Ptt ( ver.4.2 )

Contents

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

1. Introduction

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

Ptt is a text processor that converts text written in “tt format” to the text in HTML format. Text written in tt format is much more handy and intuitive.

1.2. What is Ptt ?

1.2.1. Headers and phrases

The basic idea is in “Putting tags to lines”. 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.

Note: “Putting tags to string” is source of strength of HTML and of formal beauty of HTHML. But that is too bothersome...

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

H3: HTML list
HTML has three list format:
- unordered list
- ordered list
- definition list
-
Ptt supports all these lists.

which will be converted to

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

1.2.3. Image inclusion

Image file can be included using syntax:

I: cat.jpg

which will result in

1.2.4. Table

Table is very bothersome in HTML. Instead we can write simply

Ta:
name age
alice 18
bob   20

which is enough to genarate.

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.

1.2.5. Other abilities

There are many “automatic” 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.

1.2.6. 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 here.

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

3. The Grammar

3.1. 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 br tag and p 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.

3.2. HTML attributes

We can specify tag attribute of HTML to some of tt tags. The format is

class attr="value" attr="value" ...

class="value" attr="value" attr="value" ...

where class is a class name, attr is attribute and value is the value.

Don't put spaces in the value.

3.3. Headers

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

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

3.3.3. 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”.

3.3.4. Options in “`H1:`”

Header “H1:” has some options:

H1: -lteq title

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

3.4. Options in body tag

Body tag options are given by

BO: options

which will produce

< body options >

Body tag must be located before “H1:” tag.

3.5. List

3.5.1. List format

We have three types of tag for list.

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

- item1
- item2
-

Items may include multiple lines.

Definition list is expressed as

DL:
- name1
description of name1
- name2
description of name2
-

Description may include multiple lines.

3.5.2. Termination of list

List is terminated by an empty line or a line with only “-” or header tags. Use of “-” is recommended for clarity.

3.5.3. List option “`-a`”

In case that list tag has “-a” option, the first field is regarded as link. Then list items are expressed as

UL:-a
- url1 description1
- url2 description2
-

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 urls are not shown.

3.6. 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,

Look http://ar.nyx.link/ptt/ for more details.

will be converted to

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(").

3.7. Center tag

Center tag that operates to a line is

C: sentence

In case that we have lines to align center, we have syntax:

CC: term
line1
line2
...
term

3.8. Image

In including image file, we can use “I:” tag or “II:” tag.

3.8.1. A single image

The following is an example to include single image.

I: cat.jpg

Following the file name, we can specify^* the size of display. For example,

I: cat.jpg width=400

will display 400 pixels image at the center of line.

The common rule is:

I: file size options

where file is a image file name, size is the display size and options is HTML options that can be assigned to img tag. Size is given like: 60% or 640.

3.8.2. Image array

Image array is expressed as

II: term options0
title1 file1 options1
title2 file2 options2
...
term

Image array is implemented using table.

“options0” 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. “options1”, “options2” ... 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

II:!
lily lily.jpg
iris iris.jpg
portyeraka portyeraka.jpg
!

will produce


lily	iris	portyeraka

NB: IE does not display correctly.

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

Other example is

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


lily	iris	portyeraka

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

3.9. Table

Table support is limited to a simple one like matrix. The format is something like:

Ta: d options
Ca: caption
name:format d name:format d name:format
item d data d data
item d data d data

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.

Options is HTML options for table tag. The default is

Ta: align="center"

Table design is determined by style sheet.

“Ca:” is optional
“Ta:” is terminated by a empty line

If all names are absent, item header is not shown. For example

Ta:
 :   :   :
alice 16 female
bob  20 male

will produce

alice	16	female
bob	20	male

and “:-” will hide the column, i.e.,

Ta:
 :-   :   :
alice 16 female
bob  20 male

will produce

16	female
20	male

If some of names are absent, the item headers are spanned. For example

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

2000			2010
name	age	sex	name	age	sex
alice	16	female	alice	26	female
bob	20	male	bob	30	male

You will find more natural solution later (Look “Long definition” in subsection “String definition”.)

Format is specified as:

format	meaning
`<` width	left align
width	center align
`>` width	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.

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.

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

3.10. Programing code

simply a preformat.

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,

P: term [options]
program code
term

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

#include <stdio.h>
main(){
	printf("OK\n");
}

then

P:!
#include <stdio.h>
main(){
	printf("OK\n");
}
!

is enough.

3.11. Note

We have two types of “note”.

3.11.1. Short note.

Short note means single line note. The syntax is

N: note

3.11.2. Long note

Syntax of long note is

NN: term
note
note
...
term

where “term” is a terminator string.

3.12. Quote

We have two types of “quote”.

3.12.1. Short quote

Short quote means single line quote. The syntax is

Q: quote

3.12.2. Long quote

Syntax of long quote is

QQ: term
quote
quote
...
term

where “term” is a terminator string.

3.13. Comment

Comment area of tt text is not converted to HTML.

3.13.1. Short comment

Short comment is a single line comment. The syntax is

#: comment

3.13.2. Long comment

Syntax of long comment is

##: term
comment
comment
...
term

where “term” is a terminator string.

3.14. Pure HTML mode

Pure HTML mode is uncooked mode. The syntax is

!!: term
...
...
term

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

3.15. String definition

3.15.1. Short definition.

We can define string so that the string can be replaced by some other string. The syntax is

D: from to

where “from” and “to” are string, which means “from” is replaced by “to”.
For example, If we define

D: {	<code>
D: }	</code>

then

{sample.txt}

will be replaced by

<code>sample.txt</code>

3.15.2. Long definition

Syntax of long definition is

DD: from term
to1
to2
...
term

which means “from” is replaced by several lines:
to1
to2
...

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.

2000

2010

name	age	sex
alice	16	female
bob	20	male

name	age	sex
alice	26	female
bob	30	male

This table is expressed as following.

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:

name	age	sex
alice	16	female
bob	20	male

and “nopad” denotes solid border table of cell padding=0.

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

3.15.3. Undefine

D: from

will clear the definition.

4. Label and the References

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,

Plan 9^[1] is deveploped ...
...

References
[1] Plan 9 from Bell Labs
http://plan9.bell-labs.com/plan9/

Syntax of the label and the reference is

< lab(key:label) >
< ref(key:label) >

You may use “{” and “}” instaed of “(” and “)” respectively. That is,

< lab{key:label} >
< ref{key:label} >

Serial numbers are automatically given by ptt for each key.

Other example:

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

5. Summary

5.1. Terminology

Some terminologies are listed below. Here “RE” is regular expression.

terminology	RE syntax	comment
string	`.+`	a sequence of characters
unquoted string	`[^"']?[^ ]*`	a string that does not begin with quotation mark 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

5.2. Tags

In the following table, “...” means repetition, and [ ] in syntax means optional part.

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

Words used in syntax in tag table are given in the following table.

word	meaning
lines	line line ...
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	an optional part. The syntax is [class] [attribute="value"] ... note: spaces must not be included in the value
subst	an unquoted string or a quoted string that substitutes str
patt	an unquoted string or a quoted string that follows syntax regular expression pattern
repl	an unquoted string or a quoted string that follows syntax replacement of regular expression

5.3. Restriction

Nested lists are not supported.

5.4. Notice

5.4.1. Kanji space

Kanji space generates warning.

5.4.2. rit support

If tt text begin with

#!/

then Ptt assumes that there are embedded codes. Then the code area is assumed in the aread

${
code
}$

5.5. Double quotation

The auto-conversion algorithm stands on the following consideration:

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 “ ,.;:!?”.

1. Introduction

1.1. Why Ptt ?

1.2. What is Ptt ?

1.2.1. Headers and phrases

1.2.2. List

1.2.3. Image inclusion

1.2.4. Table

1.2.5. Other abilities

1.2.6. In case we need HTML

2. Installation

3. The Grammar

3.1. General Rule

3.2. HTML attributes

3.3. Headers

3.3.1. Type of headers

3.3.2. title tag of HTML

3.3.3. Table of contents

3.3.4. Options in “H1:”

3.4. Options in body tag

3.5. List

3.5.1. List format

3.5.2. Termination of list

3.5.3. List option “-a”

3.6. Link

3.7. Center tag

3.8. Image

3.8.1. A single image

3.8.2. Image array

3.9. Table

3.10. Programing code

3.11. Note

3.11.1. Short note.

3.11.2. Long note

3.12. Quote

3.12.1. Short quote

3.12.2. Long quote

3.13. Comment

3.13.1. Short comment

3.13.2. Long comment

3.14. Pure HTML mode

3.15. String definition

3.15.1. Short definition.

3.15.2. Long definition

3.15.3. Undefine

4. Label and the References

References

5. Summary

5.1. Terminology

5.2. Tags

5.3. Restriction

5.4. Notice

5.4.1. Kanji space

5.4.2. rit support

5.5. Double quotation

3.3.4. Options in “`H1:`”

3.5.3. List option “`-a`”