[ADD] conf deplate, and test viki.

[arrow.git] / viki / zdraft / playground.viki

* [[/viki][test viki syntax, playground]]

{val: topBar}
[[otherwiki::dist#anchor][name_show]]
[[$TOPDIR/kernel/about][abount]]
AbcArrowzhang
$TOPDIR

  - Item
  * Item
    + Item
      1. Item 1
        a. Item a
        B. Item B
  # Item
  # Item 1
    # Item 2
      @ Item A
      @ Item B

|| head                 || category                     ||
| row                   |  value,表格测试    |
#CAPTION: This table
#label

Foo bar{fn: x} foo bar.

#Fn: x <<EOF
Bla bla.
EOF

<-, ->, <=, =>, <~, ~>, <->, <=>, <~>, !=, ~~, ..., --, ==

%+++, ###, ???, !!!
#Code id=Foo syntax=ruby <<---
class Foo
    # Return two times x
    def bar(x)
        x * 2
    end
end
---

%%Some formula: {ltx: $\sum_{i=n}^{n} x_{i}$}
%%or simply: $\lambda_1 v_1 + \lambda_2 v_2 + ... + \lambda_n v_n$.

%%#Inlatex <<---
%%$det A = \sum\limits_{\pi \in S_n} sgn(\pi) a_{\pi(1)1} ... a_{\pi(n)n}$
%%---


#TITLE: playground
#DATE: today
{val: TOPDIR}


#TI: How to do web-based presenation with deplate
#AU: Th. Link
#DATE: today
%#MAKETITLE
%#LIST plain!: toc
    - Item
        * Item
            + Item
                1. Item 1
                    a. Item a
                    B. Item B
                    #Verb <<---------
                    EMBEDDED VERBATIM TEXT 
                    ---------
                2. Item 1
                    || Embedded || Table ||
                    |  x        |  1      |
                    |  y        |  2      |
        * Item
            # Item 1
                @ 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
            # Item 2
    - Do this
        #A _ Some task
        #B1 _ Some other task
    - Do that
        #A  x11-11-2050 Something was done!
        #B1 11-11-2050  Some other task


|| ----------------------------- ||
|| Head || Categories || <       ||
|  Row1 |  Value1     |  Value1   |
|       | ----------- |           |
|  Row2 |             |  Value2   |
|       | ----------- |           |
|  Row3 |  Value3     |  ^        |
|  -----------------------------  |
#OPT: hiCol=first hiRow=last cols=w.3cm j.left r.1, w.1cm,,r.1 rows=,h.3cm
#OPT: note=Source: My Head, 2004
#CAP: This Table
#thisTable

#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


* This is section one
#labSectOne

Some text.
#labSomeText

#labSectTwo
* This is section two

----
--
------
WikiName
WikiName#anchor

[-name-]
[-some name-]#there
[--]#here

::WikiName
::WikiName#there
::[-some name-]
::[-some name-]#there

[[destination]]
[[destination][name]]
[[destination#anchor][name]]
[[destination.suffix]!]
[[::destination#anchor][name]]
[[#anchor]]
[[#anchor][name]]

====
<-, ->, <=, =>, <~, ~>, <->, <=>, <~>, !=, ~~, ..., --, ==, ```, `'', ``, `'

''->'', ''<-''

#Verb <<--
<-, ->, <=, =>
--

#Code id=symbolsTest syntax=ruby <<--
<-, ->, <=, =>
--
====
    - elaborate+++
    - here###
    - questionable???
    - attention!!!


====
Indented paragraphs that begin with a marker and a subsequent space 
start an annotation.
    !!! Something like this.

--------------------------------------------------------------------
9.1 The Basics
9.1.1 Elements and Particles

A deplate document is made up of elements (a.k.a. block elements in HTML, XML etc.) that consist of 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.

Although deplate has some facitilities for program control (conditional or repeated output), it really is rather a markup language but no programming language. Although you can define new elements right within a deplate document using deplate markup, this only works for really simple elements.

If a line matches an element pattern (usually defined by the beginning of the line), it marks the end of the previous element and starts a new element. If a line matches no pattern, it either starts a new paragraph or is added to the previous element. Elements like headings, anchors, or table rows are one-line patterns to which no unmatched line will be added. Other elements like list items or paragraphs can be made up of more than one line.
9.1.2 Backslashes

The deplate markup is based on inserting special characters into the text as in this example: __emphasized__, which will be printed as emphasized. If you want to prevent deplate from interpreting these markers, they must be preceded by a backslash.

    * The backslash is used as escape character that prevents the wikification of the following character.
    * There are two exceptions:
         1. 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.
         2. A backslash in front of a blank results in non-breaking space.
    * A backslash that should be printed must be preceded by a backslash.

9.1.3 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 (`)
    Backticks are used to insert 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., -, *, #, @, ?, ?. 

Other:

The dollar sign ($)
    Although it has currently to be enabled by loading a module, there is a chance that this will become the standard delimiter for mathematical expressions typed in latex (with the AMS packages enabled). The standard markup will be either $a = x + y$ or with blanks $ a = x + y $ as the dollar sign is most likely used before or after a digit. 

Be aware that your editors line wrap can inadvertently place these characters at the beginning of a line.

Example 9.1: Text styles, backslash

__emphasize__, WikiName

\__noemphasize\__, \NoWikiName

One \
\
line

One\
   word

unnnnnnnnnnnnnnnnnn\ breakkkkkkkkkkkkkkkkkk\ ableeeeeeeeeeeeeeeeeeeeeeee

yields:

emphasize, WikiName

__noemphasize__, NoWikiName

One line

Oneword

unnnnnnnnnnnnnnnnnn breakkkkkkkkkkkkkkkkkk ableeeeeeeeeeeeeeeeeeeeeeee
9.1.4 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

Table 9.1: Key arguments 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"

There are two special arguments (fmt and if) that allow some control on whether an element will be included in the output. Please see 14.6 for details.
9.2 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 12.2

Example 9.2: Comments

Line %1
%Comment
Line %2

yields:

Line %1 Line %2
9.3 Paragraphs

A paragraph a sequence of non-empty lines that don’t match anything else.

Example 9.3: Paragraphs

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

yields:

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

9.4 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 
plain!
    Don’t add any numbering to the heading. (Set the variable headings to “plain” if you want to turn off numbering for all headings.) 
url=URL
    Turn a heading into a hyperlink; this requires the hyperHeading variable(see 14.1.2) to be set 

If you set the variable autoFileNames, deplate will derive the file name from the heading.

* Level 1
#OPT: id=foo

** Level 2

*** Level 3
#OPT: noList! plain!
...

9.5 Lists (indented)

Example 9.4: List

    - Item
        * Item
            + Item
                1. Item 1
                    a. Item a
                    B. Item B
                    #Verb <<---------
                    EMBEDDED VERBATIM TEXT 
                    ---------
                2. Item 1
                    || Embedded || Table ||
                    |  x        |  1      |
                    |  y        |  2      |
        * Item
            # Item 1
                @ 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
            # Item 2
    - Do this
        #A _ Some task
        #B1 _ Some other task
    - Do that
        #A  x11-11-2050 Something was done!
        #B1 11-11-2050  Some other task

yields:

    * Item
          o Item
                + Item
                     1. Item 1
                           1. Item a
                           2. Item B

                              EMBEDDED VERBATIM TEXT 

                     2. Item 1
                        Embedded        Table
                        x       1
                        y       2
          o Item
               1. Item 1
                     1. 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?
                     2. Item B
               2. Item 2
    * Do this
          o A Some task
          o B1 Some other task
    * Do that
          o A 11-11-2050 Something was done!
          o B1 11-11-2050 Some other task

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 9.10.

NOTE: If you run into troubles when nesting lists, consider the use of the list macro 12.5.

NOTE: Task lists are implemented as varlist in DocBook.
9.6 Description lists (indented)

Example 9.5: Description list

    Item :: Description

yields:

Item
    Description 

9.7 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.

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)
                  o 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:

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 9.6: Table

|| ----------------------------- ||
|| 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
#thisTable2

yields:
Table 9.2: This Table Head      Categories
Row1    Value1  Value1
Row2            Value2
Row3    Value3
Source: My Head, 2004

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 9.7: Table styles

#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

yields:

Test grid & scriptsize styles:
Head    A       B
Foot    X       Y
Row1    1       2
Row2    3       4

Test formal & footnotesize styles:
Head    A       B
Foot    X       Y
Row1    1       2
Row2    3       4

Test box & small styles:
Head    A       B
Foot    X       Y
Row1    1       2
Row2    3       4

Test overlay style:
Head    A       B
Foot    X       Y
Row1    1       2
Row2    3       4
9.8 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 9.8: Anchors

* This is section one
#labSectOne2

Some text.
#labSomeText2

#labSectTwo2
* This is section two

9.9 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.

Simple
    Any word in CamelCase is turned into a wiki name – save if wikification is prevented with a backslash – see 9.1.2. 
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.

          “*”
              open page in new window 
          “$”
              set rel="nofollow" 
          “!”
              prevents deplate from adapting the reference’s suffix
                  o 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.
                  o 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.

        * If you want a hyperlink to have an image, use: [[http://www.example.com][{img: example_image}]]. See also 12.5.

InterWikis
    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") 

Wiki Names are automatically marked as index entries – see 11.4 and 11.5.

Example 9.9: Wiki names

WikiName
WikiName#anchor

[-name-]
[-some name-]#there
[--]#here

::WikiName
::WikiName#there
::[-some name-]
::[-some name-]#there

[[destination]]
[[destination][name]]
[[destination#anchor][name]]
[[destination.suffix]!]
[[::destination#anchor][name]]
[[#anchor]]
[[#anchor][name]]

9.10 Symbols

The backtick (`) is used to introduce some symbols like quotation marks (e.g., in positions where deplate would choose the wrong one).

Symbols are not expanded in text marked as typewriter/code and in verbatim regions.

Example 9.10: Symbols

<-, ->, <=, =>, <~, ~>, <->, <=>, <~>, !=, ~~, ..., --, ==, ```, `'', ``, `'

''->'', ''<-''

#Verb <<--
<-, ->, <=, =>
--

#Code id=symbolsTest syntax=ruby <<--
<-, ->, <=, =>
--

yields:

←, →, ⇐, ⇒, <~, ~>, ↔, ⇔, <~>, ≠, ≈, …, –, ≡, “, ”, ‘, ’

->, <-

<-, ->, <=, =>

<-, ->, <=, =>

NOTE: If you want to disable some of these symbols, you could add some ruby code like this to your config.rb:

%%class Deplate::Particle::Symbol
%%   @@symbols_table.delete_if {|k,v| ['<->', '<=>', '<~>'].include?(k)}
%%   reset_symbols
%%end

9.11 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 9.11: Markers

    - elaborate+++
    - here###
    - questionable???
    - attention!!!

yields:

    * elaborate+++
    * here###
    * questionable???
    * attention!!!

9.12 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 9.12: Notes

Indented paragraphs that begin with a marker and a subsequent space 
start an annotation.
    !!! Something like this.

yields:

Indented paragraphs that begin with a marker and a subsequent space start an annotation.

Something like this.
9.13 Strings, Smart Quotes

Example 9.13: Quotes

"Text in quotes"

yields:

“Text in quotes”

NOTE: Quotes are handled by two classes: Deplate::Particle::DoubleQuote and Deplate::Particle::SingleQuote. In order to disable smart quotes add this code to your config.rb:

Deplate::Particle.disable_particle(
    Deplate::Particle::DoubleQuote,
    Deplate::Particle::SingleQuote
)

9.14 Textstyles

Example 9.14: Text styles

__emphasize__, ''typewriter''

yields:

emphasize, typewriter

NOTE: There must not be a whitespace after the opening mark.

NOTE: Text in typewriter style is basically set verbatim with the expection of backslashes.
9.15 Breaks

A break is marked by at least 2 dashes, “8<”, and again at least 2 dashes.

I say so.
----8<--------------
Summary:
--8<--

In HTML output, a break is represented by a horizontal line. In other output formates, a break actually denotes a page break.
9.16 Whitespace

A line of whitespace usually separates text elements – e.g. paragraphs,

%%* table test
%%#R: drop <<---
%%data(tli)
%%x <- tli
%%save.image(compress=T)
%%---

%%#R: xtable <<---
%%fm1 <- aov(tlimth ~ sex + ethnicty + grade + disadvg, data=x)
%%fm1.table <- xtable(fm1)
%%print(fm1.table,type="html")
%%---
%%#CAP: An example from the xtable manual using the tli data set

%%#R <<---
%%summary(x)
%%---
%%#CAP: Summary of the tli data set

%%#R guess! <<---
%%summary(x)
%%---
%%#CAP: Summary of the tli data set (guessing cell borders)

%%The same inserted verbatim:
%%#R: verb <<---
%%summary(x)
%%---