This document describes a format called PTF (Poor Text Format).

PTF documents are:

PTF is a good format for writing README files and C/C++ comments. With a tool such as docc you can automatically extract these comments from your source files and convert the extracted PTF chunks into an acceptable reference manual.

Send bug reports to mailto:info@pixware.fr.

1 Sections

The title of a section must not be indented at all. The title of a section is typically rendered using a large bold font.

Example:

*This is a subsection

**This is a subsubsection

  First paragraph of first subsubsection.

**This is a another subsubsection

  First paragraph of the other subsubsection.

*This is another subsection

  First paragraph of the other subsection.

is rendered as:

1.1 This is a subsection

1.1.1 This is a subsubsection

First paragraph of first subsubsection.

1.1.2 This is a another subsubsection

First paragraph of the other subsubsection.

1.2 This is another subsection

First paragraph of the other subsection.

2 Paragraphs

Paragraphs must be indented (by an arbitrary amount). The amount of white space between words is not important but at least one open line must be used to specify the end of a paragraph.

Do not forget this open line after all sections, paragraphs or list items otherwise expect very strange results.

When used to determine the indentation of a paragraph, the tab character is counted as 8 white spaces. This means that you'd better set your favorite text editor tab width to 8.

The maximum line width is 255 characters.

3 Lists

Numbered lists:

  1. Decimal numbering.
    1. Upper-alpha numbering. Item #1.
    2. Upper-alpha numbering. Item #2.
    3. Upper-alpha numbering. Item #3.

    Item #1.

    1. Lower-alpha numbering. Item #1.
    2. Lower-alpha numbering. Item #2.
    3. Lower-alpha numbering. Item #3.
  2. Decimal numbering.

    Item #2.

  3. Decimal numbering.
    1. Upper-roman numbering. Item #1.
    2. Upper-roman numbering. Item #2.
    3. Upper-roman numbering. Item #3.
      1. Lower-roman numbering. Item #1.
      2. Lower-roman numbering. Item #2.
      3. Lower-roman numbering. Item #3.

    Item #3.

4 Fonts

It is not possible to nest font commands.

Do not try to specify fonts in section titles, list item labels, etc, because this kind of text is generally associated with specific presentation attributes.

5 Horizontal line

A line which is not indented and which begins with at least 3 '=' (equal) characters is rendered as an horizontal line which is as wide as a page. Past the 3 first '=' characters, the rest of the line is ignored.

Example:


6 Preformatted paragraphs

It is possible to specify that a paragraph is preformatted by placing the text between two lines which are not indented and which begin with at least 3 '-' (minus) characters.

This preformatted paragraph (typically source code) is rendered using a fixed-pitch font.

Example:

int main(int    argc,
         char*  argv[])
{
    puts("Hello MMMarvelous World!!!");
    return 0;
}

Note that borders are drawn around preformatted paragraphs if the sequence '+--' is used instead of sequence '---'.

Preformatted paragraph with borders may not be supported by all output formats.

Preformatted paragraphs are always displayed at current indentation level. Example:

Non nested line:


Non nested figure:

pixware

No caption.

7 Tables

This is a table without a caption:

Cell 1 Cell 2, line 1
line 2
line 3
Unix pipe = ``|'' Cell 4

This is another table:

Display screen
number
1 2
width 1024 1280
height 768 1024
depth 16 24

Long, long, long, long, long, long
table caption.

8 Figures

In order to specify a figure in PTF, a file name without any suffix must be put between [ and ] at column 0, optionally followed by the caption of the figure.

If the file name is something like images/myfig, tools such as docc generally expect to find actual files called:

This command may not be supported by all output formats.

Example:

[pixware] This is the logo of the Pixware company.

is rendered as:

pixware

This is the logo of the Pixware company.

9 Hypertext links

It is possible to specify hypertext links in PTF.

Example:

If this document is translated to HTML or to non-linear (winhelp) RTF, click on Poor Text Format to jump to the introduction.

10 Comments

Text between 2 '~' (tilde) characters and the end of line is ignored.

This is also a very convenient way to make sections stand out very cleary above paragraphs by underlining them using lines of ~'s.

11 More cryptic commands

These commands are generally generated by programs such as sed or docx (see the docx utility). You'll rarely need to use these commands.

\NNN
NNN is a 3-digit octal number between 0 and 255 which represent an 8-bit character belonging to the ISO Latin 1 character set.

Note that if you have a 8-bit text editor, you don't need to use \NNN commands at all because you can directly type any ISO Latin 1 character.

Example:

This paragraph contains ISO Latin 1 characters such as 
the dollar sign \044, the copyright sign \251 or small e 
accute accent \351 which is heavily used <en fran\347ais>.

is rendered as:

This paragraph contains ISO Latin 1 characters such as the dollar sign $, the copyright sign © or small e accute accent é which is heavily used en français.

\<SPACE>
(the '\' character followed by a space) Non breaking space.

Example:

Word\ 1 word\ 2 word\ 3 word\ 4 word\ 5 word\ 6
word\ 7 word\ 8 word\ 9 word\ 10 word\ 11 word\ 12
word\ 13 word\ 14 word\ 15 word\ 16 word\ 17 word\ 18
word\ 19 word\ 20 word\ 21 word\ 22 word\ 23 word\ 24.

is rendered as:

Word 1 word 2 word 3 word 4 word 5 word 6 word 7 word 8 word 9 word 10 word 11 word 12 word 13 word 14 word 15 word 16 word 17 word 18 word 19 word 20 word 21 word 22 word 23 word 24.

This command may not be supported by all output formats.

\<CR>
(the '\' character followed by a carriage return) Line break.

Example:

First line.\                 
Second line.\                 
Third line.                 

is rendered as:

First line.
Second line.
Third line.

This command may not be supported by all output formats.

[]
List break. An indented line which contains only [] may be used to force the end of a list. The indentation of the line specifies which list (or nested lists) is to be ended. This command is especially useful for preformatted paragraphs.

Example:

                 * list 1 item 1

                 * list 1 item 2

                     ** list 2 item a

                     ** list 2 item b

                     ** list 2 item c

                 []

 +--
 Without the [], this paragraph would have been contained 
 inside list 1 item 2.
 +--

is rendered as:

Without the [], this paragraph would have been contained 
inside list 1 item 2.

Note that horizontal lines, figures and page breaks force all nested lists to end.

^L
(a formfeed character at column 0) Page break.

This command may not be supported by all output formats.

Example:

^L
  This paragraph should be located at the top of a new page.

is rendered as:

This paragraph should be located at the top of a new page.