
.:comment
This document is in Kwid format.  To read this, use a Kwid formatter,
like "pugsdoc perlkwid".

.:comment
This document was stolen directly from perlpod.pod. It is a more or less
direct translation. Therefore it covers a lot of ground that wouldn't show
up in your everyday Kwid document. So if you think this document reads
cleanly, a pedestrian Kwid document should read much more so.

= NAME

perlkwid - the Kwiki Documentation format

= DESCRIPTION

Kwid is a simple-to-use markup language used for writing documentation
for Perl, Perl programs, and Perl modules. It was inspired by the Kwiki
wiki markup language and Perl's traditional Pod language.

# XXX a white lie for now :)
Translators are available for converting Kwid to various formats
like plain text, HTML, man pages, Pod, and more.

Kwid markup consists of three basic kinds of paragraphs:
[ordinary|/Ordinary Paragraph],
[verbatim|/Verbatim Paragraph], and 
[command|/Command Paragraph].

== Ordinary Paragraph

Most paragraphs in your documentation will be ordinary blocks
of text, like this one.  You can simply type in your text without
any markup whatsoever, and with just a blank line before and
after.  When it gets formatted, it will undergo minimal formatting, 
like being rewrapped, probably put into a proportionally spaced
font, and maybe even justified.

You can use formatting codes in ordinary paragraphs, for *bold*,
/italic/, `code-style`, [hyperlinks|perlfaq], and more. Such codes are
explained in the "[Formatting Codes]" section, below.

Note that *bold*, /italic/ and `code` are nicer abbreviated forms of
{*bold*}, {/italic/} and {`code`}, and can be used in 95% of use cases
when there is no ambiguity. Since bold is ended with `*}`, bolding three
asterisks is simply `{*****}`, with no extra escaping. And bold `*}` is
simply `{*\\*}*}`. See following note for explanation.

It should be mentioned early that a backslash character "\\" can
be used to /cancel/ any given format. So \*this is not bold* and this
\http://foo.com is not a hyperlink and this:
\= Is Not A Heading

In practice backslashes should be very rare. But it is good to point out
early, so that you know that all the possibilities are covered. /More on
escaping below./

== Verbatim Paragraph

Verbatim paragraphs are usually used for presenting a codeblock or
other text which does not require any special parsing or formatting,
and which shouldn't be wrapped.

A verbatim paragraph is distinguished by having a sequence of
spaces/tabs at the beginning of all its lines. Leading tabs are
converted to spaces on an 8-column boundary. Intermediate blank lines
count regardless of the number of spaces in them. Leading spaces are
stripped off of all lines one space at a time until one of the lines is
flush left. The remaining content should be reproduced exactly, with
tabs assumed to be on 8-column boundaries. There are no special
formatting codes, so you can't italicize or anything like that. A \\
means \\, and nothing else.

In addition, Kwid provides the `.verbatim` format. You don't need to indent
the content, which can be handy for some editors that do not support block
indenting.

== Command Paragraph

A command paragraph is used for special treatment of whole chunks
of text, usually as headings or parts of lists.

All command paragraphs start with an indicator, followed by a space
character, followed by arbitrary text that the command can use however
it pleases. Currently recognized commands are:

    # A comment line
    = Heading Level 1 (Most prominent)
    == Heading Level 2
    === Heading Level 3
    ==== Heading Level 4 (Least prominent)
    .verbatim
    ..verbatim
    .list indentlevel
    ..list
    * unordered (bulleted) list item
    + ordered (numbered) list item
    - definition list item
    =kwid
    =cut
    .format
    ..format
    .:format text...

To explain them each in detail:

.list
- `# A comment line`

A comment line is thrown away by the Kwid parser. It is used by the Kwid
author to annotate the markup, or to temporarily /turn off/ lines of
Kwid.

To be clear, a comment line must begin with one or more hash signs, be
followed by a whitespace char, and extends only to the end of the line. To
comment out a paragraph, you must comment out every hard line in it.

Another way to do block comments is like this:

    .comment
    == Some Heading

    Some text
    ..comment

- `= Heading Level 1`
- `== Heading Level 2`
- `=== Heading Level 3`
- `==== Heading Level 4`

`=` through `====` produce headings, `=` being the highest level.
The text in the rest of this paragraph is the content of the heading.
For example:

  == Object Attributes

The text "Object Attributes" comprises the heading there. The text in
these heading commands can use formatting codes, as seen here:

  == Possible Values for `$/`

Such commands are explained in the "[Formatting Codes]" section, below.

- `.verbatim`
- `..verbatim`

To specify verbatim text, you can either indent it or used the `.verbatim`
format. The following two sections are equivalent:

    A Perl6 Subroutine:
        sub greet (Str $name) {
            print "Hello, $name\n";
        }
    Simple, eh?

    A Perl6 Subroutine:
    .verbatim
    sub greet (Str $name) {
        print "Hello, $name\n";
    }
    ..verbatim
    Simple, eh?

- `* unordered list item`
- `+ ordered list item`

`.list`, `-`, `*`, and `+` require a little more explanation: ".list"
starts a region specifically for the generation of a list using `-`,
`*`, and `+` commands. At the end of your list, use "..list" to end it.
The /indentlevel/ option to ".list" indicates how far over to indent,
generally in ems (where one em is the width of an "M" in the document's
base font) or roughly comparable units; if there is no /indentlevel/
option, it defaults to four. (And some formatters may just ignore
whatever /indentlevel/ you provide.) In the /stuff/ in `- /stuff.../`,
you may use formatting codes, as seen here:

  - Using `$|` to Control Buffering

Such commands are explained in the "[Formatting Codes]" section, below.

One thing to note is that Kwid, unlike Pod, allows you to make simple
lists without marking the beginning and ending ".list" and "..list". You
can start any line with a "*", "+" or "-". The list continues until the
next paragraph that doesn't start with a "*", "+" or "-". You can even do
multi-level lists by using more than one "*", "+" or "-". Like this:

    * People
    -- Larry

    The creator of Perl

    -- Tom  Number 2
    -- Randal
       Karaoke Master and
    wizard.

    * Places
    ++ London is the place where the
       London Perl Mongers meet. 

    ++ France is a fine place
       for Lance.
    ++ Seattle is home,
    but I still like to roam. 

The catch is that each list item must be a single paragraph. For
multiparagraph list items you'll need ".list". In other words, if the
parser can guess where to put the ".list" markers, you don't need them.

Note also that there are some basic rules to using ".list" ...
"..list" regions:

.list
* The first thing after the ".list" command should be a "-" or "*" or
  "+" command.
* Don't put "=" (header) commands inside a ".list" ... "..list" region.
* And perhaps most importantly, keep the items consistent: either use
  "*" for all of them, to produce bullets; or use "+" to produce
  numbered lists; or use "-" for things that look nothing like bullets
  or numbers.

If you start with bullets or numbers, stick with them, as formatters
use the first item type to decide how to format the list.
..list

- `=cut`

To end a Kwid block in Perl code, use a line beginning with "=cut". This
lets Perl (and the Kwid formatter) know that this is where Perl code is
resuming. Note that `=cut` is not part of Kwid at all. It is simply a Perl
marker used in conjunction with Kwid.

- `=kwid`

The "=kwid" command by itself doesn't do much of anything, but it
signals to Perl (and Kwid formatters) that a Kwid block starts here.
For example:

  =kwid - stuff()

  This function does stuff.

  =cut

  sub stuff {
    ...
  }

  =kwid

  Remember to check its return value, as in:

    stuff() || die "Couldn't do stuff!";

  =cut

Note that `=kwid` is not part of Kwid at all. It is simply a Perl marker
used in conjunction with Kwid.

Note that any text following "=kwid ", on the same line, is added as to the
front of the rest of the Kwid section.

- `.formatname`
- `..formatname`

`.formatname` and `..formatname` will let you have regions of
text/code/data that are not generally interpreted as normal Kwid text,
but are passed directly to particular formatters, or are otherwise
special. A formatter that can use that format will use the region,
otherwise it will be completely ignored.

A command ".formatname", some paragraphs, and a
command "..formatname", mean that the text/data inbetween
is meant for formatters that understand the special format
called /formatname/.  For example,

  .html
  <hr> <img src="thang.png">
  <p> This is a raw HTML paragraph </p>
  ..html

The command ".:formatname"
specifies that the remainder of just this paragraph (starting
right after /formatname/) is in that special format.

  =for html <hr> <img src="thang.png">
  <p> This is a raw HTML paragraph </p>

This means the same thing as the above ".html" ... "..html" region.

That is, with ".:formatname", you can have only one paragraph's worth
of text (i.e., the text in ".:targetname text..."), but with
".targetname" ... "..targetname", you can have any amount
of stuff inbetween.

You can remember the syntax like this

        .format
    +  ..format
    -----------
    =  .:format

In other words, `.:format` is like adding or combining `.format` and
`..format` into one command. And that's what it does!

Here are some examples of how to use this:

  .html
  <br>Figure 1.<br><IMG SRC="figure1.png"><br>
  ..html

  .pod
  =head1 Music

  B<Rock> E<amp> I<Roll>

  =cut
  ..pod

  .text
    ---------------
    |  foo        |
    |        bar  |
    ---------------

  ^^^^ Figure 1. ^^^^
  ..text

  .:use Kwid::Tables

  .:table
  qty description         price   total
  --- ------------------- ------- --------
  3   Widgets             $0.50   $1.50
  2   Turtle Doves        $1.23   $2.46

  .comment
  These lines are
  ignored.
  ..comment

  .indent 4
  This text will be indented four spaces.
  ..indent 4

  .:include poem.kwid

  .:template copyright.tt2
  year: 2005
  license: artistic

Formatted blocks that have no ending marker are assumed to go to the end
of the available Kwid text within that scope. (They cannot go past an
`=cut` directive.)

Formatted paragraphs end with a blank line or another formatted section.

Some formats like `.indent` can take extra arguments. (In this case, the
number of spaces of 'ems' to indent.

Some format names that formatters currently are known to accept
include "roff", "man", "latex", "tex", "text", and "html".  (Some
formatters will treat some of these as synonyms.)

A format name of "comment" is common for just making notes (presumably
to yourself) that won't appear in any formatted version of the Kwid
document:

  .comment
  Make sure that all the available options are documented!
  ..comment

Same as:

  # Make sure that all the available options are documented!

- Character Encoding

Pod has support for various unicode encodings using `=encoding /encoding
name/`. At this point in history, we seem to be converging on utf8.
Therefore all Kwid documents are assumed to be utf8.
..list

Some examples of lists include:

  * First item
  * Second item
  .list
  - Foo() 
  Description of Foo function
  - Bar() 
  Description of Bar function
  ..list

== Formatting Codes

In ordinary paragraphs and in some command paragraphs, various
formatting codes (a.k.a. "interior sequences") can be used:

.:comment
 "interior sequences" is such an opaque term.
 Prefer "formatting codes" instead.

- `/text/` -- italic text

Used for emphasis ("{`be /careful!/`}") and parameters ("{`redo /LABEL/`}")

- `*text*` -- bold text

Used for switches ("{`perl's *-n* switch`}"), programs ("{`some systems
provide a *chfn* for that`}"), emphasis ("{`be *careful!*`}"), and so on
("{`and that feature is known as *autovivification*`}").

- {``code``} -- code text

Renders code in a typewriter font, or gives some other indication that
this represents program text ("{``gmtime($^T)``}") or some other
form of computerese ("{``drwxr-xr-x``}").

- `[name]` -- a hyperlink

There are various syntaxes, listed below. In the syntaxes given, `text`,
`name`, and `section` cannot contain the characters '/', '|', '[', or ']'.

.list
* `[name]`

Link to a Perl manual page (e.g., `[Net::Ping]`). Note that `name`
should not contain spaces. This syntax is also occasionally used for
references to UNIX man pages, as in `[crontab(5)]`.

* `[name/sec]`

Link to a section in other manual page.  E.g., `[perlsyn/For Loops]`

* `[/sec]` or `[sec]`

Link to a section in this manual page.  E.g., `[Object Methods]`
Note that unless the '/' is present `sec` must contain one or more spaces.

..list

A section is started by the named heading or item. For example,
`[perlvar/$.]` links to the section started by "{`- $.`}" in perlvar.
And `[perlsyn/For Loops]` links to the section started by `== For
Loops` in perlsyn.

To control what text is used for display, you use "{`[text|...]`}", as in:

.list

* `[text|name]`

Link this text to that manual page. E.g., `[Perl Error Messages|perldiag]`.

* `[text|name/sec]`

Link this text to that section in that manual page.  E.g.,
`[SWITCH statements|perlsyn/Basic BLOCKs and Switch Statements]`

* `[text|/sec]`

Link this text to that section in this manual page.  E.g.,
`[the various attributes|/Member Data]`

..list

Or you can link to a web page:

.list

* `scheme://...`

or

* `[scheme:...]`

Links to an absolute URL.  For example, `http://www.perl.org`. 
Unlike with Pod, you can also do a named link:

    [text|scheme:...]

..list

- `&escape;` -- a character escape

Exactly similar to HTML/XML `&foo;` "entity references":

- `{ text }` -- text is rendered asis with non-breaking spaces

This means that the words in /text/ should not be broken across lines.
Example: `{ $x ? $y : $z }`. Note that this markup begins with a left
brace and a space and ends with a space and a right brace.

# The file markup seems crufty. Keeping it for Pod compatibility, but using
# an elongated form to discourage use.
- `{file: filename}` -- used for filenames

Typically displayed in italics.  Example: "`{file: .cshrc}`"

# Also crufty
- `{index: topic name}` -- an index entry

This is ignored by most formatters, but some may use it for building
indexes.  It always renders as empty-string.
Example: `{index: absolutizing relative URLs}`

- `{}` -- a null (zero-effect) formatting code

This is rarely used. It is included to roundtrip Pod's rarely used `Z<>`
format.

.:comment
This was formerly explained as a "zero-width character". But it in most
parser models, it parses to nothing at all, as opposed to parsing as if
it were a E<zwnj> or E<zwj>, which are REAL zero-width characters. So
"width" and "character" are exactly the wrong words.

..list

== The Dirty Bits

Similar to Perl itself, Kwid tries to make simple things clean and dirty
things possible. In other words, Kwid optimizes for the normal cases,
but keeps a couple tricks up its sleeve to deal with conflicts between
content and markup.

.list

- Curly brace markers

Consider the following:

   Don't forget the *butter*, I really need it.

The word "butter" is bolded, because the asterisks are /hugging/ the
word. The beginning asterisk is /hugging/ because it is preceded by a
whitespace char and followed by a word char. The ending asterisk is
/hugging/ because it is preceded by a word char and followed by
whitespace char. Certain common punctuation chars are allowed to be
between the asterisks and the word chars they hug.

There are many cases when a pair of asterisks will not cause bolding. At least
not as you might expect.

   Don't forget the * butter*, I really need it.
   Don't forget the *butter*,*bread*, and salt.
   I like butter. *(Know what I mean)*? 

The solution is to use curly braces.

   Don't forget the {* butter*}, I really need it.
   Don't forget the {*butter*},{*bread*}, and salt.
   I like butter. {*(Know what I mean)*}? 

In the explicit curly brace form, `{*` is the starting marker, and `*}`
is the ending marker. More specifically, a starting marker is one or
more left curly braces followed a formatting character. An ending
marker is the same formatting char followed by one or more (but the
same number) right curly braces.

This can used for all the phrase formats:

   Code:   {`my $my_files = `ls -1 ./my_dir``}
   Italic: {//etc/apache//}
   Bold:   {**** WARNING ***: Danger!*}
   Links:  {[$foo[2]|arrays/Indexing Arrays]}
   Asis:   {{{ { {{ ... }} } }}}

There are also /named/ formats that have the form: `{foo:...}`. For
instance the filename format:

   File:   {file:/path/to/file}

These named formats can be used to extend the language in much the same
way that named blocks do.

- Backslash escaping

Unless other escaping mechanisms are in control a backslash followed by
another character renders as that character and is not used as markup.
This is how you can defeat certain markup chars when they are meant to
be content. A \\ at the end of a line is really just a \\ followed by a
newline. In paragraph context that would indicate a hard line break, rather
than folding text. A content backslash must be written as "\\\\". 

One exception is the a single backslash followed by a whitespace char
indicates a hard line ending. This is true even if it is in the middle of a
line (because a paragraph might have been wrapped by an editor).

   \== Not a header
   \# Not a comment
   \* Not a list item
   This is not a \[link].
   This is not \{*bold*}.

   This line has a hard line ending\
   and is not folded with this line.\
   This is one line.\ And this is another.

..list

== The Intent

The intent is simplicity of use, not power of expression.  Paragraphs
look like paragraphs (block format), so that they stand out
visually.  I wanted the translator to always leave the `'` and {```} and
`"` quotes alone, in verbatim mode, so I could slurp in a
working program, shift it over four spaces, and have it print out, er,
verbatim.  And presumably in a monospace font.

The Kwid format is not necessarily sufficient for writing a book. Kwid
is just meant to be an idiot-proof common source for nroff, HTML,
TeX, and other markup languages, as used for online
documentation.  Translators exist for *kwid2text*, *kwid2html*,
*kwid2man* (that's for nroff(1) and troff(1)), *kwid2latex*, and
*kwid2fm.  Various others are available in FreePAN.

== Embedding Kwid in Perl Modules

You can embed Kwid documentation in your Perl modules and scripts. Start
your documentation with a "=kwid" command at the beginning, and end it
with a "=cut" command. Perl will ignore the Kwid text. See any of the
supplied library modules for examples.

  =kwid = NAME

  Time::Local - efficiently compute time from local and GMT time

== Hints for Writing Kwid

# TODO

= SEE ALSO

[perlpod], [perlpodspec],
[perlkwidspec], [perlsyn/PODs: Embedded Documentation],
[perldoc], [kwid2html], [kwid2man], [kwid2pod], [pod2kwid].

= AUTHOR

Brian Ingerson
