% vi: ft=viki:tw=72 % @Last Change: 19-Jun-2005. * Markup #OPT: id=Markup #markup The markup corresponds to the markup of Vim's viki-plugin. There are some minor deviations, though. This chapter is mainly a test course. ** The Basics *** Elements and Particles A ''deplate'' document is made up of elements (a.k.a. block elements in HTML, XML etc.) and particles (a.k.a. inline elements). No particle can cross element boundaries. This distinction is important to understand, as [-commands-] and [-regions-] yield elements, but [-macros-] yield particles. Most element patterns work by marking the beginning of the first line of an element -- regions being the only exception. Some elements like headings, anchors, or table rows are one-line patterns. Other elements like list items or paragraphs can be made up of more than one line. A line matching an element pattern ends a multi-line element. *** Backslashes The ''deplate'' markup is based on enclosing text with special markers or sequences of characters as in this example: ''__emphasized__''. If you want to prevent ''deplate'' from interpreting these markers, they must be preceded by a backslash. #IDX: Backslash|backslash #backslash - The backslash is used as escape character that prevents the wikification of the following character - There are two exceptions: - A backslash at the end of the line makes a pattern include the next line; any whitespace at the beginning of the following line is removed #lineContinuation - A backslash in front of a blank results in non-breaking space - A backslash that should be printed must be preceded by a backslash *** Special Characters You should especially take care with the following characters: Curly braces (\{\}) :: Curly braces usually enclose macros; in other contexts, they should always be preceded by a backslash - There are some grey areas though that could cause problems, e.g. when input to a macro (e.g. the ruby macro) contains an unmatched curly brace Backticks (\`) :: {idx: Backtick|Backticks|backtick|backticks} Backticks introduce some symbols and should be escaped by a backslash in other contexts than inserting a special character. Sequences of character you should notice: Two underscores (\__) followed by non-whitespace :: Emphasized text Two single quotes (\'\') followed by non-whitespace :: Literal text set in typewriter font Two colons (\::) surrounded by whitespace :: Used in definition lists Characters with special meaning if they occur at the beginning of line: Asterisks (*) :: Headings, unordered lists Sharp sign (#) :: Anchors, commands, regions, ordered lists Percent (%) :: Comments List markers :: 1., a., -, *, #, @, ?, ?. #Example <<---- __emphasize__, WikiName \__noemphasize\__, \NoWikiName One \ \ line One\ word unnnnnnnnnnnnnnnnnn\ breakkkkkkkkkkkkkkkkkk\ ableeeeeeeeeeeeeeeeeeeeeeee ---- *** Argument Values Arguments to macros, commands, and regions: - In argument values, the characters ''!=:'' and single double quotes must be preceded by a backslash - Alternatively, you can enclose a value in double quotes (which will be stripped off; doublequotes must be escaped using a backslash) or parentheses (which will be retained) - Argument values are stripped of whitespace; if you want an argument to contain leading or trailing whitespace, you have to enclose the argument in double quotes || Example || Key Arguments || Body || | \{macro\} | \{\} | \"\" | | \{macro: foo\} | \{\} | \"foo\" | | \{macro boo!: foo\} | \{\"boo\" => true\} | \"foo\" | | \{macro boo! bar=1: foo\} | \{\"boo\" => true, \"bar\" => \"1\"\} | \"foo\" | | \{macro bar=object(id=1): foo\} | \{\"bar\" => \"object(id=1)\"\} | \"foo\" | | \{macro bar=\"foo := bar\": foo\} | \{\"bar\" => \"foo := bar\"\} | \"foo\" | | \{macro bar=( boo=boo): foo\} | \{\"bar\" => \"( boo = boo)\"\} | \"foo\" | | \{macro bar=\\( boo=boo): foo\} | \{\"bar\" => \"(\", \"boo\" => \"boo)\"\} | \"foo\" | | \{macro bar=\"(\" boo=boo): foo\} | \{\"bar\" => \"(\", \"boo\" => \"boo)\"\} | \"foo\" | #CAP: Key arguments ** Comments (whole lines) - The percent sign has to be first non-blank character in the line. Otherwise it's interpreted as a character. - A comment separates lines as paragraphs. - For intra-paragraph comments use the comment macro{ref: commentMacro} #Example <<--- Line %1 %Comment Line %2 --- ** Paragraphs A paragraph a sequence of non-empty lines that don't match anything else. #Example <<--- Paragraph 1 finishes with an empty line. Paragraph 1 finishes with an empty line. Paragraph 1 finishes with an empty line. Paragraph 2 finishes with an unordered list. Paragraph 2 finishes with an unordered list. Paragraph 2 finishes with an unordered list. - Item 1 - Item 2 --- ** Headings #headings __NOTE:__ Headings can span more than one line by putting a backslash ('\\') at the end of the line. Known options: noList! :: prevent the heading from being listed in the toc; as you can see from the current heading, the heading number is increased nevertheless (which probably should be considered as a bug?) caption :: the display name in the table of contents shortcaption :: the display name in a minitoc; with multi-file output, this argument defines the optional file name id :: similar to shortcaption; if an id and a shortcaption are given, the id will be used for the filename and the sort caption for the mini-toc If you set the variable ''autoFileNames'', ''deplate'' will derive the file name from the heading. #Verb <<--- * Level 1 #OPT: id=foo ** Level 2 *** Level 3 #OPT: noList! plain! ... --- ** Lists (indented) #lists #Example <<--- - Item * Item + Item 1. Item 1 a. Item a B. Item B * Item # Item 1 # Item 2 @ There is much to say about Item A, too much to be put in words or to be written down. What else is there to say about Item A? @ Item B --- __NOTE:__ "#" (numbered, ordered lists), and "@" (ordered lists with letters) are the preferred markers. If you use dashes as in LaTeX (i.e. "-\-"), a dash appears to be okay too. Be aware that, like LaTeX, ''deplate'' concatenates two normal dashes ("-\-") to one long dash ("--") -- see also{ref: symbols}. __NOTE:__ If you run into troubles when nesting lists, consider the use of the list macro{ref: smallLists}. ** Description lists (indented) #Example <<--- Item :: Description --- ** Tables #tables A table is marked as sequence of lines beginning and ending with one or two "|" symbols. Two pipe symbols (or whatever its name is) define a row belonging to the head or the foot. A row containing only empty cells and cells with hyphens defines a ruler. A cell containing only "^" means concatenate with the cell above. A cell containing only "<" means concatenate with the cell to the left. % !!! If you concatenate cells vertically, deplate will use the % "multirows" package for LaTeX output. Tables take the following options (via the OPT command): ''head=N'' :: The number of rows encompassing the table head ''foot=N'' :: The number of rows encompassing the table foot ''hiRow=N1,N2,first,last,...'' :: The rows to be highlighted ''hiCol=N1,N2,first,last,...'' :: The columns to be highlighted ''rows=ROWDEF1, ROWDEF2, ...'' :: Define a row's attributes - ROWDEF has the form: ''KEY1.VAL1 KEY2.VAL2 ...''; KEY being one of h :: The row height - a ruler counts as a row ''cols=COLDEF1, COLDEF2, ...'' :: Define a columns's attributes - COLDEF has the form: ''KEY1.VAL1 KEY2.VAL2 ...''; KEY being one of w :: The column width j :: The column's justification (left, right, center, or justified) r :: Add a left-handed vertical ruler (the value denotes the number of rulers or its thickness) - This option is currently only interpreted for LaTeX output ''long!'', ''short!'' :: Define whether the ''longtable'' environment should be used in LaTeX output (by default, the ''longtable'' environment will be used for tables with more than 20 rows). - Switching between the ''table'' and the ''longtable'' environment has some effects on the layout. One consequence is that footnotes are set properly only in the ''longtable'' environment. On the other hand, the ''here'', ''floatHere'', ''align'', and ''floatAlign'' options are currently ignored. ''style=NAME'' :: The table style (but see below) ''stylex=NAME'' :: Like ''style'' but ignore ''tableStyle'' ''note=TEXT'' :: A short note concerning data source etc. In addition, the following options for "floats" apply too: #floatOptions ''here!'', ''floatHere=1'' :: In LaTeX output, add the ''h'' attribute to the table environment ''align=[left|right|center]'', ''floatAlign=[left|right|center]'' :: align the table; the first one is a table specific options, the second a global document option __Joining cells:__ If a cell contains nothing but "^" or "<", the current cell will be joined with the left one or with the cell above. (The actual output depends on the formatter and the capabilities of the target format, though.) It depends on the formatter whether these options are interpeted. #Example <<-- || ----------------------------- || || Head || Categories || < || | Row1 | Value1 | Value1 | | | ----------- | | | Row2 | | Value2 | | | ----------- | | | Row3 | Value3 | ^ | | ----------------------------- | #OPT: hiCol=first hiRow=last cols=w.3cm j.right r.1, w.1cm,,r.1 rows=,h.3cm #OPT: note=Source: My Head, 2004 #CAP: This Table #thisTable -- __NOTE:__ Rows can span more than one line by putting a backslash ('\\') at the end of the line. __NOTE:__ An empty cell is marked by at least 3 consecutive blanks. You can also define a style for a table. The style attribute is currently only interpreted by the latex-styles module and to some degree emulated in HTML output -- not so surprisingly, this works better in Firefox than in MS IExplorer. The following styles are known (for one or another output format): grid :: Draw all table borders/rulers formal :: Draw a ruler at the top and the bottom of the table, as well as between groups box :: Like formal but add vertical rulers on both sides overlay :: Like box but draw the background of some rows and columns in gray or in colours list :: Horizontal rulers between each row small, footnotesize, scriptsize :: Smaller font sizes dense08 :: decreased intercell spacing (there is a minor problem with line spacing) landscape :: rotate the table (LaTeX only, I assume) #Example <<-- #Var id=styledTableExample <<--- || Head || A || B || | Row1 | 1 | 2 | | Row2 | 3 | 4 | || Foot || X || Y || #OPT: hiCol=first --- Test ''grid'' & ''scriptsize'' styles: #INCLUDE var=styledTableExample #OPT: style=grid,scriptsize Test ''formal'' & ''footnotesize'' styles: #INCLUDE var=styledTableExample #OPT: style=formal,footnotesize Test ''box'' & ''small'' styles: #INCLUDE var=styledTableExample #OPT: style=box,small Test ''overlay'' style: #INCLUDE var=styledTableExample #OPT: style=overlay,landscape -- ** Anchors Anchor (or labels respectively) are attached to the previous element, save if the previous element is a whitespace. In this case the anchor will be attached to the following element. The name must begin with a lower letter. There mustn't be non-whitespace character before the sharp sign. Example: #Verb <<-- * This is section one #labSectOne Some text. #labSomeText #labSectTwo * This is section two -- ** Wiki Names, URLs ''deplate'' is inspired by several wiki engines. It thus also provides formatting of wiki names and URLs as hyperlinks. There are about four types of wiki names. #IDX: URL|URLs Simple :: Any word in Camel\Case is turned into a wiki name -- save if wikification is prevented with a backslash -- see{ref: backslash}. Quoted :: Any text between ''[-'' and ''-]'' will be turned into a hyperlink. Extended :: An extended wiki name has the form: ''[[DESTINATION][OPTIONAL NAME]MODIFIER]''. - MODIFIER is optional. "!" :: prevents ''deplate'' from adapting the reference's suffix - ''deplate'' was created as the publishing framework (or so) for a personal wiki (namely the Vim viki plugin). As such it assumes that the files being referenced to are converted to the same target format as the current file, which is why ''deplate'' modfies an extended wiki destination's suffix. Use this modifier to prevent ''deplate'' from doing so. - Often the chosen ''deplate'' output is only an intermediary file; in order to make ''deplate'' append the suffix of the final output file, set the document option ''suffix'' to the desired value. E.g. if you convert to docbook and then from docbook to html, pass the option ''-D suffix=html'' to ''deplate'' when converting the text sources. Inter\Wikis :: An interwiki name is a shortcut to a different wiki. Any simple and quoted wiki name can be deferred to an interwiki by prepending ''NAMEINCAPITALS::''. You have to define an interwiki before referring to it by adding something like this to your configuration file: ''InterWiki.add("ID", "http://BASEURL/", ".SUFFIX")'' {idx: Wiki|wiki|Wikis|wikis} Wiki Names are automatically marked as index entries -- see{ref: cmdIDX} and{ref: listIndex}. Examples of wiki names: #Verb <<--- WikiName WikiName#anchor [-name-] [-some name-]#there [--]#here OTHERWIKI::WikiName OTHERWIKI::WikiName#there OTHERWIKI::[-some name-] OTHERWIKI::[-some name-]#there [[destination]] [[destination][name]] [[destination#anchor][name]] [[destination.suffix]!] [[#anchor]] [[#anchor][name]] --- ** Symbols #symbols #Example <<--- <-, ->, <=, =>, <~, ~>, <->, <=>, <~>, !=, ~~, ..., --, ==, ```, `'', ``, `' --- The backtick (`) is used to introduce some symbols like quotation marks (e.g., in positions where ''deplate'' would choose the wrong one). ** Markers Markers are meant to highlight a position in the text. In order to avoid ambiguities with notes (see below), there should not be a space before or after the marker -- i.e. it should immediately follow or precede the word it is referring to. #Example <<--- - elaborate+++ - here### - questionable??? - attention!!! --- ** Notes Indented paragraphs that begin with a marker and a subsequent space start an annotation, i.e. the text of paragraph will be turned in a margin note or similar -- depending on the output format. #Example <<-- Indented paragraphs that begin with a marker and a subsequent space start an annotation. !!! Something like this. -- ** Strings #Example <<--- "Text in quotes" --- ** Textstyles #Example <<--- __emphasize__, ''typewriter'' --- __NOTE:__ There must not be a whitespace after the opening mark. #IDX: Whitespace|whitespace|Whitespaces|whitespace __NOTE:__ Text in typewriter style is basically set verbatim with the expection of backslashes. ** Breaks A break is marked by at least 2 dashes, "8<", and again at least 2 dashes. #Verb <<--- I say so. ----8<-------------- Summary: --- In HTML output, a break is represented by a horizontal line. In other output formates, a break actually denotes a page break. ** Whitespace A line of whitespace usually separates text elements -- e.g. paragraphs,