/doc/ptt/ptt.tt

D: { <code>
D: } </code>
D: << &lt;
D: >> &gt;
In: /style.css
KW: text,HTML,convert,converter
H1: -qen Ptt  ( ver.4.2 )

2007/09/23 ver.3.0
2007/10/02 ver.3.1
2014/09/10 ver.4.0
2014/09/17 ver.4.0

##:!
I: /image/under-construction.gif align="left"
Much more work is required to be readable English.
!

H2: Introduction
H3: Why Ptt ?
Writing web pages in HTML format is a pain even for well skilled people. For unskilled people, there exist many tools that enable them to create HTML formatted documents using WYSIWYG interface. However they are so beginner oriented that they do not satisfy my needs.

<em>Ptt</em> is a text processor that converts text written in "<em>tt format</em>" to the text in HTML format. Text written in tt format is much more handy and intuitive.

H3: What is Ptt ?
H4: Headers and phrases
The basic idea is in "<em>Putting tags to lines</em>". I think you are already aware the fact that most of HTML tags are meaningful only to lines. However HTML tags are designed to operate to strings. The typical example is header tag such as
<h1>Ptt</h1>
The format is bothersome and makes text difficult to read. Using Ptt we wrie simply
H1: Ptt
HTML " < p > " tags and " < br > " tags are also bothersome. We will want to write the contents as if we are writing in word processor. Using Ptt, " < p > " tags and " < br > " tags are automatically generated.

NN:!
Note: "<i>Putting tags to string</i>" is source of strength of HTML and of formal beauty of HTHML. But that is too bothersome...
!

H4: List
We will frequently write unordered list. HTML "{ < ul > }" and "{ < li > }" are bothersome. In tt text, hyphen at the beginning of line is list items as shown below.
P:!
H3: HTML list
HTML has three list format:
- unordered list
- ordered list
- definition list
-
Ptt supports all thses lists.
!
which will be converted to
P:!
<h3>HTML list</h3>
<p>HTML has three list format:</p>
<ul>
<li>unordered list
<li>ordered list
<li>definition list
</ul>
<p>Ptt supports all thses lists.</p>
!
Note that the last empty hyphen terminates the list.

This rule is simple and intuitive.

H4: Image inclusion
Image file can be included using syntax:
I: cat.jpg
which will result in
I: cat.jpg

H4: Table
Table is very bothersome in HTML. Instead we can write simply
P:!
Ta:
name age
alice 18
bob   20

!
which is enough to genarate.
Ta:
name age
alice 18
bob   20

Note that last empty line terminate the table. In this example, we could specify column width, field separator, etc.

H4: Other abilities
There are many "<em>automatic</em>" in Ptt. Translating old fashioned double quote  {"} to modern left and right double quote pair "  " is one of them. Table of contents is automatically generated, indexing bibliography and referencing citations are also automatic using style similar to LaTeX.

H4: In case we need HTML
Sometimes we might want to embed pure HTML code in tt text or want to make disable excessive kindness of Ptt. Ptt has the way to do these.

This page is written in tt format and is converted to regular HTML format. The original tt text is <a href="ptt.tt">here</a>.

H2: Installation
ptt is written in Lua (ver.5.2).
You need {ptt} and some of Lua library.
You will find them at {http://plan9.aichi-u.ac.jp/netlib/lua/}.

You need style sheet "{style.css}" for Ptt. The style sheet might be updated frequently. You can get current style sheet by accessing {http://ar.aichi-u.ac.jp/style.css}.

H2: The Grammar
H3: General Rule
The followings are general rules of Ptt.
- Tag of tt format is put to line. The tag starts from the begining of line.
- You need not write <b>br</b> tag and <b>p</b> tag.
- You can use HTML tags in your document. If there are spaces in both side of "{ < }" or "{ > }" then they are converted to "{ & lt;}" and "{ & gt;}" respectively.
- "{ & }" in text is HTML escape but "{  &  }" ( "{ & }" with spaces on both side ) will be converted to "{ & amp;}".
- lines that begin with TAB code are shown as it is, which is suitable for programming code
- absolute URLs in text are automatically linked to the UTL.
-

Experimental rules of Ptt 4.0:
- lines that begin with "{ < }" and end with "{ > }" does not cooked by Ptt
- Texts enclosed by the following block tags are not cooked by Ptt:
script style pre textarea form select iframe
-

If you do want these lines to be cooked, insert a space at the beginning of the line.

H3: HTML attributes
We can specify tag attribute of HTML to some of tt tags. The format is
Q: { [ <i>class</i> ] <i>attr</i>="<i>value</i>" <i>attr</i>="<i>value</i>" ...}
or
Q: { [ <i>class</i>="<i>value</i>" ] <i>attr</i>="<i>value</i>" <i>attr</i>="<i>value</i>" ...}
where {<i>class</i>} is a class name, {<i>attr</i>} is attribute and {<i>value</i>} is the value.

Don't put spaces in the <i>value</i>.

H3: Headers
H4: Type of headers
We have following header tags.
H1:   H2:   H3:   H4:
These header tags can be used only outermost level, i.e., outside of any block tags.

H4: title tag of HTML
Subject header "{H1:}" is always required. Subject of the document follows "{H1:}". The subject will be used for both {title} tag and {h1} tag.

H4: Table of contents
Table of contents will be automatically created if we have more than one headers in our text or unless we give an option "don't make table of contents".

H4: Options in "{H1:}"
Header "{H1:}" has some options:
Q: {H1: [-lteq]} <i>title</i>
where characters inside of {[ ]} are options:
- {l} : don't show logo
- {t} : don't make table of contents
- {e} : English document
- {q} : convert {"} to left double quote or right double quote
-

H3: Options in body tag
Body tag options are given by
Q: {BO:} <i>options</i>
which will produce
Q: { < body} <i>options</i>{ > }
Body tag must be located before "{H1:}" tag.

H3: List
H4: List format
We have three types of tag for list.
DL:
- {UL:}
unordered list
- {OL:}
ordered list
- {DL:}
definition list
-
List items begin with "{- }". Empty item or empty line terminate the list.

It is possible to omit "{UL:}". Therefore unordered list can be written simply as
QQ:!
 {-} <i>item1</i>
 {-} <i>item2</i>
 {-}
!
Items may include multiple lines.

Definition list is expressed as
QQ:!
 {DL:}
 {-} <i>name1</i>
 <i>description of name1</i>
 {-} <i>name2</i>
 <i>description of name2</i>
 {-}
!
Description may include multiple lines.

H4: Termination of list
List is terminated by an empty line or a line with only "{-}" or header tags. Use of "{-}" is recommended for clarity.

H4: List option "{-a}"
In case that list tag has "{-a}" option, the first field is regarded as link. Then list items are expressed as
QQ:!
{UL:-a}
{- }<i>url1</i> <i>description1</i>
{- }<i>url2</i> <i>description2</i>
{-}
!
Here these urls are used for the value of "{href}" attribute, and may be anything that are allowed for the value.

In case of "{-a}", these <i>url</i>s are not shown.

H3: Link
It is possible to embed arbitrary HTML tags in tt text. Therefore link tags can be embedded as well. Some strings that mean URL are automatically added link tag. For example,
P:!
Look http://ar.aichi-u.ac.jp/ptt/ for more details.
!
will be converted to
P:!
Look <a href="http://ar.aichi-u.ac.jp/ptt/" target="other">
http://ar.aichi-u.ac.jp/ptt/</a> for more details.
!
Conversion is applied to the unquoted strings that start with
- {http:}
- {https:}
- {ftp:}
-
but for the case they follow double quotation({"}).

H3: Center tag
Center tag that operates to a line is
Q: C: <i>sentence</i>
In case that we have lines to align center, we have syntax:
QQ:!
{CC:} <i>term</i>
 <i>line1</i>
 <i>line2</i>
...
<i>term</i>
!

H3: Image
In including image file, we can use "{I:}" tag or "{II:}" tag.
H4: A single image
The following is an example to include single image.
P:!
I: cat.jpg
!
Following the file name, we can specify<sup>*</sup> the size of display. For example,
P:!
I: cat.jpg width=400
!
will display 400 pixels image at the center of line.

The common rule is:
Q: {I:} <i>file</i> [<i>size</i>] [<i>options</i>]
where <i>file</i> is a image file name, <i>size</i> is the display size and <i>options</i> is HTML options that can be assigned to {img} tag. Size is given like: 60% or 640.

H4: Image array
Image array is expressed as
QQ:!
 II: <i>term</i> [ <i>options0</i> ]
 <i>title1</i> <i>file1</i>  [ <i>options1</i> ]
 <i>title2</i> <i>file2</i>  [ <i>options2</i> ]
 ...
 <i>term</i>
!
Image array is implemented using table.

"<i>options0</i>" is options(table attributes) to the table and is expressed for example,
width="90%"
The default width is "60%" in case of single image, "90%" in other case. "<i>options1</i>", "<i>options2</i>" ... are options to each element of the table. The most useful usage is to specify the weight of width of the image by writing like:
width="30%"
If the weights are not given, equal weight is assumed.

For example
P:!!
II:!
lily lily.jpg
iris iris.jpg
portyeraka portyeraka.jpg
!
!!
will produce
II:!
lily lily.jpg
iris iris.jpg
portyeraka portyeraka.jpg
!

N: <b>NB:</b> IE does not display correctly.

You will want to have images of same height. However HTML does not have such option.

Other example is
P:!!
II:!
lily lily.jpg width="30%"
iris iris.jpg  width="40%"
portyeraka portyeraka.jpg width="20%"
!
!!

II:!
lily lily.jpg width="30%"
iris iris.jpg  width="40%"
portyeraka portyeraka.jpg width="20%"
!

You need not make 100%. If name contains spaces, use single quote(') or double quote(").

D: D <i>d</i>
H3: Table
Table support is limited to a simple one like matrix. The format is something like:
QQ:!
 Ta: D  &nbsp;  [ <i>options</i> ]
 Ca: <i>caption</i>
 <i>name</i>:<i>format</i> D <i>name</i>:<i>format</i> D <i>name</i>:<i>format</i>
 <i>item</i> D <i>data</i> D <i>data</i>
 <i>item</i> D <i>data</i> D <i>data</i>

!

The D is a single letter which delimits fields. If delimiter is not given, space is assumed. Put spaces between delimiters for empty items, because sequence of delimiters might be given special meaning in future.

D: D

<i>Options</i> is HTML options for table tag. The default is
Q:{Ta: align="center"}
Table design is determined by style sheet.

- "{Ca:}" is optional
- "{Ta:}" is terminated by a empty line
-

If all <i>name</i>s are absent, item header is not shown. For example
P:!
Ta:
 :   :   :
alice 16 female
bob  20 male

!
will produce
Ta:
 :   :   :
alice 16 female
bob  20 male

and "{:-}" will hide the column, i.e.,
P:!
Ta:
 :-   :   :
alice 16 female
bob  20 male

!
will produce
Ta:
 :-   :   :
alice 16 female
bob  20 male

If some of <i>name</i>s are absent, the item headers are spanned. For example
P:!
Ta: |
:- | 2000 | | | 2010 | |
   | <b>name</b> | <b>age</b> | <b>sex</b> | <b>name</b> | <b>age</b> | <b>sex</b>
   | <b>alice</b> | 16 | female | <b>alice</b> | 26 | female
   | <b>bob</b> | 20 | male | <b>bob</b> | 30 | male

!
will produce
Ta: |
:- | 2000 | | | 2010 | |
   | <b>name</b> | <b>age</b> | <b>sex</b> | <b>name</b> | <b>age</b> | <b>sex</b>
   | <b>alice</b> | 16 | female | <b>alice</b> | 26 | female
   | <b>bob</b> | 20 | male | <b>bob</b> | 30 | male

You will find more natural solution later (Look "Long definition"</a> in subsection "String definition".)

Format is specified as:
Ta: | width="40%" align="center"
 :- | <i>format</i>:50% | meaning:50%
    |{ < }<i>width</i> | left align
    | <i>width</i> | center align
    |{ > }<i>width</i> | right align
    | {-} | hidden

Note:
- Formats are optional. The default is "center align" and "minimum width".
- Widths are optional. The default is "minimum width".
- In case that "%" in width is omitted, pixel is assumed.
-

We show the code of above table below as an example.
P:!
D: { <code>
D: } </code>
Ta: | width="40%" align="center"
 :- | <i>format</i>:50% | meaning:50%
    |{ < }<i>width</i>  | left align
    | <i>width</i>      | center align
    |{ > }<i>width</i>  | right align
    |{-}                | hidden
!
where "{D:}" tag is used so that we can avoid annoying "{ < code > }" and "{ < /code > }" pairs. Look subsection "String definition" for this topic.

Variety of table style can be defined in style sheet.

<b>Note:</b> Sequence of contiguous delimiter might be given special meaning in future. Put spaces for empty table elements.

H3: Programing code
We have two method to show program code, which means the text is shown as it is.
First, lines beginning with TAB code
Second, we have "{P:}" tag. The syntax is,
QQ:!
 {P:} <i>term</i> [ tab=<i>n</i> ]
 <i>program code</i>
 <i>term</i>
!
where "{tab=}<i>n</i>" specifies tab size. The default is 8.

For example, If we want to show the following C code
P:!
#include <stdio.h>
main(){
printf("OK\n");
}
!
then
P:*
P:!
#include <stdio.h>
main(){
printf("OK\n");
}
!
*
is enough.

H3: Note
We have two types of "note".
H4: Short note.
Short note means single line note. The syntax is
Q: {N:} <i>note</i>

H4: Long note
Syntax of long note is
QQ:!
 {NN:} <i>term</i>
 <i>note</i>
 <i>note</i>
 ...
 <i>term</i>
!
where "<i>term</i>" is a terminator string.

H3: Quote
We have two types of "quote".

H4: Short quote
Short quote means single line quote. The syntax is
Q: {Q:} <i>quote</i>
H4: Long quote
Syntax of long quote is
QQ:!
 {QQ:} <i>term</i>
 <i>quote</i>
 <i>quote</i>
 ...
 <i>term</i>
!
where "<i>term</i>" is a terminator string.

H3: Comment
Comment area of tt text is not converted to HTML.
H4: Short comment
Short comment is a single line comment. The syntax is
Q: #: <i>comment</i>
H4: Long comment
Syntax of long comment is
QQ:!
 {##:} <i>term</i>
 <i>comment</i>
 <i>comment</i>
 ...
 <i>term</i>
!
where "<i>term</i>" is a terminator string.

H3: Pure HTML mode
Pure HTML mode is uncooked mode. The syntax is
QQ:!
 {!!:} <i>term</i>
 ...
 ...
 <i>term</i>
!

Now, using Ptt 4.0, this mode will seldom be required.

H3: String definition
H4: Short definition.
We can define string so that the string can be replaced by some other string. The syntax is
Q: {D:} <i>from</i> <i>to</i>
where "<i>from</i>" and "<i>to</i>" are string, which means "<i>from</i>" is replaced by "<i>to</i>".
For example, If we define
P:!
D: { <code>
D: } </code>
!
then
{sample.txt}
will be replaced by
<code>sample.txt</code>
H4: Long definition
Syntax of long definition is
QQ:!
 DD: <i>from</i> <i>term</i>
 <i>to1</i>
 <i>to2</i>
 ...
 <i>term</i>
!
which means "<i>from</i>" is replaced by several lines:
 <i>to1</i>
 <i>to2</i>
 ...

We have another type of long definition: "{DD+:}" which is used if we want to convert the "to" parts following tt syntax. "{DD+:}" is useful if we want to construct complex table.

DD+: $1 !
Ta: class=noframe
name age sex
alice 16 female
bob   20 male

!

DD+: $2 !
Ta: class=noframe
name age sex
alice 26 female
bob   30 male

!

Ta: class=nopad align="center"
:-   2000 2010
-   $1 $2

This table is expressed as following.
P:==
DD+: $1 !
Ta: class=noframe
name age sex
alice 16 female
bob   20 male

!

DD+: $2 !
Ta: class=noframe
name age sex
alice 26 female
bob   30 male

!

Ta: class=nopad
:-   2000 2010
-   $1 $2

==

where "{noframe}" denotes no-frame table:
<div style="width:160px;margin-right:auto;margin-left:auto">$1
</div>
D: $1
D: $2
and "{nopad}" denotes solid border table of cell padding=0.

Ptt handles the problem on constructing complex tables by embedding table into table element.

H4: Undefine
Q: {D:} <i>from</i>
will clear the definition.

H2: Label and the References
D: [
D: ]
P:!
Plan 9<sup>[<ref(cite:Plan9)>]</sup> is deveploped ...
...

H2: References
[<lab(cite:Plan9)>] Plan 9 from Bell Labs
http://plan9.bell-labs.com/plan9/
!
will produce,

QQ:!
Plan 9<sup>[1]</sup> is deveploped ...
...
H2: References
[1] Plan 9 from Bell Labs
http://plan9.bell-labs.com/plan9/
!

Syntax of the label and the reference is
D: {
D: }

QQ:!
 <code> < lab(<i>key:label</i>) > </code>
 <code> < ref(<i>key:label</i>) > </code>
!
You may use "<code>{</code>" and "<code>}</code>" instaed of "<code>(</code>" and "<code>)</code>" respectively. That is,
QQ:!
 <code> < lab{<i>key:label</i>} > </code>
 <code> < ref{<i>key:label</i>} > </code>
!

Serial numbers are automatically given by ptt for each <i>key</i>.

Other example:
P:!
C: Fig.<lab(fig:cat)>: My lovely cat
....
The cat shown in Fig.<ref(fig:cat)> is living in my room.
....
!

H2: Summary
D: [
D: ]
D: { <code>
D: } </code>
H3: Terminology
Some terminologies are listed below. Here "RE" is regular expression.
Ta: !
terminology  ! RE syntax ! comment:<
string ! {.+} ! a sequence of characters
unquoted string ! {[^"']?[^ ]*} !  a string that does not begin with quotation mark<br> and that does not contain spaces
quoted string ! {("[^"]*")|('[^']*')} ! a string quoted by single or double quotation mark
line ! {.*$} ! a string up to newline
size ! {[1-9][0-9]*[%]?}  !  n or n%, n is non-negative number
delimiter ! {[^- ]} ! a letter that separate fields
terminator ! {[^- ]+} ! string to terminate block
table format ! {[ <  > -]?[1-9][0-9]*[%]?} ! specifies alignment and size of the field

H3: Tags
In the following table, "..." means repetition, and [ ] in syntax means optional part.

Ta:|
Ca: Tag table
tag:<  | meaning:<150  | syntax:<300
 {H1:}| heading<br>({H2:},{H3:},…) | {H1:[-lteq]} line
 {KW:}| keyword | {KW: keyword,...}
 {BO:} | body option | {BO: options}
 {UL:}  | unordered list<br>(omissible) | {UL:[-a][+a]}<br>{-} lines<br>{-} lines<br>…<br>{-}
 {OL:} | ordered list | {OL:[-a][+a]}<br>{-} lines<br>{-} lines<br>…<br>{-}
 {DL:} | definition list | {DL:[-a][+a]}<br>{-} lines<br>{-} lines<br>…<br>{-}
 {C:} | center align | {C:} line
 {CC:} | center align | {CC:} term [options]<br>lines<br>term
 {I:}  | image inclusion | {I:}url [alt [size [options]]]
 {II:}  | image array | {II:} term [options]<br>title url [options]<br>title url [options]<br>...<br>term
 {Ta:} | table | {Ta:}[deli] [options]<br>[{Ca:} line]<br>string[:format] [deli] string[:format] [deli] …<br>string [deli] string      [deli] …<br>string [deli] string [deli] …<br>…<br>
 {Ca:} | caption<br>use next to {Ta:} |{Ca:} line
 {P:} | program code | {P:}term [{tab=}size]<br>lines<br>term
 {N:} | short note | {N:}line
 {NN:} | long note | {NN:}term [options]<br>lines<br>term
 {Q:} | short quote | {Q:}line
 {QQ:} | long quote | {QQ:}term [options]<br>lines<br>term
 {#:} | short comment | {#:}line
 {##:} | long comment | {##:}term<br>lines<br>term
 {D:} | string defintion | {D:} str subst
  {DD:}<br>{DD+:} | string definition | {DD:} str term<br>lines<br>term
 {!:} | pure HTML mode |
 {!!:} | pure HTML mode | {!!:}term<br>lines<br>term

DD+: OPT !
an optional part. The syntax is
[class] [attribute="value"] ...
note: spaces must not be included in the value
!

Words used in syntax in tag table are given in the following table.
Ta: |
word | meaning:<
lines |  line<br>line<br>...
term |  an unquoted string used for terminator
str |  an unquoted string or a quoted string
format | table format
url | a value that is used for href or src attribute
deli |  a delimiter
title | an unquoted string or a quoted string
options | OPT
subst | an unquoted string or a quoted string<br>that substitutes str
patt | an unquoted string or a quoted string<br>that follows syntax regular expression pattern
repl | an unquoted string or a quoted string<br>that follows syntax replacement of regular expression

D: OPT

H3: Restriction
- Nested lists are not supported.

H3: Notice
D: {
D: }
D: [ <code>
D: ] </code>
H4: Kanji space
Kanji space generates warning.

H4: rit support
If tt text begin with
#!/
then Ptt assumes that there are embedded codes. Then the code area is assumed in the aread
QQ:!
[${]
<i>code</i><br>
[}$]
!

H3: Double quotation
The auto-conversion algorithm stands on the following consideration:
OL:
- code area and data area are out of conversion
- double quotations in tag do not converted
- left double quote and right double quote appears in pair
- left double quote appears only at the beginning of line or at the right of space
- right double quote appears only at the end of line or at the left of character in "[ ,.;:!?]".
-