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.
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:
First paragraph of first subsubsection.
First paragraph of the other subsubsection.
First paragraph of the other subsection.
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.
[ is a special character which is used to specify labeled list items. Note that [ is a special character only if it is the first character of an indented paragraph.
\ may be used to quote special characters. As usual, the character \ itself is specified by typing \\.
* is another special character which is used to specify ``ticked'' list items. The '*' tick character is generally replaced by a nicer tick symbol such as a bullet or a little square when the document is translated into a real typesetting system such as TeX.
Like [, * is a special character only if it is the first character of an indented paragraph.
Numbered lists:
Item #1.
Item #2.
Item #3.
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.
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:
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:
A | B -------+--------- 10 | 20 30 | 40
Nested figure:
Nested
figure caption.
Nested line:
End of sublist.
Non nested line:
Non nested figure:
No caption.
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.
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:
This is the logo of the Pixware company.
It is possible to specify hypertext links in PTF.
This text, which may be converted to an index entry by systems such as LaTeX, should be at most a few words long.
This text must be defined somewhere else (possibly in another file -- see the documentation of docc) as an hypertext target.
hypertext ``buttons'' are generally rendered using specific presentation attributes so you don't need to add your own font commands.
Example:
If this document is translated to HTML or to non-linear (winhelp) RTF, click on Poor Text Format to jump to the introduction.
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.
These commands are generally generated by programs such as sed or docx (see the docx utility). You'll rarely need to use these commands.
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.
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.
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.
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.
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.
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).
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
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
The hardest format to generate is HTML because in this case you must run docc twice, example:
$ cd tmp $ docc href -o hrefs ptf.txt docc.cc docx.cc $ ls hrefs
$ 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).
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
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))