Logo address

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

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 thses 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 thses 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://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.

3. The Grammar

3.1. General Rule

The followings are general rules of Ptt.

Experimental rules of Ptt 4.0:

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" ...
or
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:

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.aichi-u.ac.jp/ptt/ for more details.
will be converted to
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
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.jpg iris.jpg portyeraka.jpg
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.jpg iris.jpg portyeraka.jpg
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.

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:

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

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 tab=n
program code
term
where “tab=n” specifies tab size. The default is 8.

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
nameagesex
alice16female
bob20male
nameagesex
alice26female
bob30male
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:

nameagesex
alice16female
bob20male

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

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:
  1. code area and data area are out of conversion
  2. double quotations in tag do not converted
  3. left double quote and right double quote appears in pair
  4. left double quote appears only at the beginning of line or at the right of space
  5. right double quote appears only at the end of line or at the left of character in “ ,.;:!?”.