// vim: set filetype=pp2html :
// Comment: ppdoc.pp: documentation and testfile for pp2html
//
// $Id: ppdoc.pp,v 1.12 2001/08/16 04:06:46 lorenz Exp $
// $Revision: 1.12 $
// $Date: 2001/08/16 04:06:46 $
// Some variabels:
$pp2html=pp2html
$pp2latex=pp2latex
$AUTHOR=L. Domke
+BLACK:\F{color=black}<__body__>
=Introduction
This file \C is a short introduction to \C
and serves also as a \X for
\C and \C.
All features which have been implemented so far are presented in the
following. It is recommended to compare this file with the results
from \C and \C.
==Features of pp2html
The most important \X of \C are:
* Simple ASCII file in PerlPoint format as source
* Automated generation of table of contents and navigation
* Optional index generation
* Possibility for simple character formatting
* Optional frame sets
* Support for TreeApplet in table of contents
==Usage
To convert this file into \I or \I and \I type the
following commands:
< ppdoc.tex
% latex ppdoc.tex
% makeindex ppdoc.idx
% latex ppdoc.tex
% dvips -o ppdoc.ps ppdoc.dvi
% ghostview ppdoc.ps
EOC
The first command creates all HTML slides. Naming conventions are set up via
options in the \C configuration file.
The commands starting with \C create a LaTeX file and from this a
Postscript file. Note that the \C command is called twice. This is necessary
in order to update all internal links and cross references before the final
document is created.
=Headers
Headers are introduced by \X (=) at the beginning of a line.
The number of equal signs determines the level of the header: \X{mode=index_only}
=A Header of Level One
==Second Level Header
===Third Level Header
Each \X \B be followed by a blank line.
Here come some tests for index entries with German characters:
Index entries which start with a German \I like \X<Übertrag>
or \X<ärgerlich> should be sorted to the corresponding non-umlaut characters
within the index.
It should also be possible to have multiple index entries with the same
name in different places. Here is another entry \X ...
=Paragraphs
The following paragraph types are used by \C:
* Normal text paragraphs
* Block paragraphs
* Verbatim block (here documents)
* List paragraphs
* Shift paragraphs
* Table paragraphs
* Macro paragraphs (PerlPoint::Parser 0.21)
For a detailed description refer to the
documentation of the PerlPoint format.
PerlPoint::Parser, PerlPoint::Backend
$AUTHOR=J. Stenzel
\INCLUDE{type=PP file="doc/parser-paragraphs.pp"}
=Tags
$AUTHOR=L. Domke
There are three kinds of tags:
* General tags provided by PerlPoint::Parser
* Special purpose tags provided by PerlPoint::Parser
* Backend tags defined by \C
$AUTHOR=J. Stenzel
\INCLUDE{type=PP file="doc/parser-tags.pp" headlinebase=1}
==Backend Tags
$AUTHOR=L. Domke
The following list shows all tags which are provided by \C in addition
to the tags which are provided by the \C (like \\INCLUDE):
* BOXCOLORS
* IMAGE
* PAGEREF
* SECTIONREF
* XREF
* A
* B
* C
* I
* U
* L
* U
* SUB
* SUP
* E
* F
* X
* LINE_BREAK
* BR
* HR
=Formatting
\C supports some simple \X as well as line breaks.
Special characters for HTML and LaTeX are escaped automatically. The following
characters should be printed correctly by \C and \C:
Special: \C<\X<\>>>, \C<\<, &, ~, $, %, ^, _, {, }>
(greater than, less than, ampersand, tilde, dollar sign, percent sing, carret, underscore, curly braces)
==Character Formatting
\C supports the following character formattings:
* Bold
* Italic
* Code
* Understroke
* Subscript and Superscript
The \\B\< ... \> tag prints text in \B
The \\I\< ... \> tag prints text in \I
The \\C\< ... \> tag prints text in \C
The \\U\< ... \> tag prints text with \U
The \\SUP\< ... \> tag creates \SUP
The \\SUB\< ... \> tag creates \SUB
==Color Tag
There is a \F{size="+2" color="#CC0000"}
tag \\F\{color=value size=value face=value\}\< .... text ...\>
which allows to change color and size and face of the text.
==Line Feeds
It is possible to force a \X by using the tag \\LINE_BREAK or \\BR.
Here an example:
<. You will see examples for
* Lists
* Tables
* Blocks
* Images
==Lists
First of all a bullet list: \A{name=bullets}
* Start each bullet item with an asterisk (*) at the beginning of a line.
* Each bullet must be followed by a blank line.
* Very long bullet items can be written
on several consecutive lines. Note: the following lines
may or may not start with a blank but after each item there must be a
blank line!
* The list is closed when another paragraph type or list type follows.
The above bullet list has been created by the following lines:
* Start each bullet item with an asterisk (*) at the beginning of a line.
* Each bullet must be followed by a blank line.
* Very long bullet items can be written
on several consecutive lines. Note: the following lines
may or may not start with a blank but after each item there must be a
blank line!
* The list is closed when another paragraph type or list type follows.
Ordered lists are numbered \X:
# List items start with a hash sign (#) in column one.
# Each item must be finished by a blank line.
This ordered list has been created by:
# List items start with a hash sign (#) in column one.
# Each item must be finished by a blank line.
And now an example for a definition list:
:\B: this is a variable
:\I:
this is a constant
The defining lines are:
:\\B: this is a variable
:\\I:
this is a constant
==Shift Paragraphs
There are special \I which start with a \> or < sign.
These paragraphs are special in that they do not contain a text body. They are
only used to increase or decrease the level of nesting for list items.
\B
* This is a list item in a level 0 list
* This is item two of the top level list
>
* this is item 1 of a sub-list
* the sub-list has been started by a > shift paragraph
>
* another item, one level below
<2
* now we are again on level 0
* last list item
got it?
\B:
* item 1, level 0
>
* item on level 1
<
* back on level 0
==Block Handling
\I are pieces of text that should be layouted as pre-formatted text.
Line breaks and indentation should not be modified.
Blocks are typically used for showing examples and pieces of code. \C
places block text in a box with colored background. The foreground and background color can be
selected via the \C<--boxtext_color=color> and \C<--box_color=color> options or by using
the \\BOXCOLORS{fg=fgcolor bg=bgcolor} tag.
Now follows a \I block. Note that the box color has been switched to green:
\BOXCOLORS{bg=green}
This is a verbatim \B
with tag - recognition; the text "block" should be printed \I.
The effect can only be seen, however, when the \C<--boxtext_bold> option has been set to \C.
\BOXCOLORS{bg=white fg=blue}
< and the \B<> tag should not
be interpreted in a special meaning but printed as they
have been typed. This should also be true for the ampersand (&)
EOT
\BOXCOLORS{bg=blue fg=white}
==Tables
A table paragraph is started with a \B<@> sign followed by a character which is to be
used as column separator.
@,
Operating system , Supported
Sun OS , yes
Linux , yes
NT , no
The above table was produced by
< tag which allows to set different parameters like
\I or \I. The following tables are created with this tag:
\TABLE{separator=";" bgcolor=yellow head_bgcolor="silver"}
pro ; contra
\BLACK ; \BLACK
\BLACK ; \BLACK<->
\END_TABLE
\TABLE{separator=";" border=4}
pro ; contra
more flexibiliy ; more "line noise"
colored heading ; -
\END_TABLE
==Images
It is possible to insert GIF, JPEG or PNG images into the text:
\IMAGE{src="./images/karawane-50.gif" height=50 width=150 alt="The camel is your friend" align=right}
The syntax is:
\\IMAGE{src="./images/karawane-50.gif" alt="The camel is your friend"
height=50 width=200 align=right}
=Internal Links and References
In order to \X