Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PerlPoint::Converters(User Contributed Perl DocumentatPerlPoint::Converters(3)

NAME
       PerlPoint::Converters - README and common functions for PerlPoint
       converters

README
       Covered topics:

       o   Introduction

       o   About PerlPoint-Converters

       o   Prerequisits

       o   What's new

       o   Installation

       o   Documentation

       o   Test	Cases

       o   Bug Reports and Support

       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	information about the PerlPoint	syntax and history please
       refer to	the documentation in the PerlPoint-Package from	Jochen Stenzel
       (perldoc	PerlPoint::Parser) and to the provided documentation in	the
       ./doc/PPDOC subdirectory	(after a successful "make" in ./doc :-)

   Prerequisits
       This version needs Perl5.005.

       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;	 (part of PerlPoint-Converters)
	 PerlPoint::Tags::LaTeX; (part of PerlPoint-Converters)

       The TreeApplet classes are contained in the pp2html_stypes 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 1.00.  You will need PerlPoint-Packet version 0.36 for
       this release.

       Please refer to file "Changes".

       NOTE:
	   Documentation is not	yet perfect, but hopefully better than before.
	   Please try a	"make" in ./doc	and look at the	documents which	should
	   have	been created in	./doc/PPDOC

   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

	 % cd ./doc
	 % make

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

   Documentation
       "pp2hml"	and "pp2latex" have a --help option which displays Usage
       information and some documentation about	the PerlPoint Language.	For a
       more detailed description please	refer to the POD documentation of the
       following Modules:

	PerlPoint::Parser
	PerlPoint::Anchors
	PerlPoint::Backend
	PerlPoint::Constants
	PerlPoint::Tags
	PerlPoint::Tags::Basic
	PerlPoint::Tags::CPPP
	PerlPoint::Tags::HTML
	PerlPoint::Tags::LaTeX
	PerlPoint::Tags::SDF

       Have also a look	into the ./doc directory of your PerlPoint::Converters
       installation directory. There is	a Makefile which produces the
       following PerlPoint documents:

       o   Getting_Started

       o   FAQ-pp2html

       o   FAQ-parser

       o   Writing-Converters

   Test	Cases
       The examples test cases from the	previous releases (ex_std_norm,
       ex_std_tree, ex_frm_norm	and ex_frm_tree) have now been replaced	with
       the documentation in the	./doc subdirectory.

   Bug Reports and Support
       Please send bug reports and requests to <lorenz.domke@gmx.de> There is
       also a mailing list for PerlPoint:

	 perlpoint@perl.org

       To join the mailing list, send a	message	to
       "perlpoint-subscribe@perl.org"

   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.

SYNOPSIS
	use PerlPoint::Converters qw(
				      replace_keywords
				      update_file
				      copy_file
				    );

	copy_file($from, $to);

	update_file($from, $to);

	$line =	replace_keywords($line,	$KEY_HASH_REF);

DESCRIPTION
       This module contains some common	functions which	are useful for most
       PerlPoint converters.

SUBROUTINES
   replace_keywords($line, $KEY_HASH_REF);
       Replace all occurences of certain keywords in $line with	the values
       specified in the	referenced hash.  The keys in the hash must be lower
       case keywords.

       Example:

	%OPT = (
	   title	=> "PerlPoint Examples",
	   bot_left_txt	=> "Copyright A. User",
	);

	open(TPL, "a_template_file");
	while(<TPL>){
	  print	replace_keywords($_, \%OPT);
	}

       This will replace "TITLE" with "PerlPoint Examples" and "BOT_LEFT_TXT"
       with "Copyright A. User".

       The supported keywords are:

	 TXT_CONTENTS
	 TXT_INDEX
	 PAGE_CNT
	 TITLE
	 BASE_LEFT_TXT
	 BASE_RIGHT_TXT
	 BASE_MIDDLE_TXT
	 BOT_LEFT_TXT
	 BOT_RIGHT_TXT
	 BOT_MIDDLE_TXT
	 TOP_LEFT_TXT
	 TOP_RIGHT_TXT
	 TOP_MIDDLE_TXT

	 BGCOLOR
	 FGCOLOR
	 BOT_BGCOLOR
	 TOP_BGCOLOR
	 IDX_BGCOLOR
	 TOC_BGCOLOR
	 BOT_FGCOLOR
	 TOP_FGCOLOR
	 IDX_FGCOLOR
	 TOC_FGCOLOR
	 LINKCOLOR
	 TOP_LINKCOLOR
	 BOT_LINKCOLOR
	 TOC_LINKCOLOR
	 IDX_LINKCOLOR
	 ALINKCOLOR
	 TOP_ALINKCOLOR
	 BOT_ALINKCOLOR
	 TOC_ALINKCOLOR
	 IDX_ALINKCOLOR
	 VLINKCOLOR
	 TOP_VLINKCOLOR
	 BOT_VLINKCOLOR
	 TOC_VLINKCOLOR
	 IDX_VLINKCOLOR

	 LABEL_NEXT
	 LABEL_PREV
	 LABEL_INDEX
	 LABEL_CONTENTS

	 SLIDE_PREFIX
	 SLIDE_SUFFIX

	 LOGO_IMAGE_FILENAME
	 IMAGE_REF
	 META_TAGS

   copy_file($from, $to, $verbose, $KEY_HASH_REF);
       Copy file $from to file $to. For	binary files (!	-T) the	File::Copy
       method will be used. Text files are copied by reading from $from	and
       printing	to $to.	All lines are treated with the "replace_keywords"
       method.

       Prints a	message	to STDERR if $verbose is set to	1.

   update_file($from, $to, $verbose, $KEY_HASH_REF, $moveFlag);
       Update file $from to file $to if	necessary. For binary files (! -T) the
       File::Copy method will be used. Files are only copied if	the
       modification date of $to	is older than the modification date of $from.

       Text files are always copied by reading from $from and printing to $to
       because keywords	might have changed. All	lines are treated with the
       "replace_keywords" method.

       Prints a	message	to STDERR if $verbose is set to	1.

       The source file is removed if the $moveFlag was set to a	true value,
       which means that	the function performs a	move instead of	a copy.

   $abs_path = return_abs_path($pathname)
       Given a relative	or absolute pathname: return absolute pathname
       $pathname must exist and	either be absolute or relative to current
       working directory.

   is_abs_path($pathname)
       Return 1	if $pathname is	an absolute pathname, i. e. it starts with a
       slash "/" or with a character, followed by a colon and and a slash or
       backslash: "C:/bla bla" or "T:\foo\bar".	Otherwise return 0.

   $rel_path = relative_path($path1, $path2)
       Return relative path from $path1	to $path2.

	   path		  C:/this/is/my/test/foo
	   path2	  C:/this/is/my/test/images/new
	   ==> rel_path	  ../images/new

AUTHOR
       Lorenz Domke <lorenz.domke@gmx.de>

perl v5.32.1			  2006-02-08	      PerlPoint::Converters(3)

NAME | README | SYNOPSIS | DESCRIPTION | SUBROUTINES | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PerlPoint::Converters&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help