' +
'Ø<\/a>' +
'«<\/a>' +
'»<\/a>' +
'"
else
let s5body = ''
let s5head = ''
let s5body2 = ''
endif
" }}}
let metainfo .= metadata
if file =~ ']*start="'
let g:zzz = 1
let doctype =
\ ''."\n"
"\ ' '."\n"
else
let doctype =
\ ''."\n"
"\ ''."\n"
endif
let header =
\ doctype
\.''."\n"
\.''."\n"
\.''."\n"
\.''.htmltitle.' '."\n"
\.''."\n"
\.metainfo."\n"
\.css."\n"
\.s5head."\n"
\.''."\n"
\.''."\n"
let closing = ''."\n".''
let file = header."\n".s5body."\n".file."\n".s5body2."\n".closing
let file = substitute(file, '\)_', '\1', 'g')
" let file = substitute(file, '\(\[#\] \)_', '\1', 'g')
" Create comment tags
let file = substitute(file, '', ' -->', 'g')
let file = substitute(file, '', '', '\n\\tableofcontents', '')
" Replace new line tags
let file = substitute(file, '\n\s*\s*\n', '\n\n', "g")
let file = substitute(file, '', '\\\\', "g")
" Title
let file = substitute(file, '\_s*\(.\{-}\)', '\\title{\1}\n\\maketitle', "g")
" Sections
let file = substitute(file, '', '\\hypertarget{\1}{}\n\\section{', "g")
let file = substitute(file, '', '\\hypertarget{\1}{}\n\\subsection{', "g")
let file = substitute(file, '', '\\hypertarget{\1}{}\n\\subsubsection{', "g")
let file = substitute(file, '', '\\hypertarget{\1}{}\n\\paragraph{', "g")
let file = substitute(file, '', '\\hypertarget{\1}{}\n\\subparagraph{', "g")
let file = substitute(file, '<.vim:h[1-6]>', '}', 'g')
" Rawlatex directive
" Ha. I didn't anticipate this - special chars inside of rawlatex will be
" escaped. Operating on string is faster than going through file line
" by line so unescaping of chars in while loop similar to pre handling still
" should be faster.
let file = substitute(file, '', '% Begin rawlatex', "g")
let file = substitute(file, '<.vim:rawlatex>', '% End rawlatex', "g")
" And the same for latexonly
let file = substitute(file, '', '% Begin rawlatex', "g")
let file = substitute(file, '<.vim:latexonly>', '% End rawlatex', "g")
" And the same for rawboth
let file = substitute(file, '', '% Begin rawlatex', "g")
let file = substitute(file, '<.vim:rawboth>', '% End rawlatex', "g")
" Lists
let file = substitute(file, '', '\\item ', 'g')
let file = substitute(file, '<.vim:li>', "", "g")
let file = substitute(file, '', '\\begin{itemize}', "g")
let file = substitute(file, '<.vim:ul.\{-}>', '\\end{itemize}', "g")
" Enumitem and enumerate are in conflict. It has to be one or the
" other
if file =~ 'vim:ol class="[^>]\{-}start="'
let file = substitute(file, '', '\\begin{enumerate}[label=\\alph*.,start=\1]', "g")
let file = substitute(file, '', '\\begin{enumerate}[label=\\Alph*.,start=\1]', "g")
let file = substitute(file, '', '\\begin{enumerate}[label=\\roman*.,start=\1]', "g")
let file = substitute(file, '', '\\begin{enumerate}[label=\\Roman*.,start=\1]', "g")
let file = substitute(file, '', '\\begin{enumerate}[label=\\arabic*.,start=\1]', "g")
let file = substitute(file, '', '\\begin{enumerate}[label=\\arabic*.]', "g")
let listings = 'enumitem'
else
let file = substitute(file, '', '\\begin{enumerate}[1.]', "g")
let listings = 'enumerate'
endif
let file = substitute(file, '<.vim:ol>', '\\end{enumerate}', "g")
" Field lists
let file = substitute(file, '\(.\{-}\)', '\\item[\1]', 'g')
let file = substitute(file, '", '\\end{deflist}', 'g')
" Option lists
let file = substitute(file, '', '\\begin{optlist}{longoptionslist}\n', 'g')
let file = substitute(file, '\(.\{-}\) ', '\\item[\1]', 'g')
let file = substitute(file, '\(.\{-}\) ', '\\item[\1]', 'g')
let file = substitute(file, '', '', 'g')
let file = substitute(file, '', '', 'g')
let file = substitute(file, " ", '\\end{optlist}', 'g')
" Definition lists
let file = substitute(file, '', '\\begin{deflist}{iii}', 'g')
let file = substitute(file, '\(.\{-}\) ', '\\item[\1]', 'g')
let file = substitute(file, '', '', 'g')
let file = substitute(file, ' ', '', 'g')
"let file = substitute(file, " ", '\\end{deflist}', 'g')
"
" Rubric
let file = substitute(file, '', '\\rubric{ ', "g")
let file = substitute(file, "", ' }', "g")
" Pull-quote
let file = substitute(file, '', '\\begin{pullquote}', "g")
let file = substitute(file, " ", '\\end{pullquote}', "g")
" Blockquote
let file = substitute(file, "", '\\begin{quotation}', "g")
let file = substitute(file, "", '\\end{quotation}', "g")
" Text styles
let file = substitute(file, '', '\\emph{', "g")
let file = substitute(file, "", "}", "g")
let file = substitute(file, '', '\\textbf{', "g")
let file = substitute(file, "", "}", "g")
let file = substitute(file, '', '\\texttt{', "g")
let file = substitute(file, "", "}", "g")
" Tables
let file = substitute(file, '', '\\setlongtables\n\\begin{center}\n\\begin{longtable}[c]{\1coln\2}\\hline\n', "g")
let file = substitute(file, "", '', "g")
let file = substitute(file, " ", '\\endhead', "g")
let file = substitute(file, "", '', "g")
let file = substitute(file, " ", '', "g")
let file = substitute(file, " ", '\\end{longtable}\n\\end{center}', "g")
let file = substitute(file, '\n\?', '', "g")
let file = substitute(file, '', ' \& ', "g")
let file = substitute(file, " ", ' \\\\ \\hline', "g")
let file = substitute(file, '\n\?\(.\{-}\)\_s* ', '\n\\multicolumn{\1}{|p{0.\2\\textwidth}|}{\3}', "g")
let file = substitute(file, '\(.\{-}\)\_s* ', ' \& \\multicolumn{\1}{p{0.\2\\textwidth}|}{\3}', "g")
let file = substitute(file, "", '', "g")
" Line
" \transition allows for easy change of transition display, eg. for
" fancy graphics
let file = substitute(file, "", '\\transition', "g")
" Comment
let file = substitute(file, "\(.\{-}\)', '\\href{\2}{\3}', 'g')
let file = substitute(file, '\(.\{-}\) ', '\\hypertarget{\1}{\2}', 'g')
" Subscript, superscript
let file = substitute(file, '\(.\{-}\)', '\\subs{\1}', 'g')
let file = substitute(file, '\(.\{-}\)', '\\sups{\1}', 'g')
" Fix address special field
let file = substitute(file, '\(.\{-}\) ', '\1', 'g')
" Replace unknown with pre elements in frame
let file = substitute(file, '', 'Unknown element \n', 'g')
let file = substitute(file, ' ', '', 'g')
" Title-reference role ()
let file = substitute(file, '', '\\emph{', 'g')
let file = substitute(file, ' ', '}', 'g')
" Class big, small
let file = substitute(file, '', '{\\small ', 'g')
let file = substitute(file, ' ', '}', 'g')
" Figure
let file = substitute(file, '', '\\begin{center}\n\\begin{minipage}{0.6\\textwidth}', 'g')
let file = substitute(file, '', '\\end{minipage}\n\\end{center}', 'g')
" Create ghost commands for custom block directives
let file = substitute(file, '', '\\vst\1{', 'g')
let file = substitute(file, '', '}', 'g')
" Create ghost commands for custom container directives
let file = substitute(file, '', '\\vst\1{', 'g')
let file = substitute(file, '', '}', 'g')
" Topic
let file = substitute(file, '', '\\hfill\\begin{minipage}{0.9\\textwidth}', 'g')
let file = substitute(file, '', '\\end{minipage}', 'g')
" Sidebar
let file = substitute(file, '', '\\hfill\\begin{minipage}{0.9\\textwidth}', 'g')
let file = substitute(file, '', '\\end{minipage}', 'g')
" Divs
let file = substitute(file, '', '\\begin{center}\n\\fbox{\\begin{minipage}{0.8\\textwidth}', 'g')
let file = substitute(file, '', '\\end{minipage}}\n\\end{center}', 'g')
" Div titles ( was already replaced)
let file = substitute(file, '\(.\{-}\)}', '\\textbf{\\sffamily\\large \1}\n\\vspace{2mm}', 'g')
" Remove rest of vim:span
" let file = substitute(file, '', '\\emph{', 'g')
let file = substitute(file, '', '\\vst\1{', 'g')
" Replace empty vim:p tags when hypertargets
let file = substitute(file, ' tags
let file = substitute(file, '<.\?vim:p\>.\{-}>', "", "g")
" Make sure no (La)TeX entity is in URL address of hyperlinks
let file = substitute(file, '\\href{\([^}]\{-}\)\\\(La\)\?TeX{}', '\\href{\1\2TeX', 'g')
let file = substitute(file, '\\hypertarget{\([^}]\{-}\)\\\(La\)\?TeX{}', '\\hypertarget{\1\2TeX', 'g')
" Unescape _ from hyperlinks
let file = substitute(file, '\\href{\([^}]\{-}\)\\_', '\\href{\1_', 'g')
let file = substitute(file, '\\hypertarget{\([^}]\{-}\)\\_', '\\hypertarget{\1_', 'g')
" Prepare newcommands from roles
if exists("g:vst_roledb")
let rolenewcommands = '%% Commands for content of roles directives'."\n"
let rolekeys = keys(g:vst_roledb)
for i in range(len(rolekeys))
let name = g:vst_roledb[rolekeys[i]]
let rolenewcommands .= '\newcommand{\vst'.name.'}[1]{\textnormal{#1}}'."\n"
endfor
unlet! rolekeys
unlet! name
else
let rolenewcommands = "\n"
endif
" Prepare newcommands from containers
if len("g:vst_containers") > 0
let containernewcommands = '%% Commands for content of container directives'."\n"
let usednames = ''
for name in g:vst_containers
if usednames !~ ','.name.','
let usednames .= ','.name.','
let containernewcommands .= '\newcommand{\vst'.name.'}[1]{#1}'."\n"
endif
endfor
else
let containernewcommands = "\n"
endif
" Preamble {{{
" This one is better for deflist but has some not nice side effects
" which have to be worked out
"\.'{\renewcommand{\makelabel}[1]{\parbox[b]{\labelwidth}{\makebox[0pt][l]{\textbf{##1}}\mbox{}\\}}'."\n"
let preamble =
\ '\documentclass[12pt]{article}'."\n"
\.'%% Generated by Vim reStructured Text '.s:vst_ver.' - Vim '.v:version/100.".".v:version % 100."\n"
\.'\usepackage[a4paper,margin=2.5cm,nohead]{geometry}'."\n"
\.'\usepackage{'.listings."}\n"
\.'\usepackage{graphicx}'."\n"
\.'\usepackage{longtable}'."\n"
\.'\usepackage{tabularx}'."\n"
\.'\usepackage{amsmath}'."\n"
\.'\usepackage['.encoding."]{inputenc}\n"
\.countrysettings."\n"
\.'\newenvironment{deflist}[1]{%'."\n"
\.'\begin{list}{}'."\n"
\.'{\renewcommand{\makelabel}[1]{\textbf{##1}\hfill}'."\n"
\.'\settowidth{\labelwidth}{\textbf{#1}}'."\n"
\.'\leftmargin=\labelwidth'."\n"
\.'\advance \leftmargin\labelsep}}'."\n"
\.'{\end{list}}'."\n"
\.'\newenvironment{optlist}[1]{%'."\n"
\.'\begin{list}{}'."\n"
\.'{\renewcommand{\makelabel}[1]{\texttt{##1}\hfill}'."\n"
\.'\settowidth{\labelwidth}{\texttt{#1}}'."\n"
\.'\leftmargin=\labelwidth'."\n"
\.'\advance \leftmargin\labelsep}}'."\n"
\.'{\end{list}}'."\n"
\.'\newenvironment{pullquote}{\begin{quotation}\Large}{\end{quotation}}'."\n"
\.'\setlength{\extrarowheight}{2pt}'."\n"
\.tocdepth."\n"
\.'\newcommand{\transition}{\begin{center}\rule{.8\textwidth}{0.2pt}\end{center}}'."\n"
\.'\newcommand{\subtitle}[1]{{\large\textsc{#1}}\vskip15pt}'."\n"
\.'\newcommand{\subs}[1]{\raisebox{-0.7ex}{\footnotesize #1}}'."\n"
\.'\newcommand{\sups}[1]{\raisebox{0.7ex}{\footnotesize #1}}'."\n"
\.'\newcommand{\attribution}[1]{\raggedleft\textit{#1}}'."\n"
\.'\newcommand{\rubric}[1]{\vskip15pt{\large #1}}'."\n"
\.rolenewcommands."\n"
\.containernewcommands."\n"
\.userpreamble."\n"
\.'\usepackage[pdftex]{hyperref}'."\n"
" Additional data {{{
let author = ''
let data = ''
if has_key(g:vst_fielddb, 'author')
let author = '\author{'.g:vst_fielddb['author'].'}'."\n"
endif
if has_key(g:vst_fielddb, 'date')
if g:vst_fielddb['date'] == 'NONE'
let g:vst_fielddb['date'] = ''
endif
let data = '\date{'.g:vst_fielddb['date'].'}'."\n"
else
let data = ''
endif
" }}}
" PDF Info {{{
let pdfinfo = ''
let pdfauthor = ''
let pdftitle = ''
let pdfsubject = ''
let pdfkeywords = ''
if has_key(g:vst_fielddb, 'author')
let pdfauthor = 'pdfauthor={'.g:vst_fielddb['author']."},\n"
endif
if has_key(g:vst_fielddb, 'title')
let pdftitle = 'pdftitle={'.g:vst_fielddb['title']."},\n"
endif
if has_key(g:vst_fielddb, 'keywords')
let pdfkeywords = 'pdfkeywords={'.g:vst_fielddb['keywords']."},\n"
endif
if has_key(g:vst_fielddb, 'subject')
let pdfsubject = 'pdfsubject={'.g:vst_fielddb['subject']."}"
endif
for key in keys(g:vst_metadb)
if key =~ 'author' && pdfauthor == ''
let pdfauthor = 'pdfauthor={'.g:vst_metadb[key]."},\n"
elseif key =~ 'title' && pdftitle == ''
let pdftitle = 'pdftitle={'.g:vst_metadb[key]."},\n"
elseif key =~ 'keywords' && pdfkeywords == ''
let pdfkeywords = 'pdfkeywords={'.g:vst_metadb[key]."},\n"
elseif key =~ 'subject' && pdfsubject == ''
let pdfsubject = 'pdfsubject={'.g:vst_metadb[key]."}"
endif
endfor
if exists("g:vst_doc_title")
let pdftitle = 'pdftitle={'.substitute(g:vst_doc_title, '^\s*', '', '')."},\n"
endif
let pdfinfo = "\\hypersetup{\npdfcreator={VST, LaTeX, hyperref},\n"
\."bookmarksopen=true,\nbookmarksopenlevel=2,\n"
\."colorlinks=true,urlcolor=blue,\n"
\.pdfauthor.pdftitle.pdfkeywords.pdfsubject."}\n"
let file = preamble."\n".pdfinfo."\n".author.data."\n".file."\n".footer
" }}}
" }}}
" Create comments
let file = substitute(file, '\(.\{-}\)<.vim:comment>', '\=VST_CreateTexComment(submatch(1))', 'g')
new
if &compatible == 1
set nocompatible
endif
0put =file
" Go through tables to tune them {{{
" 1. Create preamble of table
" 2. Remove \hline for borderless tables
silent call cursor(1,1)
while search('begin{longtable', 'W')
unlet! line1 line2
let line1 = line('.')
if getline('.') =~ 'vstbordercoln'
"silent exe line1.','.line2.'s/\(multicolumn{\d\+}{\)\(.\{-}\)}/\=submatch(1).substitute(submatch(2), "\\(\\d\\+\\)+", "|p{0.\\1\\\\\\\\textwidth}", "g")."}"/ge'
silent s/vstbordercoln\(.\{-}\)}/\='|'.substitute(submatch(1), '\(\d\+\)+', 'p{0.\1\\\\textwidth}|', 'g').'}'/e
call search('end{longtable', 'W')
let line2 = line('.')
"silent exe line1.','.line2.'s/\(multicolumn{\d\+}{\)\(.\{-}\)}/\=submatch(1).substitute(submatch(2), "\\(\\d\\+\\)+", "|p{0.\\1\\\\\\textwidth}", "g")."}"/ge'
"silent exe line1.','.line2.'s/\(\& \\multicolumn{\d\+}{\)|/\1/ge'
elseif getline('.') =~ 'vstblesscoln'
silent s/vstblesscoln\(.\{-}\)}/\=substitute(submatch(1), '\(\d\+\)+', 'p{0.\1\\\\textwidth} ', 'g').'}'/e
call search('end{longtable', 'W')
let line2 = line('.')
silent exe line1.','.line2.'s/\\hline\($\|\\end{longtable\)/\1/e'
silent exe line1.','.line2.'g/\\multicolumn/s/\(\\textwidth}\)|/\1/ge'
silent exe line1.','.line2.'g/\\multicolumn/s/\(\\multicolumn{\d\+}{\)|/\1/ge'
endif
" NOTE: this changes range so line1, line2 are useless after that
silent exe line1.','.line2.'s/\_s*&\_s*/\r\&\r/ge'
endwhile
" }}}
" Process ![]()
{{{
silent call cursor(1,1)
while search('+'.imagestring.'+e'
silent normal! j
endwhile
" }}}
" Processing preformatted text. {{{
" Not using verbatim because it is
" in conflict with minipages
silent call cursor(1,1)
while search('^\s* in $$ to show them. {{{
" \langle, \rangle would be more proper solution but they
" look too differently for my taste.
silent v/^\\mbox/s//$>$/ge
silent v/^\\mbox\|begin{longtable\|multicolumn{/s/|/$|$/ge
" }}}
" Beautyfication of LaTeX output {{{
silent %s/^\s*$//
silent %s/\n\{3,}/\r\r/
silent %s/\n\+\(\n\s*\\end\)/\1/
silent %s/\(\\begin{.\{-}}\n\)\n\+/\1/
" Compressing of titles
silent %s/title{\n/title{/e
silent %s/section{\n/section{/e
silent %s/paragraph{\n/paragraph{/e
" Shorten lists
silent %s/\\item\s*\n\n/\\item\r/e
" Because multiple spaces are meaningless:
silent %s/\s\+/ /ge
" Test it
silent %s/{\_s*/{/ge
silent %s/\n\n\s*&\s*\n\n/\r\&\r/ge
silent %s/\n\n \(\\\\ \\hline\)\s*\n\n/\r\1\r/ge
" Fix vertical space in admonitions
silent %s/\(\\vspace{2mm}\n\)\(\S\)/\1\r\2/ge
" Replace lines for .. figure:: - image first, minipage later.
silent %s/\(\\begin{minipage}{0\.6\\textwidth}\)\n\(\\begin{figure.*\)/\2\r\1/ge
" Remove special chars catchers
silent %s/@/@/ge
silent %s/[/[/ge
silent %s/\/\\/ge
silent %s/:/:/ge
silent %s/&\\#64;/@/ge
silent %s/&\\#91;/[/ge
silent %s/&\\#92;/\\/ge
silent %s/&\\#58;/:/ge
" Insert new line before \item[], it causes problems in complex
" environments
silent %s/\\item\[/\r\0/ge
" But we don't like if there is more than one blank line
silent %s/\n\n\n\\item\[/\r\r\\item\[/ge
" Remove empty deflist environment
" may be a problem when :Date: NONE is the only element of field list
silent %s/\\begin{deflist}{.\{-}}\n\\end{deflist}//ge
" Replace non-breaking space characters with ~
silent %s/ /\~/ge
" }}}
" Insert raw files {{{
silent call cursor(1,1)
while search('-vst-raw-file-placeholder:', 'W')
let file = matchstr(getline('.'), '-vst-raw-file-placeholder:\zs.*')
" Remove \ before _ - in most cases it was placed there by
" escaping mechanism, not user
let file = substitute(file, '\\_', '_', 'g')
silent s/.*//ge
exe 'silent read '.escape(file, ' \#%')
endwhile
" }}}
redraw!
" This is place for special CJK postprocessing
" What if &encoding=='utf-8'?
if &encoding =~? 'big5\|cp950\|euc-tw' || ( &encoding =~? '^utf' && v:ctype =~ 'big5' )
silent! g/^\\usepackage.*geometry}/s/.*/\0\r\\usepackage{CJK}/
silent! g/^\\usepackage.*inputenc}/d
silent! g/^\\usepackage.*hyperref}/s/.*/\\usepackage[CJKbookmarks,bookmarks=false,pdftex]{hyperref}
silent! g/^bookmarksopen=true,$/d
silent! g/^bookmarksopenlevel=2,$/d
if encoding == 'Big5'
silent! g/\\begin{document}/s/.*/\0\\begin{CJK}{Bg5}{}/
elseif encoding == 'UTF-8'
silent! g/\\begin{document}/s/.*/\0\\begin{CJK}{UTF8}{}/
else
silent! g/\\begin{document}/s/.*/\0\\begin{CJK}{}{}/
endif
silent! g/\\end{document}/s/.*/\\end{CJK}\0/
let cjkpreamble = '\renewcommand\CJKglue{\hskip -0.3pt plus 0.08\baselineskip}'."-cjk-newline-placeholder-"
\.'\linespread{1.382}'."-cjk-newline-placeholder-"
\.'\renewcommand{\arraystretch}{1.2}'."-cjk-newline-placeholder-"
\.'\parindent=0pt'."-cjk-newline-placeholder-"
\.'\parskip=1.382ex'."-cjk-newline-placeholder-"
\.'\renewenvironment{quote}'."-cjk-newline-placeholder-"
\.' {\list{}{\topsep 1ex\parsep 0ex\setlength\leftmargin{1.5em}%'."-cjk-newline-placeholder-"
\.' \rightmargin\leftmargin}\item\relax\linespread{1.0}\small}%'."-cjk-newline-placeholder-"
\.' {\endlist}'."-cjk-newline-placeholder-"
\.'\let\oldfootnote\footnote'."-cjk-newline-placeholder-"
\.'\renewcommand\footnote[1]{\oldfootnote{\renewcommand\baselinestretch{1.0}%'."-cjk-newline-placeholder-"
\.'\large\footnotesize\ignorespaces#1}}'."-cjk-newline-placeholder-"
\.'\addtolength{\footnotesep}{3pt}'
silent call cursor(1,1)
silent call search('^\\usepackage{amsmath}')
silent call append(line('.'), cjkpreamble)
" Placeholder stuff is necessary because no Vim function for
" inserting text like newline character.
silent! %s/-cjk-newline-placeholder-/\r/g
silent call cursor(1,1)
endif
" User postprocessing
if g:vst_tex_post != '' && filereadable(g:vst_tex_post)
exe "silent! source ".g:vst_tex_post
endif
" Handling of pdf export {{{
if format =~ 'pdf'
silent call cursor(1,1)
let file_tex = filename.'.tex'
if !exists('g:vst_pdf_command')
let g:vst_pdf_command = 'pdflatex -interaction=nonstopmode'
endif
silent exe 'write! '.escape(file_tex, ' \#%')
silent exe "call system(\"".g:vst_pdf_command." '".file_tex."'\")"
if search('\\tableofcontents', 'W')
silent exe "call system(\"".g:vst_pdf_command." '".file_tex."'\")"
endif
if v:shell_error == 0
bw! %
echomsg "Document compiled OK. You can view it in PDF viewer."
if exists("g:vst_pdf_clean") && g:vst_pdf_clean == 1
call delete(file_tex)
call delete(filename.'.log')
call delete(filename.'.out')
call delete(filename.'.aux')
endif
if exists("g:vst_pdf_view") && g:vst_pdf_view == 1
if !exists("g:vst_pdf_viewer")
if has("win32")
let g:vst_pdf_viewer = ""
elseif has("unix")
if executable("kpdf")
let g:vst_pdf_viewer = "kpdf"
elseif executable("xpdf")
let g:vst_pdf_viewer = "xpdf"
else
let g:vst_pdf_viewer = "no_pdf_viewer"
endif
endif
endif
silent exe "call system(\"".g:vst_pdf_viewer." '".filename.".pdf'\")"
silent redraw!
endif
else
echomsg "Something went wrong, check TeX code or command settings."
endif
silent call cursor(1,1)
call VST_End()
return
endif
" }}}
" Latex-Suite (or any other tex ftype settings) brokes *many*
" things. Load it at the end
setlocal ft=tex
if exists("g:vst_write_export") && g:vst_write_export != 0
silent exe 'write! '.escape(filename, ' \#%').'.tex'
endif
silent call cursor(1,1)
" }}}
" Auxiliary commands {{{
elseif format =~ '^head'
" Symbols for section titles {{{
call VST_Headers(text)
unlet! b:vst_first_parsing
call VST_DictTable(g:vst_headers, 'Level', 'Symbol', 0)
" }}}
elseif format =~ '^toc'
" Table of contents for file {{{
let line = line('.')
call VST_Headers(text)
unlet! b:vst_first_parsing
let i = 1
let tocc = []
let b:vst_toc_numbers = {}
let i1 = -1
let i2 = -1
let i3 = -1
let i4 = -1
let i5 = -1
let i6 = -1
while i < len(g:paras)
if g:ptype[i] =~ '^h\d'
" Real table
call add(tocc, [g:ptype[i], g:paras[i], g:plinen[i]])
" Header numbers
let header_text = matchstr(g:paras[i], '^.\{-}\ze\n')
let lvl = strpart(g:ptype[i], 1)
if lvl == 1
let b:vst_toc_numbers[header_text] = ''
let i2 = 0
let i3 = 0
let i4 = 0
let i5 = 0
let i6 = 0
elseif lvl == 2
let i2 += 1
let b:vst_toc_numbers[header_text] = i2.' '
let i3 = 0
let i4 = 0
let i5 = 0
let i6 = 0
elseif lvl == 3
let i3 += 1
let b:vst_toc_numbers[header_text] = i2.'.'.i3.' '
let i4 = 0
let i5 = 0
let i6 = 0
elseif lvl == 4
let i4 += 1
let b:vst_toc_numbers[header_text] = i2.'.'.i3.'.'.i4.' '
let i5 = 0
let i6 = 0
elseif lvl == 5
let i5 += 1
let b:vst_toc_numbers[header_text] = i2.'.'.i3.'.'.i4.'.'.i5.' '
let i6 = 0
elseif lvl == 6
let i6 += 1
let b:vst_toc_numbers[header_text] = i2.'.'.i3.'.'.i4.'.'.i5.'.'.i6.' '
endif
endif
let i += 1
endwhile
echo VST_TocTable(tocc, 'Nr', 'Title', ' Line', line)
" }}}
elseif format =~ '^fold'
" Folding {{{
let b:vst_fold = {}
call VST_Headers(text)
unlet! b:vst_first_parsing
" Prepare numbers of head lines {{{
let b:vst_fold_numbers = {}
let i = 0
let i1 = -1
let i2 = -1
let i3 = -1
let i4 = -1
let i5 = -1
let i6 = -1
while i < len(g:paras)
if g:ptype[i] =~ '^h\d'
let header_text = matchstr(g:paras[i], '^.\{-}\ze\n')
let lvl = strpart(g:ptype[i], 1)
if lvl == 1
let b:vst_fold_numbers[header_text] = ''
let i2 = 0
let i3 = 0
let i4 = 0
let i5 = 0
let i6 = 0
elseif lvl == 2
let i2 += 1
let b:vst_fold_numbers[header_text] = i2.' '
let i3 = 0
let i4 = 0
let i5 = 0
let i6 = 0
elseif lvl == 3
let i3 += 1
let b:vst_fold_numbers[header_text] = i2.'.'.i3.' '
let i4 = 0
let i5 = 0
let i6 = 0
elseif lvl == 4
let i4 += 1
let b:vst_fold_numbers[header_text] = i2.'.'.i3.'.'.i4.' '
let i5 = 0
let i6 = 0
elseif lvl == 5
let i5 += 1
let b:vst_fold_numbers[header_text] = i2.'.'.i3.'.'.i4.'.'.i5.' '
let i6 = 0
elseif lvl == 6
let i6 += 1
let b:vst_fold_numbers[header_text] = i2.'.'.i3.'.'.i4.'.'.i5.'.'.i6.' '
endif
let b:vst_fold[header_text] = lvl-1
endif
let i += 1
endwhile
" }}}
" Prepare fold levels {{{
let b:vst_fold_lvl = matchstr(format, '\zs.\ze\s*$')
if b:vst_fold_lvl =~ 'r'
for i in [1, 2, 3, 4, 5, 6]
let b:vst_fold_list_{i} = filter(deepcopy(b:vst_fold), 'v:val == i')
let b:vst_flvl_{i} = keys(b:vst_fold_list_{i})
endfor
else
if b:vst_fold_lvl !~ '\d'
let b:vst_fold_lvl = 0
elseif b:vst_fold_lvl =~ '\d' && b:vst_fold_lvl > 6
let b:vst_fold_lvl = 6
endif
if b:vst_fold_lvl != 0
let b:vst_fold_list = filter(deepcopy(b:vst_fold), 'v:val <= b:vst_fold_lvl')
else
let b:vst_fold_list = b:vst_fold
endif
endif
" }}}
setlocal foldmethod=expr
setlocal foldexpr=VST_FoldExpr(v:lnum)
setlocal foldtext=VST_FoldText()
" }}}
elseif format =~ '^fblank'
" Folding by blank lines {{{
let directive = matchstr(format, '^f\zs.*')
setlocal foldmethod=expr
set foldexpr=getline(v:lnum)=~'^\\s*$'&&getline(v:lnum+1)=~'\\S'?'<1':1
function! VST_FoldText()
let text = getline(v:foldstart)
let indent = '+'.v:folddashes
return indent.repeat(' ', 2).text.' '
endfunction
setlocal foldtext=VST_FoldText()
" }}}
elseif format =~ '^f'
" Folding by directive {{{
"elseif format =~ '^f\(block\|container\|image\|figure\|sidebar\|compound\|topic\|rubric\|table\|tip\|note\|warning\|admonition\|include\|pull-quote\|class\|meta\|raw\|2html\)'
let directive = matchstr(format, '^f\zs.*')
setlocal foldmethod=expr
"exe "setlocal foldexpr=getline(v:lnum)=~?'^\\\\s*\\\.\\\.\\\ ".directive."::'?'>1':1"
exe "setlocal foldexpr=getline(v:lnum)=~?'^\\\\s*\\\.\\\.\\\ ".directive."'?'>1':1"
function! VST_FoldDirective()
let text = getline(v:foldstart)
let indent = '+'.v:folddashes
let fill = 65 - (len(indent) + len(text) + 3)
if fill < 1
let fill = 1
endif
return indent.' '.text.repeat(' ', fill).v:foldstart.' ('.v:foldstart*100/line('$').'%)'
endfunction
setlocal foldtext=VST_FoldDirective()
" }}}
elseif format =~ '^link'
" Link table {{{
call VST_Headers(text)
unlet! b:vst_first_parsing
call VST_DictTable(g:vst_hlinkdb, 'Text', 'Link', 0)
" }}}
elseif format =~ '^slink'
" Sorted link table {{{
call VST_Headers(text)
unlet! b:vst_first_parsing
call VST_DictTable(g:vst_hlinkdb, 'Text', 'Link', 1)
" }}}
elseif format =~ '^rep'
" Replacement table {{{
call VST_Headers(text)
unlet! b:vst_first_parsing
call VST_DictTable(g:vst_replacedb, 'Symbol', 'Replacement', 0)
" }}}
elseif format =~ '^srep'
" Sorted replacement table {{{
call VST_Headers(text)
unlet! b:vst_first_parsing
call VST_DictTable(g:vst_replacedb, 'Symbol', 'Replacement', 1)
" }}}
elseif format =~ '^help'
" Help for commands {{{
echo
\ "Help for :Vst arguments:\n"
\."html - [default] export to HTML format\n"
\."tex - export to LaTeX format\n"
\."pdf - export to LaTeX format and compile PDF\n"
\."rest - export to reST format\n"
\."s5 - export to S5 HTML presentation\n"
\." ---------------\n"
\."toc - file table of contents\n"
\."head - show used symbols for headers\n"
\."link - show table of link declarations\n"
\."slink - show sorted table of link declarations\n"
\."rep - show table of replacements\n"
\."srep - show sorted table of replacements\n"
\."preproc - process inclusion commands (non-recursively)\n"
\."help - this message\n"
\." ---------------\n"
\."fold - (re)create folds in file\n"
\."foldr - (re)create folds recursively in file\n"
\."fold1 - (re)create folds of 1st level headers in file\n"
\."fold2 - (re)create folds up to 2nd level header in file\n"
\."fold3 - (re)create folds up to 3rd level header in file\n"
\."fold4 - (re)create folds up to 4th level header in file\n"
\."fold5 - (re)create folds up to 5th level header in file\n"
\."fold6 - (re)create folds up to 6th level header in file\n"
\." ---------------\n"
\."Additional commands:\n"
\.":Vsti - immediately write file\n"
\.":Vstm - display menus (no arguments)"
return ''
" }}}
elseif format =~ '^pre'
" Interpret all including commands and put them in file {{{
silent normal! ggdG
let jtext = join(text, "\n")
silent 0put =jtext
silent call cursor(1,1)
" }}}
" }}}
endif
call VST_End()
return ''
endfunction
" }}}
" Functions for auxiliary mappings {{{
function! vst#vst#VST_AuxiliaryMappings()
" VST_Ornaments: insert ornaments depending on position {{{
" Description: Depending on position and inserted character inserted before
" cursor fill ornaments: single section ornaments, double section ornaments,
" transition element
function! VST_Ornaments()
" Get ornament character
" HEADDEF:
let s:vst_headdef = '\(=\{3,}\|+\{3,}\|\*\{3,}\|\^\{3,}\|%\{3,}\|\$\{3,}\|#\{3,}\|@\{3,}\|;\{3,}\|"\{3,}\|\.\{3,}\|,\{3,}\|`\{3,}\|\~\{3,}\|-\{3,}\|!\{3,}\|(\{3,}\|)\{3,}\|:\{3,}\|_\{3,}\|&\{3,}\|}\{3,}\|{\{3,}\||\{3,}\|?\{3,}\|<\{3,}\|>\{3,}\|\\\{3,}\|\[\{3,}\|\]\{3,}\|\/\{3,}\|''\{3,}\)'
let s:vst_headchars2 = '\(=\|+\|\*\|\^\|%\|\$\|#\|@\|;\|"\|\.\|,\|`\|\~\|-\|!\|(\|)\|:\|_\|&\|}\|{\||\|?\|<\|>\|\\\|\[\|\]\|\/\|''\)'
let curline = getline(line('.'))
let character = curline[len(curline)-1]
if curline =~ '^\s*$'
" Temporary thing, to by-pass headchars test
let character = '-'
elseif curline !~ '^\s*'.s:vst_headchars2.'\+$'
return ''
endif
let prevline = getline(line('.')-1)
let nextline = getline(line('.')+1)
if prevline =~ '^\s*$'
let prevline_is_empty = 1
else
let prevline_is_empty = 0
endif
if nextline =~ '^\s*$'
let nextline_is_empty = 1
else
let nextline_is_empty = 0
endif
if prevline_is_empty == 1 && nextline_is_empty == 1
" We are to insert transition element
if &tw > 50
let trans_len = &tw/3
else
let trans_len = 20
endif
if curline =~ '^\s*$'
" Current line consists of only white characters. Try to find last
" used transition
let last_trans_line = search('\n\s*\n\s*'.s:vst_headdef.'\s*\n\s*\n' , 'bWn') + 2
if last_trans_line == 2
let character = '-'
else
let character = matchstr(getline(last_trans_line), '^\s*\zs.\ze')
endif
endif
return repeat(character, trans_len)
elseif prevline_is_empty == 0 && nextline_is_empty == 1
" Insert single ornament
let prevline_len = len(prevline)
if curline =~ '^\s*$'
" Current line consists of only white characters. Try to find last
" single ornament section
let last_single_ornament = search('\(\%^\|\n\s*\n\|\%^\s*\n\).\{-}\n\s*'.s:vst_headdef.'\s*\n\s*\n' , 'bWn') + 3
if last_single_ornament == 4 && getline(1) =~ '^\s*$' && getline(2) =~ '^\s*$'
let last_single_ornament = 4
elseif last_single_ornament == 4 && getline(1) =~ '^\s*$'
let last_single_ornament = 3
let real3 = 1
elseif last_single_ornament == 4
let last_single_ornament = 2
endif
if last_single_ornament == 3
if !exists('real3')
let character = '-'
else
let character = matchstr(getline(last_single_ornament), '^\s*\zs.\ze')
unlet! real3
endif
else
let character = matchstr(getline(last_single_ornament), '^\s*\zs.\ze')
endif
endif
if prevline_len < 3
let ornament_len = 3 - len(curline)
else
let ornament_len = prevline_len - len(curline)
endif
return repeat(character, ornament_len)."\n"
elseif prevline_is_empty == 1 && nextline_is_empty == 0
" Insert double ornament
let nextline_len = len(nextline)
" Unfortunately this line borks undo history
normal! 2"_dd
if curline =~ '^\s*$'
" Current line consists of only white characters. Try to find last
" used ornament
let last_double_ornament = search('\(\%^\|\n\s*\n\|\%^\s*\n\)\s*'.s:vst_headdef.'\s*\n.\{-}\n\s*\2\s*\n' , 'bWn') + 2
if last_double_ornament == 3 && getline(1) =~ '^\s*$' && getline(2) !~ '^\s*$'
let last_double_ornament = 4
endif
if last_double_ornament == 2
let character = '='
else
let character = matchstr(getline(last_double_ornament), '^\s*\zs.\ze')
endif
endif
if len(curline) == 0
let correction = 0
else
let correction = 1
endif
if nextline_len < 3
let ornament_len = 3
else
let ornament_len = nextline_len
endif
let ornament = repeat(character, ornament_len)
return ornament."\n".nextline."\n".ornament."\n"
else
return ''
endif
return ''
endfunction
" }}}
" VST_RotateOrnaments: rotate characters in ornaments {{{
" headers
function! VST_RotateOrnaments()
" HEADDEF:
let s:vst_headdef = '\(=\{3,}\|+\{3,}\|\*\{3,}\|\^\{3,}\|%\{3,}\|\$\{3,}\|#\{3,}\|@\{3,}\|;\{3,}\|"\{3,}\|\.\{3,}\|,\{3,}\|`\{3,}\|\~\{3,}\|-\{3,}\|!\{3,}\|(\{3,}\|)\{3,}\|:\{3,}\|_\{3,}\|&\{3,}\|}\{3,}\|{\{3,}\||\{3,}\|?\{3,}\|<\{3,}\|>\{3,}\|\\\{3,}\|\[\{3,}\|\]\{3,}\|\/\{3,}\|''\{3,}\)'
let s:vst_headchars2 = '\(=\|+\|\*\|\^\|%\|\$\|#\|@\|;\|"\|\.\|,\|`\|\~\|-\|!\|(\|)\|:\|_\|&\|}\|{\||\|?\|<\|>\|\\\|\[\|\]\|\/\|''\)'
" Make sure we are in position to perform any actions
" This is more general regexp, could match several
if getline('.') !~ '^\s*'.s:vst_headdef.'\s*$'
return 0
endif
" Get situation: double/single ornament, transition
let prevline = getline(line('.')-1)
let nextline = getline(line('.')+1)
if prevline =~ '^\s*$'
let prevline_is_empty = 1
else
let prevline_is_empty = 0
endif
if nextline =~ '^\s*$'
let nextline_is_empty = 1
else
let nextline_is_empty = 0
endif
if !exists("g:vst_headers")
call input('No knowledge about headers, run :Vst head')
return 0
endif
if nextline_is_empty == 1 && prevline_is_empty == 0
" Single ornament
let a = 0
endif
" Make sure we have data about headers. Note: updating of data will be
" done manually or updated at the end
endfunction
" }}}
" Auxiliary mappings
inoremap o =VST_Ornaments()
"noremap o =VST_RotateOrnaments()
endfunction
" vim:fdm=marker:ff=unix:noet:ts=4:sw=4:nowrap
VST-1.4/doc2/ 0000775 0000000 0000000 00000000000 11456723370 0012671 5 ustar 00root root 0000000 0000000 VST-1.4/doc2/test.png 0000664 0000000 0000000 00000015400 11456723370 0014356 0 ustar 00root root 0000000 0000000 ‰PNG
IHDR È d t4 pHYs H H FÉk> ²IDATxÚí{¬mUuÆ÷¸¶ilÒšÆ6i›Æ6}¥5MmÛ´þc›–sh‰Á>¬-µ©%ÖGKQ ”^”\”WË9§"(¡<DAŠByUD¤€€ç lAÉÙ£Ü{ÎÞkí9ÆøÆœc®½ö¾ç B¸›½æý1¿ùíoŽ¹½ýíÌ««ƒ ƒá`¸õOÞóïjü÷ÔgÆÿ¹±çßIùÌè“í?%å*Â÷ Ôúž
h´¤Ž$ý
ÔU|4ÚŸ!u$2ï¡\ÖhGµ¡F§aWÑøgh0dO-¥Éo@£%u$
Æ*$MCãÖ¢ášYiòÔµ|4°*jŽ AïxtxòwöQ%ÀšZ# †C+èdÑs» I @Ã!‹äœZ£k™BÃí‘ â»‘A_‹ÉèZù4Ð¥ß4
Dh¹i--ézÆh¤Gb Aªží
Ñæ ²TÈ"Ö3ýÛ6~é©¥ÖÍÆt1 ÇX‰(+’íÂÐéMêH´ u ~OŠ @ƒ¥É*è±ÉIuhŒF/‹rAçÊb®CÇeqTѲ¸õyn¦t‘ð,œ4ð†i8vWìA÷=å·WÕËà¦Ô*è SJ5q ed½]Ðät
h‘ihm=JÃ.èyöÒH tš|]QŽÃ'‹4È M#=’"ÑIÃÇdü×ÛÁöýýžØ¸yy¦4?ó ÍÅq(8¸Ìa«VW™ â8²3AÒG;L™Z™ $4)è‰:Ž|˜øfd‚¬1)ÊÛJï¼í¹ [q”9G«Œ 6íPq …™ (ÐZ‰x2ATSÓ;F±;˜#‹Ã±Ç“úhx<).‹94¶>C:Ÿ'Åe1UÏ.Ydˆ ²øì?>ºšJŽxM).‹Å8„’ò§`>êÔjåù4âdÑšZ*
ãg‹/œ Á:“âL0‹FŠ|N
6O™ 2³²3A:ôóÿ÷ßZØóÕV^
*EM-Ë?[BBAsj¡rS1„–Š½#ôìSWJÁ¸(Ä G
Ñ…E¤`U3A:üß=ýá%¨Œ²¶!“:êëß™~(Xw2sOÖé8&®Â“cŽö_"
’iD9Žrÿ…8Žnü¤Ü!3«Ôµ™¤ZÕz÷eϼô›«Àeðþün¦Ý©\¡¶Ì`ÿT"yý;¹)X´'Mt„'õ,œ53A'ue‚®Y‘FâW‹Ï“æ¤`
:â××®}pÁ(èÐPP߬ŒQ VÑ[]ºQÝÇLÐ’›ðLMŠ ‹Þ*É¡aÕ¼µ„§ëPh™2³ÊiÀ†#Г¦ Ç‘ŸX}õKËqÄù/
‡O«8Þº
É4PYŒp "PÇ1óþK,ú Î]ÈL¾™eËM½=Yƒ %h˜9xó›aÃAïýù§ ¹À!—HPk T"½k MH.*}ȳúw@& NM`«„Ó#Ù>ÓçÛ§î°}§u¯Z~ê°¯-(8 ]„ÀÙ8reÑ*èÊgú(—†àIYãæ¢1@i`²hO\Yl GÜV‰UÏe
ÃÕÛ§9w‘ð{ÒràÌ"ßVIbQ¡?ñäß·¤àØ=‘¢CÁZ ÃóÔ?8» Ñ bù4¢ GÕLFÿ—çd‚]óò˜µÙîú-¹éM&˜¬çÉÐýèžX¹gµ*ŽÇáÀá8°•3ë™
äOÁ:ÏY‰-¾¥)˜]ÐU3A±æE«
Ðq â;“™ Ô)Fïáã¿q÷B6Ž˜PÐ0¥lAA ‡ß¢ÏvÿNy7S®,úhL½z|$/‹òR¡È¢RÏ™}†cs¦Do•Ècd‘ŽyßÿÜð_K*ú>ôO7GÒ«3}"
ÏÔ£Ëß1`®œ ¦‹ÞM£IÞØ™MÖ†oáŒÜ*É¡a¶O™ ’‚u” 2¤3tìÆ£qÇjkª kEW¡ â8âLi«8§–QüFõlg‚rѧÚ߬L Ñr ÀѦ™ úd±æ.$ï™G»ôÁC yü«
>K}K7eµ[èò_ÅŽ£ÿÕ¼Væž,Ef‚Óß…ôg‚9ŽC ! AG™äl@‚9…I7í;åÍLH…lÝA:nõá#o_òâP¶øúwfþLŸÉÍCcb$,®H\—†c©Øk2AÌM¤gŠ]ÏýËS×rg‚h
Æ
ÚõÖ‡^tÛšXÐ"3Áatü^‰<æÒ½ljY™ VÐ4Hâ†þ,ͧ!K€gjmÑ0Z¦å8üžÔt Àô4ùRÿ…ÊbÏÚ§éøG <ûÖ…‰‹8Šð_ŽP°²ãèÆ!S«ÃL‡âµ²3A˜ÉÛgúò„ vè,Ñð-1²Øh pÏ×o¾yÍ…c½çh‚ŠƒrqDu —í•L½(è럖$Ž§.9[%ÁíÓ¤/œqíÓH
æß*ÉinÑ “þäþ×Ý´ |EÝÖ¸*¡ {„f÷7»[ã¸
ÌqØS«j&HÒêd‚˜øvš SK“ «ž“4Ìz®óN2AÖi$«ˆNþò?}ã’8ÜüêàPÜ8Ô‚ŽÞ…,÷_í‘€þËá8䂞ƞ,"SÊá#èùš' YßûÝóö 6d‘þeŸûvÞ°–Ê´ûwÊqdÈ¢XÐ=êŸf‰†ÏqäÒ0eQ|ïwH&:èí3}ékÅd‚Ú ¬œ Ò©×Ýûã×/€8TõeßZQéuCœzñw`(X¯Q°8D–ŠyÊÇ1ƒ™`sAâH¿ ¥h Ud‹o•LNÿ»ÏûÜ’þ¡DA— —§PÐt &2ÇÒ(v Eck$$Ó@e±4Ä·J¦¿ Yî¿,¹éÿbƒ}äÓw½â³kc—)u ½*þ Â÷|~â¡®XùiXâ[3´eQ¾ƒ½íßÙ*èÙyβT”yR×™¾êÐ9YE¥%“â[%Í‘œñkwÞví‚q »}¦RL"Ðq´Ñ{VÎè§t“ b²èš
{j93ÁÍ©b.H¸ ÷J™0ö
œG#E>àd´Tô5lÄ+‹ÿvÆíÇ^¹0Cý;Æ8ÙÆQ&‹ Š +ïßQi˜Axs$ñ²(téV‰gá¬óÿV‰|³ Ëq€²XNÃ/‹"
*E:óÅÿùS—/›S+k•àq >Ç‘‹C^‘úØ?í’ÅtÑ›]ºUâY9ëöO7GRÐ ËïQ&ÈöRÑ·
d‚–á ³>të…—â@ü—¶ja8Lõ§VÕPP¼…›S§Qæ8þüÍþûZkªÄâH¡÷ìBb8ÒkEäF5¸WÂé‘hâ›C-£~d‚ OŠ;Ž´Œe‚f=O§:4@Ç‘¸ƒÑþK«çêíÓܼÖ÷®/~l QŽ#ì™
ìÂѺVŒÿB GH&HÈVI}ÿ…8Žrÿ…8ŽŸìÎv=—ù/M 16“úÇfJy
ƃ!}âéÿÔ²QÐñ\~ºD¦Ú¿ƒ—XÐ5»™Rå(Ðh4ã4Ò#ékÿNy7:µPOŠo•x]Xw™ 2³¢eQ]89Mc$Xç¿å ?{þšŠ>Gâ‘û¦,·0î™
vAwõLKnÜ™ ñ½z¦è8´kå'¤–øvÖ>Í(·HOÚ‹öiºà¡ë?ýÉÉ—P`à€P" ‡Ã)Ýÿ…8ŽÙìŸ :wfqÿåa2íLP«%€FûU,]+(TiØÜ*d‚úÌ¢ _ÿù}Î[ž÷Pmp™¡`ëZžŸ6)ŽÃ¤‘.#ñ
zUO&´F2ÕLÐ)‹ >YlŽ$r«ÄªgH§á–E«žé¢»®»÷ãkêeòûw\8ÄŸ- Ãq¦´n7&‹öÔÊ•ÅæHzØ?Í
¶îW}4:kŸ&m‘P„F¸ƒ·O»h´ÈÓÅûömç,@ÃõïL!t9
}`£ 7Ñ—¦`ž´(L¼A¯f
ÖÃL¨ù f=Ç{Ò^g‚tÉ-× Ï^ H·°æ30õMO•úº»`(¨ÐðÉ"¸ ©9ŽŠ40Ç‘ÉÜf‚ÐAôŽŸì.<ÓµÇ'ÌŸ„—þÁÕ'¹æÂQì8ÂpD9Ž~½%XY»/Õú§©T7¿™ Çá_$äz.•EÏÂ9Sgú RùH ]víg~ñ£‹[8|SK+zëîÁÁ¾1CÁÍ‚& ‡VÐóz¦ov2AdjÍy&È
%7¸‘ŸF»ž;Ìéòß¾òŠ•eq(vÑ{V‰Ù í[ñLT[#dý*¸'Ô?ͦ,R.Àþih‘ˆ9-[×aU¤Ñ@ Kn
h$ëyŒ]qñ¼´@™ŠÿqX`Ê"uå¿ú“ öçdBf&ˆ:Ž0~ÇÑm&¨UHpû5ÿv©ØA¾/A[%tÕKÿãëg,‚8l¡ÑV¤Èn¦öH¶®:´DbúwÊ»™|KÅÜé£
€ WÈÝ4Š2A–ÇPç™
é;Ø›L>sÎe}dY@_«c¸ü™
²ÜT韦²Ža½õ®¨c˜QrÑ{¦VÎVIzØ*Ñj#Êq`™`iû4*‹‘™`ÅöiBª(IƒuCºæ%—¾à´µ1ôCµÏv ¹Õ¾¬›P™Z˜ÿÒh Ž£›LP»ƒ=É
Ç‘zïwMj™A8J"+ë&Dt ;¤kO¿ä´SŸ„» ;
ÇaÝÂâMYÚaŽÖG#=’"Yd”F¾,æŸpD§V¼,bõÜqûŽå8iø G¾,îñ¤¤FкîÇ.þÕS–M …ºˆ™RFpØPöªþi³ ãž©`tWýÓ©k¹3AógËh$ÓÎ=[%[Ÿ7ƒðœ¬z&È
úÜ®‹®9iÍÄá›Z¹8f+D¦V’¡Lú• "rxR.JÁئQ” †ÒˆJÁæ)D ‡r¾…®ÿÁ ÷?q11”
Í‚ k·0ÞÉ ½' :@5QŽ£ÿ…8Vä¤ÌqBc9H§ð¶GöÑ°™l.ö7 uÁC ^ XB€ØÔÊ‘ÅæH¦Ù?–2µÌ!¤ ·ÏôÁFh KEé>uL&¨ÝÁ™Ë-ÃA_øÞù‡ ¿žœ*8h0ŠÞÆá›ZI ÐÍónTç§`c4Ä#Jå)Ø
ÆeQ¾ƒÿ‹q>Ç‘KlŸ&Ÿ,‚4Ô*ÒÈçÓ°ëyŒ<Ýþª3ع(~Ý+‘oaGýÓ›èÙ3µ&p@B£I€UÐOʨθÂL°ñÞïÈ«Bz“ Šó%04ë¹0tµïL/ ÖWnúè µìÁaáÙ¡ XFMç8BBA}X&(t·ÏT@¸ÍS&ˆ¤`NÿÅÚHri´FBò]Îõ_((Ã1úvÇﯜõžõŽ(ÇÑͦ,*‹e›²“9z²;§ï sO–Âý—UЙŽcÄ$¿›Ü·TÌà™>ˆIå#}tçÕË/?rQEïøpd¥`ÖôfAO<Ù³VlŸéÓ l圷
õ4äZ)ØfìО)¸ÐXrS%¤»^~ÆMÿ´lƒsâHt_CÁ浊BA‡,†xRÓqÔ¡¡´ÇqŒ
1 „[ Ô?
Éb„ã(÷_Ú œÿ•¬çñ7?ß}Ñ¿ pøº G”ã¨à¿`p8Ôsù[#Q‚p[ºñ_ˆã(Û¨žj&ÈíŸöÑþ+Mq ó” ¦G²û4 FC_`gV A÷þÊéO ¶(BÉ=šÃ!4É¢çöç#ýWJ>Ðé=_ý;åÝLèÔš¨FòÐÉ+w½4šäóS°ÄUØ Q,‹Øì®óŒE‚î;û´>d%1”˜½l¨Ò?-tAÇ0åÒ@§–±9ÀZAû<éôû§‘¥"w«ÄÝ?
H€FÃç8ri4ÉwÖ>
Ϭ ”AÃ2 ôµŸ9õÅï\Ѓ¦8ƒ>9ôøþiJ™ãpnT;§F#]Ðu:ãz bŽƒâh`â‹ïS›UÄ
›ê¿4e†¥á7 {¾™î?õ”s^qX`t¡ Óq”oÊ&‹ž<4|²X–‚d‚¬q³%À*èY>™P¾'‹8Žnž©€0 lß!„ÆØÿE¼èäß=hô“°¸G¸…ÑÏTÇ
ChböJJi M†ã(¦"‹ØFuiÿ´}ƒd‘¬¥¢›L°yN3ÁÖ‚T!ôÐ`ƒ}ã¸oýûuá29qó
¦oaÐF5IÜü4dñõe‚¾“ ò].OÁ&þt3gy$¶ÜÄÓð;Ž VÍc3««L1 žt÷ùúæ Nxã;R? g44 Úã8,ñÝHá ôù4PYÜ~²{JFÑŸ6ªø’Lq EþËr 4¢ G–ÿb=ôž¿mÅÄ¡tüÑ„Rÿ…8ŽJ¡`FAR˜ð$“iöï”w3aLÜý;2öΣ‘ IClÑ[%˜Ð¤*¿È“²Aƒ ~öøcþn]Âa¼ø{ûL_Ì^‰gj5h0V"®L°"
{´¦ c…<µl °i$ï‹øÞïüÐÈ4ì;úL£žó·J†ôƒvýä[¸.B8x‡Ïqdã`G”ãèUÿ4ÉÅå8Êýâ8ºñ_ˆ”e‚øKpl:@nºó_–Üd‚ôèÇ]pàŠ UßÒ¬·¡ QЕ2AñµW¾ ó_‘ðäß«8 ß…ì]&˜èÔŸ—“ í;,1Ù¤÷Ø›?øÊ7¯‹ƒèüL $4†,òlžé íߑˈR¯\OIC+èf_R™'Åe1ŸºpÆË¢\ÏnYdœF™,¶uCaB?pì ³¨à@VNYn8’SÅç8̽.‘(èܬ¬WųrÖ¦‚Uô6
ßÔ‚hOÜï]Ÿ Yó"
¯çšqÝd‚ˆá0u†¾ý—Çüí_¯ÌD(ˆ€›z(˜xä¾^Ð…4X£9ŽÄ $
K|û• bâ‹ïSog‚70 Õsúˆ=ùÕ÷=÷Æõl .z[ãÈ#…>g2ºQ0ßq”û¯&ùZ{²žL°¸‡%&¸,¶ï˜;³ÝµO[Ùñ ¶O{e‘žÞïè]oØ*è™èŸfý*Å¡ ˆÞ—‚UËOìŠÛ¨iÏtÝ‹2A@| R0³ž 3A`fu“ ¦®•¨"úÎ;_òúñ†…‚,á°ÔW,è ÖA(hÒ WN´Zt ØÔŠHÁæ)ܼVo3ÁdÉ"Õ¡‘ ‰ßpì¡a 4½ò¨KX È·ýA‘
Æ8ȹ¦–Ÿ†\ˆñŽ£|O™ZNÿ¥áB£²ã(÷_ˆãó_f=÷ãdB`&HëW½÷ÿjßNCAJAÿNª ‰ØÑÍ„Ébj$ÛgúlY´
ºê™¾ùZ4ÚõÜ陾ÁP;ßÂ^e²˜¸ƒôÝß<òž×®dàðMTq`7/&DÖŠ¸½’|6“–'åZ4,ñE7\ž”n"
¶*ß*іزl©Ø›Ú§íz £Aÿû©#ÞúšuJGýÓJÑ[·°¸Z}Å$zÇú/TKû§í©5…Lñ•‚ÍS&ˆpShÐäH4ñ
Éy8Ò³¿üî?ßW,èš8,õES°vA#kE¼ÿ’ ::›§L•Å d67´‰
pg6«›‰&ýmß)wè-nôÜ™‡Ÿø§+êÅúÚ¿3¥g*Ðs´^!@ih-’g/
Lm¡É•Å¶pÄm•Xõ\Ö>íkß™óöéÑH€_-c4,ÃAßÿéÃ~áÕë. VÑc+'±OhR8е¢/¯ ï"Däf†3AvÐ Œ†ïdB.(Ç1!4JŽUQŠ2³¦’ Òó§ rùþûŠC±Õwš¡ VЕBA
ãgK]È^e‚@®Ñ@ Çìd‚¸ÿ£Á>¾™•KC&ï3 #ߤ3«
Úø‘wýÑ«VÔËä8ŽbÿMÿÅí‘L»:³Ç,hÿN7ýÓq²hM-`«ÄxïwWOó¤8
lf5iŒ}†ƒiL4B· Öðß¿ß3Æ$ß>Ó§Ïî¬q0¾•sÚ™ =Úìg*@ŽcØ8‚^ù™
ªÜÌg&ˆ,•2Áÿî„<Ü–,f IEND®B`‚ VST-1.4/doc2/vst-s5.txt 0000664 0000000 0000000 00000007034 11456723370 0014577 0 ustar 00root root 0000000 0000000 .. This is a comment
.. Use ":Vst s5" to generate the HTML for this document
============================================
Vim reStructured Text
============================================
:Title: Vim reStructured Text - A Quick Introduction
:Author: George V. Reilly
:Date: 2006/05/12
What is VST?
============
`VST `_ is an easy way to produce:
* HTML
* S5 Slides, like this document
* LaTeX and PDF
from `reStructured text `_: plain text
with minimal markup.
The powerful `Vim `_ editor is used to prepare the
material.
Please read the _`source` of these slides to see how the effects used herein are
achieved.
Simple markup
=============
+ Bulleted Lists
+ Numeric lists (nested)
#. **Bold** text
2. *Italics* text
#. ``typewriter`` text
+ Subscripts, H\ :sub:`2`\ O.
+ Replacement -- |VST| -- of text.
Blockquotes
===========
You can embed blockquotes inside your text::
Simple markup
==============
+ Bulleted Lists
+ Numeric lists (nested)
#. **Bold** text
2. *Italics* text
#. ``typewriter`` text
+ Replacement -- |VST| -- of text.
is most of the text of the previous slide.
Links
=====
VST supports a variety of hyperlink notations.
* Starting points: `What is VST?`_
* `External links`_
* Internal links, such as `source`_
* Standalone links, http://www.vim.org
* `Embedded URIs `_
The full effect of these links cannot be seen in the S5 slides.
Regenerate with ``:Vst`` instead.
.. _External links: http://skawina.eu.org/mikolaj/vst.html#lexternal-links
Images
======
.. image:: http://www.vim.org/images/vim_header.gif
:title: Vim
:target: http://www.vim.org/
.. tip:: You can apply a variety of attributes to images.
If you need really fine control, you may need to use ``.. raw:: html``
Simple Tables
=============
== == == == == == ==
su mo tu we th fr sa
== == == == == == ==
1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 29
30 31
== == == == == == ==
Rich Tables
===========
+---------------------+----------------+------------------+
| Cells are | by bar with | | |
| separated | spaces around | |
+---------------------+----------------+------------------+
| *You* may use | markup, | included. |
| **inline** | links_ | |
+---------------------+----------------+------------------+
| You can use various | - like lists | VST will |
| types of structure | | interpret them. |
| elements:: | + various | |
| | | Even paragraphs. |
| Welcome to world | - embedded | |
| of preformatted | - one into | 1. And |
| text. | other | 2. not |
+---------------------+----------------+------------------+
| Text may span across several | |
| columns. Cell can be also empty -> | |
+---------------------+----------------+------------------+
Conclusion
==========
VST is an easy way to produce marked-up documents with easy-to-read source, in
Vim.
This slideshow displays only a few features of VST. Be sure to read the
`manual `_.
.. |VST| replace:: Vim reStructured Text
.. vim:set tw=78 ai fo+=n fo-=l ft=rst:
VST-1.4/doc2/vst.txt 0000664 0000000 0000000 00000242737 11456723370 0014265 0 ustar 00root root 0000000 0000000 =====================
Vim reStructured Text
=====================
:Author: Mikolaj Machowski
:Title: Vim reStructured Text - HTML and LaTeX output
:Keywords: Vim, LaTeX, PDF, HTML, XML
:Version: 1.4
:License: GPL v. 2
:Date: 4 Nov 2006
For a long time Vim_ users were asking for "real" export to HTML. This is,
I believe, first real try to achieve this effect. This is Vim version of
reStructuredText_, popular Python_ language documentation tool (so I borrowed
parts of its documentation).
.. contents::
:depth: 3
:class: new
Introduction
------------
*Structured* means Vim script recognizes some patterns and translates them
into form recognizable by WWW browsers. In fact, Vim creates quasi-XML
form which can be exported into HTML and LaTeX.
Major office suites OpenOffice.org_ and MS-Office_ can import HTML
(KOffice_ also can do this but results aren't good) and save files in
their native formats.
Download
--------
- Scripts themselves and docs in txt form: vst.zip_
All forms of documentation were created from the same txt source without
**any** corrections:
- HTML documentation: vst.html_
- PDF documentation: vst.pdf_
- LaTeX source of documentation: vst.tex_
.. _vst.zip: http://skawina.eu.org/mikolaj/vst.zip
.. _vst.html: http://skawina.eu.org/mikolaj/vst.html
.. _vst.pdf: http://skawina.eu.org/mikolaj/vst.pdf
.. _vst.tex: http://skawina.eu.org/mikolaj/vst.tex
.. _archive:
Installation
------------
Put archive ``vst.zip`` into your ``~/.vim`` (Unices) or ``vimfiles``
(MS-Windows) directory and unpack it there. It will create files::
|- doc2/vst.txt <- documentation
|- doc2/vst-s5.txt <- example of S5 presentation
|- doc2/test.png <- to complete documentation
|- plugin/vstplugin.vim <- small plugin file with commands
|- autoload/vst/vst.vim <- main script
|- autoload/vst/myhtmlvst.vim <- examples of macros
\- autoload/vst/s5ui/* <- S5 style files
Usage
-----
Transformation is called with command::
:Vst [{format}]
Where ``{format}`` is format of exported file. Format argument is
optional and without it default value (HTML) will be used. Argument name
is case-insensitive: HTML, html, Html are equivalents. Formatted file
will be opened in new buffer without name.
``g:vst_write_export``
Boolean (0). If true, write file immediately with extension specific to
export format (html, tex, xml). Overwrite existing files without warning.
How to set it read ``:help :let``.
Second command::
:Vsti [{format}]
Instantly writes file with extension specific to export, overwrite existing
files without warning.
Third command::
:Vstm
Is calling menus.
Project file
~~~~~~~~~~~~
User can write variables specific to project into special file ``vstrc.vim``,
located into the same directory as processed file. This is regular Vim script
file which will be sourced at the time of export.
Export to HTML
~~~~~~~~~~~~~~
These commands will create XHTML 1.0 file::
:Vst html
:Vst
Vst command (with any export argument) accepts range::
:[range]Vst {[export]}
When file use exclusively lists starting from 1/a/A/etc. doctype is Strict, in
other case it is Transitional.
From special characters/entities |VST| handles at the moment::
<, >, &, (c)
Results in: <, >, &, (c).
List can be extended on request.
.. _vhp:
``g:vst_html_post``
String (empty). Filename, sourced after whole processing. In that file
user can put specialized formatting commands, replacing custom or export
dependent templates from replacements etc. For examples check macros_
section. How to set it read ``:help :let``.
User CSS
````````
User can manipulate how CSS will be attached by combinations of these two
variables (how to use Vim variables read ``:help :let``):
``g:vst_css_default``
String (empty). When unmodified default CSS will be included in HTML file.
When non-empty default CSS will be written to external file. Existing file
will be overwritten without warning. If equal to NONE (case sensitive) any
reference to default CSS will be skipped.
``g:vst_css_user``
String (empty). When non-empty link to specified file will be included.
Default CSS is in separate file in autoload/vst/default.css so it is easy to
make global-local modifications.
Export to S5
~~~~~~~~~~~~
Command::
:Vst s5
Will create S5_ -- Simple Standards Based Slide Show System. XHTML file steered
by JavaScript and CSS created by Eric Meyer.
.. _S5: http://meyerweb.com/eric/tools/s5
Not every document will be good S5 presentation. All elements but table of
contents are supported but not every one will be good thing to place in one
screen.
S5 document
```````````
File should begin with first level header. It will be title of document. Each
slide will begin with second level header. Author and date to place in footer
will be taken from appropriate fields of field list.
.. Tip::
- it is unwise to use more than two levels of headers
|VST| provides predefined classes. Both can be introduced by class_ or
container_ directives:
``handout``
Elements marked with that class will not be seen in presentation mode,
only handout mode.
``incremental``
Elements marked with that class will be displayed gradually, when using
normal forward. This one can be also introduced as a role -- usage of this
element is easier with `default role`_ directive.
Good example of S5 document was prepared by George V. Reilly and its text
form is included in tarball (doc2/vst-s5.txt). Result can be viewed here__.
__ http://skawina.eu.org/mikolaj/vst-s5.html
Export to LaTeX
~~~~~~~~~~~~~~~
These commands will LaTeX version of |VST| file::
:Vst latex
:Vst tex
Document will use ``hyperref`` package and it will be fully hyperlinked.
It is better to compile it with ``pdflatex``, directly to PDF than use
pure ``latex``.
.. _vtp:
``g:vst_tex_preamble``
String (empty). User can define his own command (to use in
`raw latex`_) or change some defaults. Should be absolute or relative
path to processed file. Contents of file will be included with
``\input{}``.
``g:vst_tex_post``
String (empty). Filename, sourced after whole processing. In that file
user can put specialized formatting commands, replacing custom or export
dependent templates from replacements etc.
Current differences between HTML and LaTeX export:
- 2html is treated as ordinary preformatted text
- custom roles are ignored
- right/left floating frames are ignored
Export to PDF
~~~~~~~~~~~~~
This command will immediately compile PDF document after creation of
LaTeX source::
:Vst pdf
Additional tuning of this command with variables (how to use variables read
``:help :let``):
``g:vst_pdf_view``
Boolean (0). When equal 1 immediately show result of compilation.
``g:vst_pdf_viewer``
String (default for unices is ``xpdf``, for MS-Windows empty
-- properly setup system will take care about choosing application).
``g:vst_pdf_clean``
Boolean (0). When equal 1 remove auxiliary files of PDF compilation
(including tex source -- use with caution!)
``g:vst_pdf_command``
String (``pdflatex -interaction=nonstopmode``). Value of this string will
be used to produce PDF document. User may need to modify this variable,
especially if document needs some preprocessing.
Export to XML
~~~~~~~~~~~~~
This command will produce XML-like code::
:Vst xml
For debugging purposes.
Export to reST
~~~~~~~~~~~~~~
This command will remove incompatibilities with reST::
:Vst rest
- identify option of images_ and figures_ will be deleted
- figalign option of figures_ will be deleted
- in Vim commands of `option list`_ leading colon will be replaced with
``--VIM, :``
- replace non-breaking space with plain space
- replace 2html directive declaration with '::'
.. Warning:: This export can result in losing of some formatting.
Auxiliary commands
~~~~~~~~~~~~~~~~~~
|VST| script provides set of auxiliary commands to make easier editing
of bigger files and especially navigating through them.
.. _headers:
``head``
````````
It is possible to lost orientation which type of underscore was used to
mark certain level of sections::
:Vst head
Will show small table with level name and symbols used to mark them::
Level Symbol
h1 =========d
h2 ---------
h3 ~~~~~~~~~
h4 +++++++++
This is result of ``Vst head`` for this manual. Letter ``d`` at the end of
ornament shows this is double ornament.
.. _contents:
``toc``
```````
In longer text documents it is very easy to be lost::
:Vst toc
This command will present table of contents for current document. Here
is fragment of table of contents of this manual::
h3 ~~~~~~~~~ 5.3 Inline markup rules 553
h3 ~~~~~~~~~ 5.4 Special characters 587
h3 ~~~~~~~~~ [[[ 5.5 Roles ]]] 625
h4 ````````` 5.5.1 Predefined roles 652
h5 ''''''''' 5.5.1.1 Title reference 658
h5 ''''''''' 5.5.1.2 Subscript 670
It gives plenty of information. First column is name of section level; second
column shows decoration for that level; third column are section titles with
numbers of sections as they will be shown in HTML and LaTeX export. Title of
section were cursor was at the moment of invoking command is taken into
``[[[ ]]]``; fourth column are line numbers of section titles -- user can
immediately issue Vim command, eg. ``:625`` to go to Roles section.
``link`` and ``slink``
``````````````````````
Commands will show all external links and internal explicit targets in
chronological order::
:Vst link
In alphabetical order::
:Vst slink
Fragment of link table for this document (in chronological order)::
Text Link
Vim http://www.vim.org
reStructuredText http://docutils.sf.net
starting point http://www.vim.org
comment
Opera http://www.opera.com
vst.pdf http://skawina.eu.org/mikolaj/vst.pdf
Item without Link part (second column) is internal explicit target.
``rep`` and ``srep``
````````````````````
Commands will show replace declarations. In chronological order::
:Vst rep
And in alphabetical::
:Vst srep
Replace table for this document (in chronological order)::
Symbol Replacement
H2O H\ :sub:`2`\ O
from image:image.jpg width:20 height:20 target:URL
VST Vim reStructured Text
Folding
```````
|VST| offers whole family of commands for folding of file.
This command will create simple folds for document, each section has its own
fold on the same level::
:Vst fold
Folds are created based on regular expressions and when you add new text to
section fold will be expanded to include them. New sections won't be
recognized automatically and you should recreate folds to include new
sections.
In front of header text you will see numbers of section as they will be
visible in HTML and LaTeX formats.
At the end of line enclosed in parenthesis are charaters used as ornament of
section title.
Command::
:Vst foldr
Will create folds recursively, each level of headers will have its own level
of folding.
Commands::
:Vst fold1
:Vst fold2
:Vst fold3
:Vst fold4
:Vst fold5
Will create one level of folds down to this level of headers. This is can be
useful for visualization of table of contents and faster navigation by big
structures of text.
Folding by directive
````````````````````
For easier finding of some directives user can use special case of folding::
:Vst f{directive}
Where ``{directive}`` is name of directive, eg.: container, blockquote,
image, figure, tip, note, etc. Directive name is case insensitive.
Special case is::
:Vst fblank
Document will be folded by paragraphs -- fragments of text separated by
blank lines.
``help``
````````
This command will show short summary of |VST| commands::
:Vst help
``preproc``
```````````
This command will preprocess file and include in file all including commands::
:Vst preproc
This command is recursive. For details see `including commands`_
Ornament mapping
````````````````
Manual insertion of sections_ or transitions_ ornaments is boring. To speed
things up in Vim way auxiliary mapping was created: o.
When placed below line of text and above empty one it will fill line to length
of line above. It may use character before cursor, when not available it will
use last single ornamented section title as hint.
When placed above line of text and below empty line it will embrace line below
in section ornaments. It may use character before cursor, when not available it
will use last double ornamented section title as hint.
When placed between empty lines it will fill it as transition element. It may
use character before cursor, when not available it will use last transition as
hint.
Vim settings
~~~~~~~~~~~~
Set of Vim settings which can be useful for editing of |VST| files::
set nocompatible
set autoindent
set formatoptions+=tqn
set formatlistpat=^\\s*\\(\\d\\+\\\|[a-z]\\)[\\].)]\\s*
set textwidth=78 " purely arbitrary value, just remember to set it
set expandtab
set softtabstop=4 " less than 4 may result in breaking of lists
set shiftwidth=4
set formatoptions+=tqn
Syntax highlighting
~~~~~~~~~~~~~~~~~~~
Structure of document will be more visible with syntax highlighting. It is
possible to use Vim default syntax highlighting file by Nicolai Weibull just
by issuing Vim command::
:set ft=rst
On `vim-online`_ site is another syntax file by Estienne Swart.
You can plase filetype declaration in Vim modeline, it will be removed from
output file to not confuse Vim filetype detection (modelines have the highest
priority). But it will work only if filetype setting is in separate |VST|
comment, line matching::
^\s*\.\. vim:
This line has to be also inside of 'modelines' Vim option range.
.. _vim-online: http://www.vim.org/scripts/script.php?script_id=973
Menus
~~~~~
Command::
:Vstm
in GUI version (gvim) will create menu with most common commands:
:Export to HTML: `export to HTML`_
:Export to LaTeX: `export to LaTeX`_
:Export to PDF: `export to PDF`_
:Export to reST: `export to reST`_
:Fold: folding_ of document
:Headers: show symbols of headers_ for various levels
:TOC: show contents_ of text document
:Help: show short help at the bottom of screen
To show menu always put this command in .vimrc:
``g:vst_showmenu``
Boolean (0). When 1 and set in .vimrc it will always show menu.
Structure
---------
Paragraphs
~~~~~~~~~~
Base unit of text is **paragraph**, text separated by at least one blank
line. All lines in paragraphs must have the same indentation. Paragraph
indented will be displayed as quotation (blockquote). It is possible to
embed any type and any number of elements inside blockquote -- respecting
their own rules of embedding. Example::
This is example of paragraph. This
is continuation of paragraph.
This is indented paragraph. Looking
like quoted text.
This is quoted quoted text. Indented two times.
This is another one.
Results in:
This is example of paragraph. This
is continuation of paragraph.
This is indented paragraph. Looking
like quoted text.
This is quoted quoted text. Indented two times.
This is another one.
Embedding of elements is supported for paragraphs, blockquotes, ordered
lists, unordered lists and tip, note, warning directives. In all of them
can be embedded the rest of one-level elements.
Text styles
~~~~~~~~~~~
Inside of paragraph (and other text elements you can use another markup
-- *italics* with ``*italics*``, **bold** with ``**bold**``,
````double back-quotes```` for ``typewriter text``.
This text is *italicised*.
This text is **strongly emphasised**.
This text is ``a code``.
If you find that you want to use one of the "special" characters in
text, it should be OK -- |VST| can deal with most typical situations.
For example, this * asterisk is handled just fine. If you actually
want text \*surrounded by asterisks* to **not** be italicised, then
you need to indicate that the asterisk is not special. You do this by
placing a backslash just before it, like so "``\\*``". Remember: special
treatment of these few characters is entering inline literals -- even
there you have to escape it with double backslash::
``\\*``
For another method of font manipulation check Roles_.
Inline markup rules
~~~~~~~~~~~~~~~~~~~
These rules apply for `text styles`_ and all other types of inline markup,
especially links_.
The inline markup start-string and end-string recognition rules are as
follows. If any of the conditions are not met, the start-string or
end-string will not be recognized or processed.
1. Inline markup start-strings must start a text block or be
immediately preceded by whitespace or one of::
' " ( [ { < - / :
2. Inline markup start-strings must be immediately followed by
non-whitespace.
3. Inline markup end-strings must be immediately preceded by
non-whitespace.
4. Inline markup end-strings must end a text block or be immediately
followed by whitespace or one of::
' " ) ] } > - / : . , ; ! ? \
5. If an inline markup start-string is immediately preceded by a
single or double quote, "(", "[", "{", or "<", it must not be
immediately followed by the corresponding single or double quote,
")", "]", "}", or ">".
6. An inline markup end-string must be separated by at least one
character from the start-string.
Special characters
~~~~~~~~~~~~~~~~~~
Sometimes it is necessary to escape special treatment of some
characters (or give that meaning). Then you have to put backslash ``\``
before them.
Remove space::
this\ that
Result: this\ that
Do not italicise word::
not \*this* word
Result: not \*this* word
Insert non-breaking space::
non\-breaking\-space
Result: non\-breaking\-space (`` `` in HTML)
.. Note:: This construction should be avoided and use non-breaking space
instead. It will be replaced with tilde in LaTeX export and leaved
as-is in HTML (it is correctly interpreted by browsers.
To input non-breaking space in Vim use:
- 160 in Latin1 and Latin2 encodings (``:help i_CTRL-V_digit``)
- NS (``:help i_digraph``)
Backslash should be escaped by putting before it another backslash only in
case when backslash could be used in special character. Slight inconsistency
but generally makes text more readable.
Roles
~~~~~
|VST| supports additional methods of text manipulation. They are called
*roles*. Usual form is::
:name:`text`
Roles are requiring white spaces or non-word characters around them. You
can escape them so they will be::
H\ :sub:`2`\ O
Result: H\ :sub:`2`\ O
It looks awkwardly, especially if repeated many times in text. You can
help it with replacement_::
|H2O|
.. |H2O| replace:: H\ :sub:`2`\ O
Result is: |H2O|
.. |H2O| replace:: H\ :sub:`2`\ O
Predefined roles
````````````````
All predefined roles can be recognized as arguments for `default role`_
directive.
Title reference
'''''''''''''''
This role will should be used to display :t:`Titles of books` and similar
citation sources. There are three ways to declare it in text::
:title-reference:`Title`
:title:`Title`
:t:`Title`
Title reference is default role for interpreted text.
Subscript
'''''''''
This role will show :sub:`small text below` normal line of text::
:sub:`small text below`
Superscript
'''''''''''
This role will show :sup:`small text over` normal line of text::
:sup:`small text over`
Big
'''
This role will show some :big:`bigger text`::
:big:`bigger text`
Small
'''''
This role will show some :small:`smaller text`::
:small:`smaller text`
Strong
''''''
This role will show :strong:`bold text`::
:strong:`bold text`
Emphasis
''''''''
This role will show :emphasis:`emphasised text`::
:emphasis:`emphasised text`
Literal
'''''''
This role will show :literal:`monospaced text`::
:literal:`monospaced text`
Custom roles
````````````
You can use custom roles which will be marked in |VST| source as::
:custom:`special text`
And in HTML output::
special text
In LaTeX output::
\vstcustom{special text}
Note ``vst`` prefix to avoid possible conflicts with built-in (La)TeX
commands. In preamble will be inserted simple template to allow compilation of
document without stopping on unknown commands::
\newcommand{\vstcustom}[1]{\textnormal{#1}}
It will be inserted before declaration of extension of preamble by `external
file`__. If user wants to declare there these new commands he should
use ``renewcommand`` LaTeX command.
__ vtp_
Roles have to be declared through _`role directive`. When not declared will be
silently ignored and any sign of them will be removed from output. Declaration
of role::
.. role:: custom
May be used for example to underline fragment of text (style of decoration not
supported by reST_ or |VST|)::
.. role:: ul
This fragment :ul:`will be underlined`
And in `user CSS`_ file::
span.ul { text-decoration: underline }
Role directive may have an option ``class``::
.. role:: name
:class: special
It will turn::
This is :name:`wonderful` feature.
Into::
This is wonderful feature.
Useful when CSS name is long or not meaningful.
Reversed notation
`````````````````
|VST| supports also reversed notation of roles::
`text`:name:
But be careful. Use of it in some cases (replacement-link combo) can give
weird results.
Lists
~~~~~
Lists of items come in three main flavours: **enumerated**, **bulleted** and
**definitions**. List element can contain many body elements.
Lists must always start a new paragraph -- that is, they must appear
after a blank line.
Enumerated lists
````````````````
Start a line off with a number or letter followed by a period ".",
right bracket ")" or colon ":", also enclosed in parenthesis (a). Following
forms are recognised::
1. numbers
A. upper-case letters
and it goes over many lines and may contain body elements like
1. sub-
2. -lists
::
Or preformatted text
a. lower-case letters
1) numbers again
i. lower roman numerals
I. and upper roman literals
(a) enumerator enclosed in parenthesis
Results in:
1. numbers
A. upper-case letters
and it goes over many lines and may contain body elements like
1. sub-
2. -lists
::
Or preformatted text
Or many other elements.
a. lower-case letters
1) numbers again
i. lower roman numerals
I. and upper roman literals
(a) enumerator enclosed in parenthesis
|VST| is taking numeration of first element as numeration of whole
list. This code::
a. alpha list
2. decimal list
Will be rendered as:
a. alpha list
b. decimal list
Two lists of the same type must have separator between them. In other
cause they will be rendered as one::
1. List1 Elem1
2. List1 Elem2
1. List2 Elem1
2. List2 Elem2
Results in:
1. List1 Elem1
2. List1 Elem2
1. List2 Elem1
2. List2 Elem2
Placing between them empty comment_ is enough. Anyway, short
description is always good thing.
List does not have to start from 1, a or A. Example::
5. First element of list
#. Second element
Will become:
5. First element of list
#. Second element
And::
h. lower alpha list
#. also don't have to start from a
Results in:
h. lower alpha list
#. also don't have to start from a
Also roman numerals can begin not only with i/I. Note however they have to
begin with number containing more than one letter (xl, iii, CV), in other case
they will be treated as alpha lists. Also each list beginning with i/I will be
treated as roman, never as alpha which begins at 9\ :sup:`th` letter of Latin
alphabet.
.. Warning:: In LaTeX export starting of lists not from 1/a/A/i/I requires
enumitem_ package.
.. _enumitem: http://www.ctan.org/tex-archive/macros/latex/contrib/enumitem
Auto numerated lists
````````````````````
Lists can be auto numerated. Begin list item with ``#``::
#. First item of list
#. Second item of list
All lists created with ``#`` will be displayed as numerated lists. Result:
#: First item of list
#: Second item of list
Bulleted lists
``````````````
Just like enumerated lists, start the line off with a bullet point
character -- either "-", "+" or "*"::
* a bullet using "*"
- list using "-"
+ yet another list
Results in:
* a bullet using "*"
- list using "-"
+ yet another list
These elements are connected (HTML only). ``*`` bulleted list always will be
``circle``, ``-`` will be ``disc`` and ``+`` will be ``square``.
In UTF-8 it is possible to use unicode BULLET characters:
- \u2022 BULLET
- \u2023 TRIANGULAR BULLET
- \u2043 HYPHEN BULLET
- \u204C BLACK LEFTWARDS BULLET
- \u204D BLACK RIGHTWARDS BULLET
- \u2219 BULLET OPERATOR
- \u25D8 INVERSE BULLET
- \u25E6 WHITE BULLET
- \u2619 REVERSED ROTATED FLORAL HEART BULLET
- \u2765 ROTATED HEAVY BLACK HEART BULLET
- \u2767 ROTATED FLORAL HEART BULLET
- \u29BE CIRCLED WHITE BULLET
- \u29BF CIRCLED BULLET
To make nicely looking text documents, however all of them will be treated in
output as ``-``.
Embedding of lists
``````````````````
Enumerated and bulleted lists can contain many elements and can be
nested. This code will be rendered::
1. This is description how to make lists embeddable
one into other.
- start one list
- insert blank line and bigger indentation
- start another list
- insert blank line before next element
2. It is possible to embed paragraphs into list (and blockquotes)
also.
Paragraphs and blockquotes have to be separated by blank line and
start where list begins: indentation of list "leader" plus
"leader", punctuation sign and space.
That is memorable quote.
Those features are not implemented for other types of elements.
Only: plain paragraphs, blockquotes, ordered lists, bulleted
lists.
Indentation level is *very* important. One space can break
things.
Results in:
1. This is description how to make lists embeddable
one into other.
- start one list
- insert blank line and bigger indentation
- start another list
- insert blank line before next element
2. It is possible to embed paragraphs into list (and blockquotes)
also.
Paragraphs and blockquotes have to be separated by blank line and
start where list begins: indentation of list "leader" plus
"leader", punctuation sign and space.
That is memorable quote.
Those features are not implemented for other types of elements. Only:
plain paragraphs, blockquotes, ordered lists, bulleted lists.
Indentation level is *very* important. One space can break things.
Definition lists
````````````````
Unlike the other two, the definition lists consist of a term, and
the definition of that term. The format of a definition list is::
what
Definition lists associate a term with a definition.
*how*
The term is a one-line phrase, and the definition are body elements,
indented relative to the term. Blank lines are not allowed between
term and first line of definition.
list
1. First element of definition
2. don't have to be
3. plain paragraph.
Results in:
what
Definition lists associate a term with a definition.
*how*
The term is a one-line phrase, and the definition are body elements,
indented relative to the term. Blank lines are not allowed between term
and first line of definition.
list
1. First element of definition
2. don't have to be
3. plain paragraph.
Field list
~~~~~~~~~~
Special kind of list designed for headers of files or highlighting
important information. Paragraph in form::
:Author: Mikolaj Machowski
:Something: Somewhere
Results in:
:Author: Mikolaj Machowski
:Something: Somewhere
Vim recognizes some names of field list as special and places them in
meta info of created documents:
- Author
- Title
- Date
- Subject
- Keywords
By default date is displayed in LaTeX documents. User can suppress it by using
keyword NONE::
:Date: NONE
This line will be removed from output and there will be no info about date in
exported document.
Option list
~~~~~~~~~~~
|VST| recognizes also special type of lists: option lists. It is
designed for listing of command options and Vim commands.
It is possible to create list from various types of command line
options::
-a Short form of an option
--all-name Long form of an option
-a, --all-name Combined listing of option
+option Old style options
/VMS VMS and DOS style options
:Vim command And Vim command -- not available in reST
--multi-struct It is possible to use structure elements in
option lists::
To present examples of use
1. Or possible
2. uses
3. Or any other structure element.
--in-case-of-very-long-option
definition may begin in next line, no trailing space
after option name allowed.
Option (command) have to be separated from description by at least two
spaces. Above example results in:
-a Short form of an option
--all-name Long form of an option
-a, --all-name Combined listing of option
+option Old style options
/VMS VMS and DOS style options
:Vim command And Vim command -- not available in reST
--multi-struct It is possible to use structure elements in
option lists::
To present examples of use
1. Or possible
2. uses
3. Or any other structure element.
--in-case-of-very-long-option
definition may begin in next line, no trailing space
after option name allowed.
Line blocks
~~~~~~~~~~~
Useful for presenting poetry or some preformatted text but not in monospace
font like addresses::
| This is *first* line
| This is indented **second** line
| This is indented slightly less then second
line, third (long) line
| And last, :small:`fourth` line
Will result in:
| This is *first* line
| This is indented **second** line
| This is indented slightly less then second
line, third (long) line
| And last, :small:`fourth` line
As you see, you can use markup inside of line block paragraphs. Line without
"| " starting sequence will be treated as continuation of previous line.
To use | at the beginning of paragraph but without intention of line block
creation, escape it with backslash.
.. Tip:: Indentation provided by output writers is visually much smaller than
presented in monospace font. Make correction for that.
.. _double colon:
Preformatting
~~~~~~~~~~~~~
To just include a chunk of preformatted, text, finish the prior
paragraph with "``::``". The preformatted block is finished when the
text falls back to the same indentation level as a paragraph prior to
the preformatted block. For example::
An example::
Whitespace, newlines, blank lines, and all kinds of markup
(like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)
no more example
Results in:
An example::
Whitespace, newlines, blank lines, and all kinds of markup
(like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)
no more example
.. _empty double colon:
Note that if a paragraph consists only of "``::``", then it's removed
from the output::
::
This is preformatted text, and the
last "::" paragraph is removed
Results in:
::
This is preformatted text, and the
last "::" paragraph is removed
Quoted literal blocks
`````````````````````
Quoted literal blocks are unindented blocks of text where each line begins
with the same character::
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~
**And** previous paragraph ends with ``::``.
Blank line ends quoted literal block. Quoting characters are preserved.
Example::
You wrote::
>> Thanks for your work
>
> Glad you appreciate it
Ha!
Results in:
You wrote::
>> Thanks for your work
>
> Glad you appreciate it
Ha!
Doctest
~~~~~~~
Special case of preformatted text are doctest blocks. First line have to begin
with ">>>" and can contain only one paragraph of text (without blank lines)::
>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)
Sections
~~~~~~~~
To break longer text up into sections, you use **section headers**. These are
a single line of text (one or more words) with adornment: an underline, in
dashes "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
non-alphanumeric characters ``= - ~ ^ ` * + # `` that you feel comfortable
with (full list of chars is in `quoted literal blocks`_ section). The
underline must be at least as long as the title text. Be consistent, since
all sections marked with the same adornment style are deemed to be at the same
level::
Chapter 1 Title
===============
Section 1.1 Title
-----------------
Subsection 1.1.1 Title
~~~~~~~~~~~~~~~~~~~~~~
Section 1.2 Title
-----------------
Chapter 2 Title
===============
To make some section titles more outstanding you can use double style headers,
with adornments below and *above* of title. These special lines **must** be
equal, both in characters and length. However, these two titles::
=================
Document title
=================
Section title
=============
Will be treated as two different levels.
In HTML export sections will be numbered thanks to ``content`` property.
Alas, only small number of WWW browsers are supporting this feature
(Konqueror_, Opera_, Firefox 1.5).
Section headers don't have to be separated with blank line from next paragraph
but it is recommended. Simple paragraphs not separated from section header
will be treated as subtitles_, rest will be treated normally, only directives
and special markup explicit blocks are forbidden.
Subtitles
`````````
It is possible to provide subtitles for section headers. It should be one,
short paragraph placed directly under ornament which will be rendered slightly
bigger than normal text. Example::
Directives
----------
Or how to place special elements in text
Check rendering of Directives_ section header.
Links
~~~~~
Links are important part of modern document. |VST| allows to create
external and internal links. All names declarations are case
insensitive. It means both examples will be working::
start_
_start: http://www.vim.org
`Starting point`_
.. _starting point: http://www.vim.org
Jump to tables_ (which is section with title "Tables").
Starting point
``````````````
Starting point looks like this::
We explained `starting point`_ somewhere else
The same for start_
Note: when start is single entity made from ``[:alnum:]``, ``.``, ``-``,
``_`` characters it may not be enclosed in backticks, also if word
is constructed from ``iskeyword`` characters.
External links
``````````````
Definition of external target::
.. _starting point: http://www.vim.org
.. _start: http://skawina.eu.org/mikolaj
Note: lack of backticks around titles, even when there is more than one
word. Links can be split for several lines::
.. _very, very long link description:
http://this.is.address.com/of/this/description
Internal links
``````````````
Definition of internal target can be done in two ways.
First is to put definition in text::
some text about _`starting point` explaining this term
Backticks are obligatory.
Second way is anonymous target::
.. _starting point:
Very similar to external target just pointing nowhere.
Standalone links
````````````````
Links can be put directly into text when written explicitly in text::
This link to http://skawina.eu.org/mikolaj page by
mailto:mikmach@wp.pl.
Results in:
This link to http://skawina.eu.org/mikolaj page by mailto:mikmach@wp.pl.
Supported protocols: http, https, ftp, mailto.
Anonymous hyperlinks
````````````````````
Definitions of links are boring. For creation of fast links use anonymous
hyperlinks. Example::
This is link__ to external document. I don't have time to write__ full
definition.
__ http://link.to.some.external.doc
.. __: http://second.link.to.external.doc
As you can see order of links and definitions is important. Should be used
only for fast and dirty work.
Indirect links
``````````````
Links definitions can be starting points defined elsewhere. Example::
.. _my wonderful page: start_
.. _start: http://skawina.eu.org/mikolaj
Should point to `my wonderful page`_.
.. _my wonderful page: start_
.. _start: http://skawina.eu.org/mikolaj
This can be also used in anonymous links::
__ start_
User can even create multi element chains::
.. _first elem: secondelem_
.. _secondelem: thirdelem_
.. _thirdelem: http://skawina.eu.org/mikolaj
Here is `first elem`_ link.
.. _first elem: secondelem_
.. _secondelem: thirdelem_
.. _thirdelem: http://skawina.eu.org/mikolaj
Embedded URIs
`````````````
A hyperlink reference may directly embed a target URI inline, within
angle brackets ("<...>") as follows::
See the `Vim-online page `_ for info.
This is exactly equivalent to::
See the `Vim-online page`_ for info.
.. _Vim-online page: http://www.vim.org
The bracketed URI must be preceded by whitespace and be the last text
before the end string. With a single trailing underscore, the
reference is named and the same target URI may be referred to again.
With two trailing underscores, the reference and target are both
anonymous, and the target cannot be referred to again. These are
"one-off" hyperlinks in form::
This is `embedded URI `__
This is `John Smith's mail `__
Note double underscore at the end and declaration of ``mailto:`` with e-mail.
There is also possible ultimate compact form::
This is link to ``__.
Results in:
This is link to ``__.
Replacement-link combo
``````````````````````
It is often boring to write long link texts. Shortening of them is very handy.
|VST| can do that with::
This is |vrest|_.
.. |vrest| replace:: reST implementation for Vim, **the best** editor of Earth
.. _vrest: http://skawina.eu.org/mikolaj/vst.html
Results in:
This is |vrest|_.
.. |vrest| replace:: reST implementation for Vim, **the best** editor of Earth
.. _vrest: http://skawina.eu.org/mikolaj/vst.html
This also a way to use inline markup inside of links.
Transitions
~~~~~~~~~~~
It is a nice touch to separate some paragraphs and parts of text
visually. In some old-fashioned books it is done with small graphics, in
newer with eg. row of asterisks ``* * *``.
In |VST| you can do this with line of letters, preferred are characters
used for sections_ underscoring::
================================================
------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
************************************************
etc. It have to be separated from other elements with blank lines. In
exported file they will look like straight line:
================================================
Attribution
~~~~~~~~~~~
When quoting text it is nice to add mention about author of quote. Special
element of text looks like::
This is memorable quote.
-- John Smith, Esq.
Results in:
This is memorable quote.
-- John Smith, Esq.
Some things which may not be visible:
- Must be last paragraph of block quote
- Must begin with '--' or '---' and space
Tables
~~~~~~
|VST| provides support for two types of tables. With border::
+---------------------+----------------+------------------+
| Cells are | by bar with | | |
| separated | spaces around | |
+---------------------+----------------+------------------+
| *You* may use | markup, | included. |
| **inline** | links_ | |
+---------------------+----------------+------------------+
| You can use various | - like lists | |VST| will |
| types of structure | | interpret them. |
| elements:: | + various | |
| | | Even paragraphs. |
| Welcome to world | - embedded | |
| of preformatted | - one into | 1. And |
| text. | other | 2. not |
| | | 3. only |
+---------------------+----------------+------------------+
| Text may span across several | |
| columns. Cell can be also empty -> | |
+---------------------+----------------+------------------+
This is result of table:
+---------------------+----------------+------------------+
| Cells are | by bar with | | |
| separated | spaces around | |
+---------------------+----------------+------------------+
| *You* may use | markup, | included. |
| **inline** | links_ | |
+---------------------+----------------+------------------+
| You can use various | - like lists | |VST| will |
| types of structure | | interpret them. |
| elements:: | + various | |
| | | Even paragraphs. |
| Welcome to world | - embedded | |
| of preformatted | - one into | 1. And |
| text. | other | 2. not |
| | | 3. only |
+---------------------+----------------+------------------+
| Text may span across several | |
| columns. Cell can be also empty -> | |
+---------------------+----------------+------------------+
For tables containing bigger chunks of structured text it may be better
to use border less tables. They are looking almost the same as regular
tables with exception of first line which is created with from equal
sign::
+======================================================================+
| This is converted fragment of ChangeLog_ |
+============+=========================================================+
| 5 Apr 2005 | - FIX: [HTML] properly indent preformatted |
| | text when first line has bigger |
| | indentation than next ones |
| | - CHG: [LaTeX] improve displaying |
| | of field lists |
+------------+---------------------------------------------------------+
| 6 Apr 2005 | - ADD: Rawlatex directive |
| | - ADD: [HTML] use counters in CSS for |
| | numbering of `table of contents`_ |
| | and sections_ in text. At the moment |
| | this numbering can be seen only in |
| | Konqueror_ 3.4 and Opera_ ver. ? |
+------------+---------------------------------------------------------+
Result of above example:
+======================================================================+
| This is converted fragment of ChangeLog_ |
+============+=========================================================+
| 5 Apr 2005 | - FIX: [HTML] properly indent preformatted |
| | text when first line has bigger |
| | indentation than next ones |
| | - CHG: [LaTeX] improve displaying |
| | of field lists |
+------------+---------------------------------------------------------+
| 6 Apr 2005 | - ADD: Rawlatex directive |
| | - ADD: [HTML] use counters in CSS for |
| | numbering of `table of contents`_ |
| | and sections_ in text. At the moment |
| | this numbering can be seen only in |
| | Konqueror_ 3.4 and Opera_ ver. ? |
+------------+---------------------------------------------------------+
Row separator from ``=`` will create head of table. Second such row will
create foot of table (only in HTML export).
Simple tables
~~~~~~~~~~~~~
Full tables are hard to correct and in most cases not necessary. Simple tables
are much simpler to write and maintain. They have also less features. The most
important difference is lack of support for spanning columns. Fragment of
changelog rewritten as simple table::
============ ========================================================
Date This is converted fragment of ChangeLog_
============ ========================================================
5 Apr 2005 - FIX: [HTML] properly indent preformatted
text when first line has bigger
indentation than next ones
- CHG: [LaTeX] improve displaying
of field lists
6 Apr 2005 - ADD: Rawlatex directive
- ADD: [HTML] use counters in CSS for
numbering of `table of contents`_
and sections_ in text. At the moment
this numbering can be seen only in
Konqueror_ 3.4 and Opera_ ver. ?
============ ========================================================
Results in:
============ ========================================================
Date This is converted fragment of ChangeLog_
============ ========================================================
5 Apr 2005 - FIX: [HTML] properly indent preformatted
text when first line has bigger
indentation than next ones
- CHG: [LaTeX] improve displaying
of field lists
6 Apr 2005 - ADD: Rawlatex directive
- ADD: [HTML] use counters in CSS for
numbering of `table of contents`_
and sections_ in text. At the moment
this numbering can be seen only in
Konqueror_ 3.4 and Opera_ ver. ?
============ ========================================================
Another nice example is output of ``cal`` program with slight modifications::
== == == == == == ==
su mo tu we th fr sa
== == == == == == ==
1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 29
30 31
== == == == == == ==
Will be shown as:
== == == == == == ==
su mo tu we th fr sa
== == == == == == ==
1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 29
30 31
== == == == == == ==
.. _comment:
Comments
~~~~~~~~
To comment fragment of text it should be prepended with two dots::
.. This text will be commented.
This text also will be commented.
But this not.
To make commenting easier dots can be in previous line::
..
This line will be commented.
And this not.
However, when line with two dots (and only two dots, eventually spaces) will
be followed by blank line even indented lines won't be commented out.
Comments may be useful to place in output code useful things like Vim
modelines::
.. vim:set tw=72:
or folding markers::
.. {{{
.. }}}
These lines will be in exported format, just not visible.
Footnotes
---------
You can include in text special links to fragments which don't match
into current paragraph, and place those fragments wherever you want in
document. |VST| supports three types of footnotes: **numbered**, **labeled**
and **auto-numbered**.
It is possible to use many structure elements in footnotes. They have to be
indented up to ``[`` opening footnote declaration.
Text of footnotes cannot be placed inside of tables.
Numbered footnotes
~~~~~~~~~~~~~~~~~~
The simplest one. Number is manually assigned to footnote. Example::
This doesn't belong here[1]_.
.. [1] I will describe it here.
Results in:
This doesn't belong here[1]_.
.. [1] I will describe it here.
There are numbered footnotes, try to keep them in order to not
disorientate readers. |VST| will not warn about duplicate footnotes.
Auto-numbered footnotes
~~~~~~~~~~~~~~~~~~~~~~~
In this type footnotes are declared by author only with ``[#]_``. Text of
footnote will look like::
.. [#] Footnote text.
Order of ``#`` signs is very important. First ``[#]_`` will be
connected with first ``.. [#]``, second ``[#]_`` with second ``.. [#]``
and so on.
Labeled footnotes
~~~~~~~~~~~~~~~~~
Marking footnotes with ``[#]_`` is fast but user can easily lost orientation.
Solution can be use of labeled footnotes. Example::
This is labeled[#lfoot]_ footnote.
.. [#lfoot] Labeled footnote looks similar to auto numbered but # is
followed by short alphanumeric description.
Mixing of footnotes
~~~~~~~~~~~~~~~~~~~
User can mix types of footnotes but results can be unexpected (and for sure
they will be different from reST_).
First numbers will be assigned to numbered footnotes, labeled footnotes will
follow with first number bigger then maximum number of numbered footnotes.
Numbers to labels will be assigned in order of use of labels in text. The last
ones will be auto-numbered footnotes.
.. Note:: Numbering of footnotes in LaTeX will strictly follow order of
footnotes. With mixed types is high probability numbers of footnotes in two
types of export will be different.
Citations
---------
Special case of footnotes_ are citations. In form::
This is citation [Smith1995]_
.. [Smith1995] John Smith, *Something about nothing*, Kein Press, 1995.
Will create footnote-like paragraph and link to this paragraph.
Directives
----------
Or how to place special elements in text
You can achieve special treating of some paragraphs by using
directives. They have always a form of::
.. directive::
Some directives can contain many various elements of text like lists,
preformatted text, even other directives.
Unknown directives will be displayed in red frame and in monospace font.
Images
~~~~~~
To include an image in your document, you use the ``image`` directive.
For example::
.. image:: test.png
Spaces in filename should be avoided (or encoded as %20, but can work properly
on standard settings.
- **Argument**: path to image
- **Options**:
``:width:``
Sets width of image in output document. Example::
:width: 200
``:height:``
Sets height of image in output document. Example::
:height: 100
``:identify:``
Calls ``identify`` program from ImageMagick_ suite to identify
dimensions of image. Possible use of argument -- number will be value
how to scale image in percents. When containing non digit chars,
ignored. Example::
:identify: 50
.. Note:: Not available in reST.
``:scale:``
Scale values from ``width``, ``height`` and/or ``identify``. Ignored
when values not supplied or argument contain non digit chars. Example::
:scale: 50
``:alt:``
Alternative text to show in WWW browsers when image not loaded. HTML
export only. Example::
:alt: Alternative text
``:title:``
Title of image to show in WWW browsers and as caption of image in
LaTeX/PDF output. Example::
:title: Title of image
``:target:``
Makes image a link. Argument is a path to location. Special argument
``self`` points to image itself. Examples::
:target: URL
:target: start_
:target: self
``:align:``
Moves image to the side of document making text flowing around it.
Allowed arguments are ``right`` and ``left``. HTML export only.
``:class:``
Apply special class to image. HTML export only.
- **Content**: NONE
Image examples
``````````````
You can supply additional information about image with options::
.. image:: test.png
:width: 200
:height: 100
:alt: Alternative text
:title: Title of image
Results in:
.. image:: test.png
:width: 200
:height: 100
:alt: Alternative text
:title: Title of image
Getting info about image dimensions is boring. You can use special
option ``:identify:`` which uses program from ImageMagick_ suite
of programs (available on most OS where Vim is available)::
.. image:: test.png
:identify:
:alt: Alternative text
:title: Title of image
``identify:`` can handle argument which will serve as scale factor. 100
is scale 1:1, scale will decrease size of image **only in document**. Real
size of image will not change::
.. image:: test.png
:identify: 50
:alt: Alternative text
:title: Title of image
Similar effect can be achieved with option ``:scale:``. Note that
``:identify:`` argument and ``:scale:`` will accumulate. If you declare 50 in
both image will have only 25% of linear size.
It is possible to make image a link with option ``:target:``::
.. image:: test.png
:target: http://www.vst.info/test.png
It will make image a link to other image. When you are scaling image
view it is a good idea to make it clickable and point to full scale
version -- possible with special argument ``self`` (note limited
usability in LaTeX export)::
.. image:: test.png
:identify: 50
:target: self
:alt: Alternative text
:title: Title of image
Results in:
.. image:: test.png
:identify: 50
:target: self
:alt: Alternative text
:title: Title of image
Figures
~~~~~~~
Figure is special construction which creates image with following text
elements will be placed in separate frame with possible text flowing around
(HTML only)::
.. figure:: test.png
:identify:
This is description of this figure.
1. Can use
2. Different elements
Spaces in filename should be avoided (or encoded as %20, but can work properly
on standard settings.
- **Argument**: path to image
- **Options**:
``:width:``
Sets width of image in output document. Example::
:width: 200
``:height:``
Sets height of image in output document. Example::
:height: 100
``:identify:``
Calls ``identify`` program from ImageMagick_ suite to identify
dimensions of image. Possible use of argument -- number will be value
hot to scale image. When containing non digit chars, ignored.
Example::
:identify: 50
.. Note:: Not available in reST.
``:scale:``
Scale values from ``width``, ``height`` and/or ``identify``. Ignored
when values not supplied or argument contain non digit chars. Example::
:scale: 50
``:alt:``
Alternative text to show in WWW browsers when image not loaded. HTML
export only. Example::
:alt: Alternative text
``:title:``
Title of image to show in WWW browsers and as caption of image in
LaTeX/PDF output. Example::
:title: Title of image
``:target:``
Makes image a link. Argument is a path to location. Special argument
``self`` points to image itself. Examples::
:target: URL
:target: start_
:target: self
``:align:``
Moves image to the side of document making text flowing around it.
Allowed arguments are ``right`` and ``left``. HTML export only.
.. Note:: When in options without ``:figalign:`` will be interpreted
as align of figure, not image.
``:class:``
Apply special class to image. HTML export only.
``:figwidth:``
Width of figure. By default 400px on HTML export and 0.6 of textwidth
in LaTeX. HTML export only.
``:figalign:``
Side where figure will be placed and text will flow around it. HTML
export only.
``:figclass:``
Apply special class to figure. HTML export only.
- **Content**: Interpreted as body elements.
Topic
~~~~~
A topic is like a block quote with a title, or a self-contained section with
no subsections. Use the "topic" directive to indicate a self-contained idea
that is separate from the flow of the document. Topics may occur anywhere
a section or transition may occur.
The directive's sole argument is interpreted as the topic title; the next line
must be blank. All subsequent lines make up the topic body, interpreted as
body elements. Example::
.. topic:: Header of topic
These lines are topic content interpreted
as body elements.
- **Argument**: header of topic
- **Options**:
``:class:``
Name of class applied to the topic. Only in HTML export.
One class is predefined -- sidebar::
.. topic:: Notes on margin
:class: sidebar
Elements from that topic will be put in float on right margin.
- **Content**: Interpreted as body elements
Sidebar
~~~~~~~
A sidebar is like a block quote with a title (also can be subtitle). Use the
"sidebar" directive to indicate a self-contained idea that is separate from
the flow of the document.
The directive's sole argument is interpreted as the sidebar title; the next
line must be blank. All subsequent lines make up the sidebar body, interpreted
as body elements. Example::
.. sidebar:: Header of subtitle
:subtitle: Why this is important
These lines are sidebar content interpreted
as body elements.
- **Argument**: header of sidebar
- **Options**:
``:class:``
Name of class applied to the topic. Only in HTML export.
``:subtitle:``
Subtitle of topic.
- **Content**: Interpreted as body elements
Table of contents
~~~~~~~~~~~~~~~~~
For longer text it is good idea to put in document table of contents.
In |VST| you can place table of contents at desired position with
directive::
.. contents::
In exported document it will be replaced by unordered list with elements
indented to present structure of document.
When contents directive is used sections headers will become links to
corresponding entries in table of contents.
- **Argument**: This directive automatically places also title. Default is
'Contents'. If you want give title in your language add this as argument to
directive (example for Polish)::
.. contents:: Spis tresci
I have omitted Polish diacritics to avoid encoding problems.
- **Options**:
``:depth:``
Directive ``contents`` accepts option ``:depth:`` which
argument is level of headers shown in table of contents::
.. contents:
:depth: 3
Will show in table of contents only headers down to 3\ :sup:`rd`
level.
``:class:``
Class of table of contents. In HTML CSS it is presented by two
elements: ``span`` (TOC header) and ``ul`` (TOC contents).
- **Content**: NONE
In HTML export table of contents will be numbered thanks to ``content``
property. Alas, only small number of WWW browsers are supporting this
feature (Konqueror_, Opera_, Firefox1.5).
Replacement
~~~~~~~~~~~
This is an exception from general format of directive::
.. |from| replace:: into
It consists of four parts: leading commas; source part enclosed in
bars; name of directive -- ``replace::``; and the rest of line which will
replace source in file (without leading space). Beware: ``from`` and ``into``
elements are processed through ``substitute()`` Vim function and have to be
proper Vim regexps. Three characters will be escaped automatically: ``\ & ~``.
Inline images
`````````````
Special type of replacement, designed for placement of images inline and
in tables_.
In text you can use it as normal replacement_ but declaration is
different::
.. |from| image::image.jpg
:width: 20
:height: 20
:target: URL
All options of Images_ directive are supported.
Result looks like that: |from|.
.. |from| image:: test.png
:width: 20
:height: 20
:target: self
Unicode
```````
Not all characters can be shown in localized encodings. For the rest it is
possible to use Unicode (U+ followed by hexadecimal number)::
.. |from| unicode:: U+2211 .. Sigma sign
This text will replace marker into unicode sigma sign. Encoding of output
document, regardless of current Vim encoding will be set to utf-8. Text after
two dots will be ignored.
User can put longer text in replacement::
.. |200E| unicode:: 200 U+20AC .. 200 euro
Spaces will be removed from output.
Unicode directive accepts one of three options:
``:ltrim:``
Will remove space from the left side of sign.
``:trim:``
Will remove space from left and right side of sign.
``:rtrim:``
Will remove space from right side of sign.
.. Warning::
- Encoding of Vim will not be changed and characters encoded in
utf-8 may be unreadable on terminal with non utf-8 encoding.
- Unicode replacements doesn't work for standard LaTeX
configuration. Direct PDF export will not work and LaTeX may need special
configuration.
Date
````
Inserting of date is tedious. To make it simpler use date replacement
directive::
.. |date| date::
.. |time| date:: %H:%M
Without arguments placeholder will be replaced with date in ISO format
YYYY-MM-DD. Arguments are following ``strftime()`` syntax. This function isn't
available on all systems, in such case placeholder will be replaced with
seconds from epoch :)
Including commands
~~~~~~~~~~~~~~~~~~
With bigger sets of documents some parts can be repeated. In such case it is
good idea to put them in external file and only include it in proper place.
Also it gives profits when making changes. User have to only make correction
in one file, not in whole collection. |VST| provides three directives. All are
making the same thing -- include text file -- written in VST before any other
activity.
1. This command will include file in given place::
.. header:: {filename}
Regardless of placement of this directive file will be put in the
beginning of exported file.
2. This command will include file in given place::
.. include:: {filename}
3. This command will include file in given place::
.. footer:: {filename}
Regardless of placement of this directive file will be put at the end of
exported file.
- **Argument**: String.
- If it is readable file its contents will be included and parsed as |VST|.
- Predefined name: ``vstfooter``. Contains date of generation and link to
source file. ``vstfooter`` will be used also in case when argument will be
empty.
- When filename is enclosed in <> |VST| will search in directory defined by
``g:vst_included`` variable. By default it is defined as: first element of
'runtimepath' option plus ``autoload/vst/include/`` directory. For example
on Linux it will be::
$HOME/.vim/autoload/vst/include/
This can be used for standard substitutions like provided by `reST
substitutes`_, personal set of substitutions or other type of data.
- For header and footer in other cases it will be treated as short message
to include at the top or bottom of the document and separated with
horizontal line from the rest of document.
- When including files indentation of directive will be taken into account.
It may be convenient to produce program listings in connection with `double
colon`_ or 2html_ directive.
- **Options**: NONE
- **Content**: NONE
.. Note:: To avoid endless loops level of recursiveness is equal to Vim's
option 'maxfuncdepth'/2 (default: 50).
.. _reST substitutes:
http://docutils.sf.net/docs/ref/rst/substitutions.html#character-entity-sets
Tip
~~~
This directive can contain many various elements::
.. tip:: First paragraph.
1. List element
2. List element
Second paragraph
- **Argument**: NONE
- **Options**: NONE
- **Content**: Interpreted as body elements
Above example results in:
.. tip:: First paragraph.
1. List element
2. List element
Second paragraph
All elements must have bigger indentation than directive. These
elements will be placed in green frame and with title 'Tip'.
Note
~~~~
This directive can contain many various elements::
.. Note:: First paragraph.
Remember these noble words.
Second paragraph
- **Argument**: NONE
- **Options**: NONE
- **Content**: Interpreted as body elements
Above example results in:
.. Note:: First paragraph.
Remember these noble words.
Second paragraph
All elements must have bigger indentation than directive. These
elements will be placed in black frame and with title 'Note'.
Warning
~~~~~~~
This directive can contain many various elements::
.. Warning:: First paragraph.
- List element
- List element
Second paragraph
- **Argument**: NONE
- **Options**: NONE
- **Content**: Interpreted as body elements
Above example results in:
.. Warning:: First paragraph.
- List element
- List element
Second paragraph
All elements must have bigger indentation than directive. These
elements will be placed in red frame and with title 'Warning'.
Admonition
~~~~~~~~~~
General form of multi element message directive (MEMD). Have form::
.. admonition::
:class: <class>
Text of admonition (many elements).
- **Argument**: title of admonition
- **Options**
``:class:``
describes look of admonition. By default ``note``, available three
classes: ``note``, ``tip``, ``warning``.
- **Content**: Interpreted as body elements. MUST be separated from header by
blank line.
Directive can be used as i18n version of any other MEMD.
Pull-quote
~~~~~~~~~~
Semantically similar to blockquote but in addition to being indented text will
be displayed with bigger font to attract attention::
.. pull-quote::
This is time of our lives!
Results in:
.. pull-quote::
This is time of our lives!
- **Argument**: NONE
- **Options**: NONE
- **Content**: Interpreted as block quote.
Container
~~~~~~~~~
General block directive::
.. container:: classname
- **Argument**: class name, may use any character, string will be parsed to
eliminate them
- **Options**: NONE
- **Content**: Interpreted as body elements
HTML output::
<div class="classname"> content of container </div>
LaTeX output::
\vstclassname{ content of container }
Note ``vst`` prefix to avoid possible conflicts with built-in (La)TeX
commands. In preamble will be inserted simple template to allow compilation of
document without stopping on unknown commands::
\newcommand{\vstclassname}[1]{#1}
It will be inserted before declaration of extension of preamble by `external
file`__. If user wants to declare there these new commands he should
use ``renewcommand`` LaTeX command.
__ vtp_
Compound
~~~~~~~~
Similar to container_ but designed to distinguish text rather semantically, not
visually:
.. compound:: <class>
- **Argument**: NONE
- **Options**
``:class:``
describes look of admonition
- **Content**: Interpreted as body elements
Class
~~~~~
This directive allows to apply arbitrary class name to most block elements
(HTML only)::
.. class:: name
There is an exception: Class directive will be ignored for directives which
has ``:class:`` option.
If next element has the same level of indentation class will be applied only
to that alement. But if next elements has bigger indentation class will be
applied to all of them::
.. class:: name
First paragraph
Second paragraph
Third paragraph
``name`` class will be applied to first and second paragraph but to to third.
.. Note:: ``name`` class style will be added to default style, not replace it.
- **Argument**: class name, may use any character, string will be parsed to
eliminate them
- **Options**: NONE
- **Content**: Interpreted as body elements
Default role
~~~~~~~~~~~~
This role sets default text role used for interpreted tex without declared
role. For example, after setting::
.. default-role:: newstyle
Text enclosed in backticks will be presented with help of ``newstyle`` class.
Default role for |VST| is `title reference`_.
- **Argument**: class name, may use any character, string will be parsed to
eliminate them
- **Options**: NONE
- **Content**: NONE
Meta
~~~~
This directive can be useful when providing meta data which user don't want to
be visible in form of `field list`_::
.. meta::
:author: Mikolaj Machowski
:subject: Vim reStructured Text
:http-equiv=Content-Type: text/html; charset=iso-8859-2
:description lang=en: Special text formatting
In HTML export this list will be included into meta tags of header. In LaTeX
four keywords will be recognized and put into PDF info: author, title,
subject, keywords.
- **Argument**: List of keywords with descriptions.
- **Options**: NONE
- **Content**: NONE
Title
~~~~~
Title directive may be used to place your own text in title tag of HTML export
or in PDF info fields. This title will not be visible in document itself::
.. title:: VST documentation
- **Argument**: Title of document
- **Options**: NONE
- **Content**: NONE
Rubric
~~~~~~
This directive shows line as header but without semantic meaning of header::
.. rubric:: This may be of interest for readers
- **Argument**: class name, may use any character, string will be parsed to
eliminate them
- **Options**: NONE
- **Content**: NONE
Raw
~~~
Raw latex
`````````
HTML and pure text are often not enough to present some mathematical
concepts. You can use then raw LaTeX directive::
.. raw:: latex
.. raw:: tex
- **Argument**: name of export: html, latex (case sensitive)
- **Options**:
``:file:``
External file which will be read into file. Example::
:file: path/to/file.tex
Contrary to treating of content there is no fall back for other
format.
- **Content**: one indented paragraph of LaTeX source
Content of this directive will not be visible in HTML export and in LaTeX
literally. This directive must be a one paragraph of |VST| -- without blank
lines. But you can make it multi paragraph LaTeX content with ``\par``
command::
.. raw:: latex
This is first par with special $\pi$ content.
\par
This is second par with special $\alpha$ content.
\par
\emph{Indentation} doesn't have special meaning but it is
good for visual separation of \texttt{paragraphs}.
Results in:
.. raw:: latex
This is first par with special $\pi$ content.
\par
This is second par with special $\alpha$ content.
\par
\emph{Indentation} doesn't have special meaning but it is
good for visual separation of \texttt{paragraphs}.
Content of this directive (and above example) will not be visible in HTML
export. This directive must be a one paragraph of |VST| -- without blank lines.
Raw latex replaces ``latexonly`` directive which is considered deprecated.
Raw html
````````
::
.. raw:: html
- **Argument**: name of export: html, latex (case sensitive)
- **Options**:
``:file:``
External file which will be read into file. Example::
:file: path/to/file.html
Contrary to treating of content there is no fall back for other
format.
- **Content**: one indented paragraph
::
.. raw:: html
<p>CO<sub>2</sub></p>
Results in:
.. raw:: html
<p>CO<sub>2</sub></p>
Content of this directive (and above example) will not be visible in LaTeX
export. This directive must be a one paragraph of |VST| -- without blank lines.
Raw html replaces ``htmlonly`` directive which is considered deprecated.
Both
````
Directive will accept also two arguments (HTML and LaTeX), it will be passed
without any modifications in two exports::
.. raw:: html latex
Order is not significant.
2html
~~~~~
.. Note:: Not available in reST. Colors in HTML only.
Directive designed to make use from ``2html.vim`` script for syntax
highlighting of code::
.. 2html:: [{filetype}]
.. 2html:: filetype [{colorscheme}]
``2html`` directive is extended declaration of `empty double colon`_.
Following paragraphs have to be separated by blank line and must have
bigger indentation.
- **Arguments**:
``filetype``
Argument will set proper highlighting for the following fragment of
code (usually those snippets will be too short for automatic
recognition). May be omitted, following paragraphs will be treated
as normal code snippets -- without coloring. Obligatory if you want
to declare ``colorscheme``.
``colorscheme``
Will set color scheme used for syntax highlighting. If omitted
current color scheme will be used. If you started without color
scheme and declared ``colorscheme`` argument it will be set. When
declared colorscheme doesn't exist default/current colorscheme will
be used.
- **Options**: NONE
- **Content**: Interpreted as preformatted text
.. Tip:: Not all colorschemes look good when exported to HTML. It is wise idea
to check result before official presentation. Especially ``default`` is
hard to read on white background -- and this is default combination when
doing export from non-GUI version of Vim. It is a good idea to set
``g:colors_name`` somewhere because it will be used in such case. When you
try to export this document on your system check example below with manxome
colorscheme which is not included in default Vim distribution.
2html examples
``````````````
Fragment of ``vst.vim`` in blue colorscheme::
.. 2html:: vim blue
if exists('depth') && depth != ''
let hdepth = strpart(g:ptype[j], '1')
if hdepth > depth
let j += 1
continue
endif
endif
Result:
.. 2html:: vim blue
if exists('depth') && depth != ''
let hdepth = strpart(g:ptype[j], '1')
if hdepth > depth
let j += 1
continue
endif
endif
The same fragment in manxome:
.. 2html:: vim manxome
if exists('depth') && depth != ''
let hdepth = strpart(g:ptype[j], '1')
if hdepth > depth
let j += 1
continue
endif
endif
And fragment of Vim itself -- ex_cmds.c by murphy. Declaration::
.. 2html:: c murphy
.. 2html:: c murphy
if (fp_out != NULL)
{
(void)mch_setperm(tempname,
(long)((st_old.st_mode & 0777) | 0600));
/* this only works for root: */
(void)chown((char *)tempname, st_old.st_uid, st_old.st_gid);
}
Macros
------
Not everything can be done with VST syntax. Here are coming **macros**. Macro
is keyword with optional value after colon like::
{macroname:argument}
They are not codified. To show what can be achieved with them to distribution
is added ``myhtmlvst.vim`` file with examples of two macros:
1. ::
{read:file}
First macro read file and put it inside of ``pre`` tag (it is like Vim
``:read`` command).
2. ::
{readpython:file}
Second _macro interpret contents of file and put it also in ``pre`` tag
(like Vim ``:read!`` command).
This command is smart. It can catch name of program between read and : and
call it later. Thus it can become {readperl}, {readruby}, {readbash}, etc.
Program name has to match ``\w\+`` regexp.
``readbang`` has special value -- it will execute shell command.
.. Warning:: This macro can have serious security consequences!!!
These two macros are line wise and must be kept in separate lines with
nothing around them.
Macro file is executed with help of `g:vst_html_post variable`__.
__ vhp_
Thanks
------
I'd like to say thanks to:
- Bram Moolenaar for great editor
- All authors of ``2html.vim``
- Authors of reST_ documentation
- George V. Reilly for extensive testing
- Edward G.J. Lee for traditional Chinese support in LaTeX
FAQ
---
- **Why VST was created?** For long time Vim users were asking for export
to real, human readable HTML text. Default 2html.vim does wonderful job but
only in regard to code. For other documents it is not well suited.
- **Why reST_ syntax and not ...?** I was looking through several text format
syntaxes but only reStructuredText was looking complete enough for me. Also
major plus for reST was fact that (contrary to all Wikis I saw) it was
designed to look equally good in original text form.
- **Will VST support all reST features?** Rather not. It is too big project
and develop too fast to catch up. All major features at the moment (1 Dec
2005) were implemented, minor features are covered to satisfy most users
IMO -- you can compare differences in `compatibility table`_.
.. _compatibility table: http://skawina.eu.org/mikolaj/restdiff.html
Also there are many pythonisms in reST I am personally not interested. Vim
Python users will probably install reST and will be happy, other wont be
interested in them.
- **Will be VST files fully compatible with reST?** It depends on user. There
are features Vim specific (like accepting of Vim commands in option lists),
or features that could not find in reST and seemed necessary for me. Also
some structure elements are practically impossible to implement in the same
way as in reST. I decided it is better to provide different implementation
that nothing.
- **How to make...?** Not everything can be made by pure VST or syntax. That
is what ``g:vst_xxx_post`` is for. For example, if you really must break
lines in HTML with ``br`` tag put placeholder ``{br}`` in your document,
and write::
%s/{br}/<br\/>/ge
in ``myhtmlvst.vim`` file and set::
let g:vst_html_post = "myhtmlvst.vim"
For other examples check macros_ section.
- **How to get only body of document?** Yes, this can be useful for writing blogs
or embedding text in other documents. As in previous question the answer is:
``g:vst_xxx_post``. Example for HTML::
:1,/<body>/ d
:/<\/body/,$ d
Also it is possible to get rid of VST specific ``id``\ s and ``class``\ es
with::
:%s/\(id\|class\)=".\{-}"//ge
- **Why should I choose VST over reST?**
1. No dependency on external tools. Unpack .zip archive and everything is ready.
2. reST is hard to install. I tried several times on Linux to set it up
properly -- $PATH and everything. Failed each time. Don't want even
think how to install it on MS-Windows. Plus installation of Python
itself.
3. 2html_ directive. Whole power of Vim syntax and colorscheme files on
your command!
Still, reST users may find some commands provided by VST useful. Check
`auxiliary commands`_ section.
- **What are the differences between VST and reST?** Comparison table is long
and is in `separate file`_.
.. _separate file: http://skawina.eu.org/mikolaj/restdiff.html
ChangeLog
---------
:FIX: bug fix
:ADD: new feature
:CHG: change of behaviour
:RMV: remove feature
:LaTeX/HTML/etc: apply to export, without that tag -- global
Full ChangeLog is here: `vst-changelog`_.
.. _vst-changelog: http://skawina.eu.org/mikolaj/vst-changelog.html
Changes from last announcement:
- 31 Oct 2006 - **1.3** announcement
- FIX: Vst link broken
- FIX: & in URLs double encoded
- FIX: broken chained links with uppercase letters
- REMEMBER ABOUT UPDATING DOCS
TODO
----
There is no roadmap for these things, they are just loose thoughts what
can be done in the future.
reST compatibility things are in `compatibility table`_ with (td) note.
- rotation of ornaments in titles
- option for XHTML doctype with proper content?
- image inside of admonition in LaTeX export (minipage conflicts...)
- show worded reference as label
- (doc) Quick start table
- start description of option in next line if option name too long
- fix _top in CSS (IE...)
+ REMEMBER ABOUT UPDATING DOCS
Copyright (c) Mikolaj Machowski, 2006
.. |VST| replace:: Vim reStructured Text
.. _reStructuredText: http://docutils.sf.net
.. _reST: http://docutils.sf.net
.. _Python: http://www.python.org
.. _Vim: http://www.vim.org
.. _OpenOffice.org: http://www.openoffice.org
.. _KOffice: http://koffice.kde.org
.. _MS-Office: http://www.microsoft.com
.. _ImageMagick: http://www.imagemagick.org
.. _Konqueror: http://www.kde.org
.. _Opera: http://www.opera.com
.. vim:set tw=78 ai fo+=n fo-=l ft=rst:
VST-1.4/plugin/ 0000775 0000000 0000000 00000000000 11456723370 0013340 5 ustar 00root root 0000000 0000000 VST-1.4/plugin/vstplugin.vim 0000664 0000000 0000000 00000004762 11456723370 0016121 0 ustar 00root root 0000000 0000000 " Vim reStructured Text
" (c) Mikolaj Machowski 2006
" Author: Mikolaj Machowski ( mikmach AT wp DOT pl )
" Last Change: 4 Nov 2006
" Version: 1.4
" License:
" Copyright (C) 2006 Mikolaj Machowski <mikmach@wp.pl>
"
" This script is free software; you can redistribute it and/or
" modify it under the terms of the GNU Library General Public
" License as published by the Free Software Foundation; either
" version 2 of the License, or (at your option) any later version.
"
" This library is distributed in the hope that it will be useful,
" but WITHOUT ANY WARRANTY; without even the implied warranty of
" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
" Library General Public License for more details.
"
" You should have received a copy of the GNU Library General Public License
" along with this library; see the file COPYING.LIB. If not, write to
" the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
" Boston, MA 02110-1301, USA.
"
" VST requires Vim7
if v:version < 700
finish
endif
" Command :Vst
command! -range=% -nargs=? -complete=custom,VST_Args Vst call vst#vst#VST_Export(<line1>, <line2>, <q-args>)
command! -range=% -nargs=? -complete=custom,VST_Args Vsti call vst#vst#VST_InstantWrapper(<line1>, <line2>, <q-args>)
command! -range=% -nargs=? -complete=custom,VST_Args Vstm call VST_Menus()
" VST_Args: Command line completion for :Vst command {{{
function! VST_Args(A, C, P)
let args = "html,tex,latex,pdf,toc,head,fold,link,slink,rep,srep,preproc,help,rest"
return substitute(args, ',', '\n', 'g')
endfunction
" }}}
" Menus {{{
function! VST_Menus()
if has("gui_running")
menu VreST.Export\ to\ HTML :Vst html<cr>
menu VreST.Export\ to\ LaTeX :Vst tex<cr>
menu VreST.Export\ to\ PDF :Vst pdf<cr>
menu VreST.Export\ to\ reST :Vst rest<cr>
menu VreST.Fold :Vst fold<cr>
menu VreST.Headers :Vst head<cr>
menu VreST.TOC :Vst toc<cr>
menu VreST.Help :Vst help<cr>
inoremenu VreST.Export\ to\ HTML <c-o>:Vst html<cr>
inoremenu VreST.Export\ to\ LaTeX <c-o>:Vst tex<cr>
inoremenu VreST.Export\ to\ PDF <c-o>:Vst pdf<cr>
inoremenu VreST.Export\ to\ reST <c-o>:Vst rest<cr>
inoremenu VreST.Fold <c-o>:Vst fold<cr>
inoremenu VreST.Headers <c-o>:Vst head<cr>
inoremenu VreST.TOC <c-o>:Vst toc<cr>
inoremenu VreST.Help <c-o>:Vst help<cr>
endif
endfunction
if exists("g:vst_showmenu") && g:vst_load_menus != 0
call VST_Menus()
endif
" }}}
" Load auxiliary mappings:
call vst#vst#VST_AuxiliaryMappings()
" vim:fdm=marker:ff=unix:noet:ts=4:sw=4:nowrap