Table des Matières

Sections
This is a subsection
This is a subsubsection
This is a another subsubsection
This is another subsection
Paragraphs
Lists
Fonts
Horizontal line
Preformatted paragraphs
Tables
Figures
Hypertext links
Comments
More cryptic commands
The docc utility
Examples
LaTeX
troff -man
HTML
RTF
The docx utility
Index

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.

SectionsTable des Matières

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:

This is a subsectionTable des Matières

This is a subsubsectionTable des Matières

First paragraph of first subsubsection.

This is a another subsubsectionTable des Matières

First paragraph of the other subsubsection.

This is another subsectionTable des Matières

First paragraph of the other subsection.

ParagraphsTable des Matières

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.

ListsTable des Matières

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.

FontsTable des Matières

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.

Horizontal lineTable des Matières

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:


Preformatted paragraphsTable des Matières

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.

TablesTable des Matières

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.

FiguresTable des Matières

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.

Hypertext linksTable des Matières

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.

CommentsTable des Matières

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.

More cryptic commandsTable des Matières

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.

The docc utilityTable des Matières

See also the docx utility.

docc is auto-documented. Simply type docc to list its generic options:

$ docc
usage: docc target_format [generic_options] [format_options] {input_file}+

target_format: latex, man, html, rtf or href (pseudo-format)

Note that PTF comments are automatically extracted from C/C++ source files
using docx if the extension of the input file name is .[hH]* or .[cC]*. Tcl
source files are supported too if the extension of the input file name is .tcl
or .TCL.

generic_options:
-c 
Each input file is individually translated to a stand-alone
documentation file (like 'cc -c').
Default: all input files are translated to a single output file.
-o <%255s>
Specify the name of the output file (like 'cc -o').
Default: the basename of the input file+a format specific suffix.
-href (-h) <%255s>
Specify the name of the hypertext references file to be loaded
(generated during a first pass using the 'href' pseudo-format).
Default: none.
-sed (-s) <%255s>
Specify the name of a file which contains sed commands. These
sed commands are applied to all PTF source files (even if
automatically extracted using docx) just before their translation
to the target format.
Default: none.
-borders (-b) 
Tell docx to add borders around extracted code.
Default: no borders.

Type 'docc target_format' to list the options related to
target_format.

Then, for example, type docc rtf to list the options related to the RTF format:

$ docc rtf
-linear (-li) 
The output RTF file does not contain hypertext links a la WinHelp.
Default: non linear (WinHelp).
-adobefonts (-af) 
Use Adobe fonts (Helvetica, Times, etc).
Default: Windows fonts (Arial, Time New Roman, etc).

ExamplesTable des Matières

LaTeXTable des Matières

PTF comments are directly extracted from C/C++ sources files.

$ cd tmp
$ docc latex -dc article -dco a4paper \
-ti 'The PTF Format and Related Utilties' \
-o ptf.tex ptf.txt docc.cc docx.cc
$ ls
ptf.tex

troff -manTable des Matières

docc is run on docc.cc and then on docx.cc to generate two man pages with different headers.

$ cd tmp
$ docc man -c -ti docc -se 1 -he 'Text Utilities' -fo Pixware docc.cc
$ docc man -c -ti docx -se 1 -he 'Text Utilities' -fo Pixware docx.cc
$ ls
docc.man        docx.man

HTMLTable des Matières

The hardest format to generate is HTML because in this case you must run docc twice, example:

First pass
Resolve all hypertext links and save them in a file called hrefs. To do this, you need to use the href pseudo-format.
$ cd tmp
$ docc href -o hrefs ptf.txt docc.cc docx.cc
$ ls
hrefs
Second pass
For each input file, generate an HTML file (the -c option). Load file hrefs (the -h hrefs option) to be able to resolve hypertext links.
$ docc html -br -h hrefs -c ptf.txt docc.cc docx.cc
$ ls
docc.html        hrefs           previous.gif
docx.html        next.gif        ptf.html

The -br option is used to chain the generated HTML files not only through hypertext links but also sequentially (i.e. like the pages of a book).

RTFTable des Matières

Always use -o when generating non-linear RTF format (WinHelp) to get a single .rtf file and a single .hpj (help project) file.

$ cd tmp
$ docc rtf -o docc.rtf ptf.txt docc.cc docx.cc
$ ls
docc.hpj        docc.rtf

Unlike the HTML format, the generation of WinHelp files does not require running docc twice. The hypertext links are resolved by the help compiler (example hc31.exe) that you must run under DOS on the generated .hpj file.

C> hc31 docc

The docx utilityTable des Matières

docx is a simple preprocessor used by docc to extract comments written in PTF (Poor Text Format) and associated C/C++ code from source files.

docx has no command line options:

docx [-l c|tcl] [-b] [input_file [output_file]]

When input_file and output_file are not specified, docx reads its standard input and writes its standard output.

The -l option may be used to specify the programming language. Currently only Tcl and C/C++ are supported. C/C++ is the default language.

The -b option may be used to add a border around the extracted code.

Comments which are to be extracted must be marked by adding an x just after the beginning of comments character sequence.

Example 1, C style comments:

/*x
Title
    paragraph paragraph paragraph paragraph paragraph 
    paragraph paragraph paragraph paragraph paragraph 
                .
                .
                .

Example 2, C++ style comments:

//x
//Title
//    paragraph paragraph paragraph paragraph paragraph 
//    paragraph paragraph paragraph paragraph paragraph 
                .
                .
                .

Example 3, Tcl style comments:

#x
#Title
#    paragraph paragraph paragraph paragraph paragraph 
#    paragraph paragraph paragraph paragraph paragraph 
                .
                .
                .

All characters between /*x or //x and the end of the line are ignored (except, of course, the end of comments character sequence for C style comments).

Associated C/C++ code (if any) must immediately follow the PTF comments. An open line, EOF, or other comments must be used to end this associated code. Example:

//x
//    Returns the maximum of <x> and <y>.
#define MAX(x, y) \
    (((x) > (y))? (x) : (y))

Associated code is unindented before (by default) being inserted as a verbatim section at the beginning of the PTF comments.

The place where associated code is to be inserted may be specified by putting a line which begins with the '~' '~' 'x' sequence inside PTF comments. Example:

//x
//    Returns the maximum of <x> and <y>.
//
//~~x
//
//    Note that <x> and <y> may be any type for which the '>' operator
//    is defined.
#define MAX(x, y) (((x) > (y))? (x) : (y))

Index

A
Ai j
D
docc
docx
P
Poor Text Format
U
Unix
Utilities