This is the README file for PerlPoint-Converters

$Id: README,v 1.11 2001/06/16 12:37:08 lorenz Exp $

Covered topics:

o  Introduction
o  About PerlPoint-Converters
o  Prerequisits
o  What's new
o  Installation
o  Test Cases
o  Bug Reports
o  Credits
o  Licence

Introduction
------------
PerlPoint is a simple text format which allows easy typing of text
with headlines, bullet lists, normal text paragraphs, indented
paragraphs for code examples etc., from which slides for presentations
can be generated by a script without the need of proprietary software.
Since there is a large variety of platforms which provide web browsers,
HTML is a good choice for the output format. In principle, however, it
is possible to generate each output format whose specification is
known. At the moment there exist converters for HTML, LaTeX (alpha software)
and SDF. The latter both may be used to generate printable output or to
provide the basis for further processing.


About PerlPoint-Converters
--------------------------
This package provides two programs:
  pp2html
  pp2latex (still alpha software)

They convert an ASCII file written in the `PerlPoint' language to a set
of HTML files or to Latex Files respectively. The `PerlPoint' language
was initially invented by Tom Christiansen as a simple means for
preparing slides. The idea was to just write down your headings and
bullet items and then use a simple perl script to create the slides:

  =Header of first slide

  * Use your favourite editor

  * Start headings with a `='

  * Bullets items start with an asterisk `*'

The syntax of the original version was similar to POD and the layout 
of the slides was hard coded in Tom's pp2html script. The new syntax 
provides more felxibility and can be parsed with the PerlPoint::Parser 
from Jochen Stenzel's PerlPoint-Package.

The following list persents some of the features of pp2html and pp2latex:
  - HTML template files for header, footer and navigation bar
  - Support of Frame Sets
  - Support of the TreeControl Applet in tabel of contents
  - Headers with different levels with or wihout numbering
    (1, 1.1, 1.2, 2, ...)
  - Hyperlinks to internal and external pages
  - Automatic generation of table of contents and navigation links
  - Automatic generation of index
  - Bullet-Lists with standard <LI> bullets or with bullets from a gif/jpeg file
  - Numbered lists and definition lists
  - Simple tables
  - Simple text formatting possible

For more inforamtion about the PerlPoint syntax and history please
refer to the documentation in the PerlPoint-Package from Jochen Stenzel
(perldoc PerlPoint::Parser).


Prerequisits
------------
This version needs Perl5.005.
Note: The fields.pm Module which comes with Perl5.005 is quite old.
You should get the newest version from CPAN because the PerlPoint::Parser
Module needs a newer version!

The pp2html program uses the following packages which are available on CPAN
or come with your Perl distribution:

  Pod::Text
  Getopt::Long
  Getopt::ArgvFile
  PerlPoint::Parser
  PerlPoint::Backend
  PerlPoint::Constants
  PerlPoint::Tags::Basic;
  PerlPoint::Tags::HTML;
  PerlPoint::Tags::LaTeX;
  
The TreeApplet classes are contained in the images subdirectory of this
distribution. For more information about the TreeApplet classes refer to
http://www.naturallyj.com.
This distribution contains an older version which was freely available.


What's new in this version
--------------------------
This is version 0.10
You will need PerlPoint-Packet version 0.34 for this release.

Please refer to file "Changes".

NOTE: This is major release. The handling of directories in \IMAGE tags has changed:
      Now the image filenames must be specified relative to the calling PerlPoint 
      file (or as absolute pathnames). 

      Filenames specified with the --bullet options must now also be relative to
      the start directory (where pp2html is called) or relative to the style
      directory.

      The --style, --style_dir options are new and should simplify the handling of
      templates. You can now build a collection of pre-defined styles which can
      easily be called with the --style option.

NOTE: Documentation is not yet perfect. This will be one of the major issues of the
      next release which will come soon! Please keep tuned.


Installation
------------
Just get the PerlPoint-Converters-<release>.tar.gz file and unpack it in a temp directory:

  tar zxvf PerlPoint-Converters-<release>.tar.gz 
  cd PerlPoint-Converters-<release>
  perl Makefile.PL
  make
  make test
  make install

The main program is `pp2html'. Try `pp2html --help | less' to get more 
information.

The test script `t/test_pp.t', which is invoked via `make test', runs the input 
file `ppdoc.pp' four times through `pp2html' using four different configuration
files.  The resulting HTML files are placed in the `ex_*' subdirectories. These
examples contain documentation for `pp2html'.

Test Cases
----------
The following examples/test cases are provided:
  ex_std_norm/     Standard HTML pages without TreeApplet
  ex_std_tree/     Standard HTML pages with TreeApplet support
  ex_frm_norm/     Frame set without TreeApplet
  ex_frm_tree/     Frame set with TreeApplet support

Issue the `make test' command to create the test samples.
Look at the results by opening the following files in your web browser
(Javascript must be enabled to look at the *tree* examples):

  ex_std_norm/page0000.htm
  ex_std_tree/page0000.htm
  ex_frm_norm/frame_set.html
  ex_frm_tree/frame_set.html


Bug Reports
-----------
Please send bug reports and requests to <lorenz.domke@gmx.de>

Lorenz Domke


Credits
-------
Thanks to Tom Christiansen for the idea and first implementation
of PerlPoint! And special thanks for his permission to use this
name for our new implementation.

Thanks to Jochen Stenzel who tested the first versions of pp2html
and supplied the powerful PerlPoint-Package which is the base of
this new implementation of pp2html.

Thanks to Stephen Riehm who shared his ideas of extensions for
the original software with us. The final language was basically
designed by a team of Jochen, him and me.

Thanks to Alex Sigel and Norbert Gruener who became our first
testers outside the team and helped us by their usage reports.
Special thanks to Alex for propagating the toolkit and his help
to publish the software!


Licence
-------
This module is free software, you can redistribute it and/or modify it
under the terms of the Artistic License distributed with Perl version
5.003 or (at your option) any later version. Please refer to the
Artistic License that came with your Perl distribution for more
details.

The Artistic License should have been included in your distribution of
Perl. It resides in the file named "Artistic" at the top-level of the
Perl source tree (where Perl was downloaded/unpacked - ask your
system administrator if you dont know where this is).  Alternatively,
the current version of the Artistic License distributed with Perl can
be viewed on-line on the World-Wide Web (WWW) from the following URL:
http://www.perl.com/perl/misc/Artistic.html

DISCLAIMER

This software is distributed in the hope that it will be useful, but
is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or
implied, INCLUDING, without limitation, the implied warranties of
MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE.

The ENTIRE RISK as to the quality and performance of the software
IS WITH YOU (the holder of the software).  Should the software prove
defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.

IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE,
MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO
ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even
if they arise from known or unknown flaws in the software).

Please refer to the Artistic License that came with your Perl
distribution for more details.

