/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 these 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 these 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://p9.nyx.link/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.nyx.link/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.nyx.link/ptt/ for more details.

!

will be converted to

P:!

Look <a href="http://ar.nyx.link/ptt/" target="other">

http://ar.nyx.link/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

simply a preformat.

D: [

D: ]

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> [<i>options</i>]

 <i>program code</i>

 <i>term</i>

!

tabsize can be an option. The default is 8.

And for long program, an option

	style="overflow:auto; height:50ex"

may be better.

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</h2>

[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 "[ ,.;:!?]".

-