address Logo

Ptt ( ver.3.1/3.2 )

Contents

valid-html401

Ptt generates HTML text that is
“Valid HTML 4.01 Transitional”
of W3C from tt formatted text.

2007/09/23 (ver.3.0)
2007/10/02 (ver.3.1)

Introduction

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.

What is Ptt ?

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

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.

Image inclusion

Image file can be included using syntax: 

	I: cat.jpg

which will result in

cat

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.

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.

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.

Installation

You need ptt and style.css.
You will find them at http://plan9.aichi-u.ac.jp/netlib/cmd/ptt/.
You will find 

#!/bin/env python

at the first line of the downloaded Ptt, where “/bin/env” is my program that has not been released yet. Please change to others:

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.

The Grammar

General Rule

The followings are general rules of Ptt.

Experimental rules of Ptt 3.2:

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

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.

Headers

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.

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.

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

Options in “H1:”

Header “H1:” has some options:

H1: [-lteq] title

where characters inside of [ ] are options:

Style sheet

If style sheet is not specified, style sheet named “style.css” in the document root of HTTP will be used.

Document specific style sheet is given by “S:” or “SS:”. They must be located before “H1:”.

External style sheet

The format is

S: url

where url is used for the value of “src” attribute, and may be anything that are allowed for the value.

Inline style

SS: term

style

...

term

where term is a terminating string and styles are style statements.

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.

List

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.

Termination of list

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

List option “-a” and “+a”.

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

UL:-a
- url1 description1
- url2 description2
-

Here these usrls 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. If you want to show the urls, use “+a”.

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

Options “-a” and “+a” in list are handy. We can use similar systax out of list.

-a: path description

or

+a: path description

In case “-a”, the “path” will be hidden, on the other hand in case “+a”, the “path” will be shown.

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

Image

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

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.

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
irise irise.jpg
portyeraka portyeraka.jpg
!

will produce

lily.jpg irise.jpg portyeraka.jpg
lily irise 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%"
irise irise.jpg  width="40%"
portyeraka portyeraka.jpg width="20%"
!
lily.jpg irise.jpg portyeraka.jpg
lily irise portyeraka

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

Horizontal ruler

Horizontal ruler is given by

HR: options

where options is a attribute/value list of “<hr>” tag.

Note that color attribute is not supported in HTML 4.0.

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 defintion”.)

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. Table class “noborder” is predefined. If we replace the third line 

	Ta: | width="40%" align="center"

to 

	Ta: | class="noborder" width="40%" align="center"

or simply 

	Ta: | noborder width="40%" align="center"

then we will have

format meaning
<width left align
width center align
>width right align
- hidden

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

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.

Note

We have two types of “note”.

Short note.

Short note means single line note. The syntax is

N: note

Long note

Syntax of long note is

NN: term
note
note
...
term

where “term” is a terminator string.

Quote

We have two types of “quote”.

Short quote

Short quote means single line quote. The syntax is

Q: quote

Long quote

Syntax of long quote is

QQ: term
quote
quote
...
term

where “term” is a terminator string.

Comment

Comment area of tt text is not converted to HTML.

Short comment

Short comment is a single line comment. The syntax is

#: comment

Long comment

Syntax of long comment is

##: term
comment
comment
...
term

where “term” is a terminator string.

Pure HTML mode

Pure HTML mode is uncooked mode. The syntax is

!: term
...
...
term

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

String definition

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>

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: noframe
name age sex
alice 16 female
bob   20 male

!

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

!

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

Undefine

D: from

will clear the definition.

Replacement using regular expression

Ptt has facility to replace strings using regular expression. The syntax is

RD: patt repl

Here we may use single quotation or double quotation.

For cleaning the definition, we have

RD: patt

Regular expression is powerful but difficult to understand for beginners. You need knowledge of regular expression.

Reference index

Bibliography and the citation

Ptt supports LaTeX style cross reference. The following is the simple example: 

Plan 9<cite{Plan9}> is deveploped ...
...
H2: References
<bib{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 reference list is

<bib{key}>reference

Numbers are automatically given by ptt.

In the body of text, we embed “<cite{key}>” as above example.

You can look an live example: http://plan9.aichi-u.ac.jp/rit/rit-1.4.html
The tt file is: http://plan9.aichi-u.ac.jp/rit/rit-1.4.tt
This case is much complicated because the HTML file is automatically converted to LaTeX file using “html2tex”.

Label and the reference

This is a new feature of Ptt 3.2. We can put labels to “H2:”, “H3:” and “H4:” and the section can be referenced elsewhere. Two types of syntax are provided.

For example: 

.... Look "<a href="#ref{SD}">String definition</a>" ...
...
H3: String definition
<lab{SD}>
...

As this example shows, “<lab{key}>” should be placed after the header tag.

Summary

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

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
BO: body option BO: options
S: style sheet S: url
SS: inline style sheet SS: term
lines
term
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
…
-
-a: add a link to the url,
the url is hidden 		-a: url line
+a: add a link to the url,
the url is shown		 +a: url line
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
HR: horizontal ruler HR: [options]
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
RD: substitution on regular expression RD: patt repl
!: 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

Restriction

Notice

Kanji space

Kanji space generates warning.

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

}$

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