PERL CODE: prolog-to-web translation

(File Last Modified Tues, May 28, 2002.)

• Documentation control
• How it works
• Command line
• File types
• Current types
• Making new file types
• Configuration
• Extensions to standard Pod files
• Two wildly optimistic and untested assumptions
• Bugs
• Author

Documentation control

The system builds a little web site linking source code to demo code to sample output code.

For example, the Absolute Prolog web site was built using this tool.

All the source code must be documented using the Perl Pod format (plain old documentation) described at http://www.perldoc.com/perl5.6/pod/perlpod.html .

A sample of Prolog-in-pod is shown below.

 /*

 =head1 Hook into the Prolog reader

 Hook our code into the Prolog reader as follows */

   term_expansion(X=Y, Out) 
        capsules(X=Y, Out).
   term_expansion((F`X --> Y), Out) :-
      xpandr((F`X --> Y), Out).
   term_expansion((F`X), Out) :-
      xpandr((F`X --> true), Out).  /*

 =head1 capsule(+Handle = +Fields, -Result)

 Uses the bagof trick; */

   capsules(X = Y,Out) :-
        bagof(Z,X^Y^capsule(X=Y,Z),Out).

Note the indentations used above. Any line that does NOT start on column 1 is treated as verbatim text and is converted into pre-formatted typewriter font text.

How it works

For every FNAME.EXT you list (as shown in the options.lib), the following files are generated:

• FNAME.html
• demos/FNAME.html (but only if demos/FNAME.pl exists).
• out/FNAME.html (but only if out/FNAME.out exists).

Also, a toc.html is generated linking together in one place FNAME.html, demos/FNAME.html, out/FNAME.html and out/FNAME.EXT.

Command line

To make it work for you:

• Steal the entire directory tree making up this system (ask tim@menzies.com for copy).
• Write a file in pod format, e.g. xx.pl. Place xx.pl in the root of the stolen directory tree.
• Optionally, if you have sample input and output from the code in xx.pl, place the inputs into demos/xx.pl and the outputs into out/xx.out.
• Edit options.lib and add in a reference to your new file (for details of the format of that file, see Configuration, below ).
• Call the system as follows:

   cd /place/where/your/source/code/is
   perl absolute.pl

  By default, the system only updates the html files that have newer source files. To force a total update:

   perl absolute.pl -all

• Now your xx.pl file should be prettied up (as xx.html) and the table of contents will offer links to xx.html plus, if the exist, demo/xxx.pl and out/xxx.out.

File types

The files here are divided up into their categories. Each category gets its own color.

Current types

As of build 1752, the current types are:

``1''

Library files contain lots of stand-alone predicates. Library files can be understood by glancing at small parts of them. Prolog novices might want to start with library files.

``10''

Utilities files containing lots of interacting predicates. Utility files can't be understood without working through most of the file. The icon for utility files is stop watch that takes a few minutes to run. After studying the library files, Prolog novices might want to move to the utilities files.

``100''

Systems files co-ordinate processing amongst lots of interacting files. System files can't be understood without working through many files. Prolog novices might want to study systems files last. Alternatively, since all the files here were reverse-engineered in an effort to explain these systems, the brave novice might want to read the systems files first.

``text''

Text files discuss some general issue or some general theory.

``pro''

Prolog files discuss some Prolog issue or some Prolog theory.

``silly''

Silly files discuss truly silly stuff and should be ignored by sensible people.

``admin''

Admin files describe some feature of Absolute Prolog.

Making new file types

The number of categories is up to you. Defining a new category is a little tedious (must fix this one day) but the process is:

1. Pick a short name for your new type; e.g. NEWT.
2. Pick a distinctive color for your new type; e.g. orange.
3. Create a new style file for files of this type. Inside the file NEWT.css, include (e.g.)

    H1 {background: orange}

4. Add to the list of styles defined for the right-hand-side table of contents. Inside the file types.css add the line (e.g.):

    .NEWT {background: orange}

5. In the file options.lib, edit the definition of %type to include a text description of the new type; e.g.

    "NEWT"   => "Stuff about my holidays"

6. Edit header0.txt and add in a hyper text entry to the index file for this new type _NEWT.html; e.g.

    <span class=NEWT><a href="_NEWT.html">My holiday diaries</a></span><br>

The new type is now define. To classify files as belonging to this new group:

• In the file options.lib, edit the definition of the demos sub-routine and tag some files with your new type; e.g.

    page qw(holiday     pl    NEWT     tm My holiday diary);

• Recompile the whole site using

   perl absolute.pl -all

Configuration

Certain magic files can be changed to alter the contents, and some details of the look and feel.

• options.lib: defines what files are included as well as certain magic strings. Read the configuration notes in that file to change the file definitions and magic strings.
• copyright.html: copyright notices.
• footer0.txt: html stuff to go at bottom of table of contents
• header0.txt: html stuff to go at bottom of table of contents
• hello.html: splash screen, used as the main page.
• index.html: contains the title of the whole site, and the frame size definitions.
• options.lib: discussed above.
• style.css: style sheet for the main viewing pane.
• toc.css: Style sheet for the table of contents.
• demos/demos.css: Style sheet for the demo input files
• out/out.css: Style sheet for the output files.

Extensions to standard Pod files

Absolute.pl makes a few changes to the standard Pod syntax:

R{X}

Gets translated to a link to i.e. it is used to Link into a reference library; R{X } becomes a hyperlink to refs.html#X;

L{page}

Inserts a hyper link to page in the current directory. The text of the link is page.

L{page:text}

Inserts a hyper link to page.html in the current directory. The text of the link is text.

LL{folder/page.html#sec:text}

Inserts a hyper link to folder/page.html#sec in the current directory. The text of the link is text.

Two wildly optimistic and untested assumptions

1. All the code for generating the cite is written in (hopefully) portable Perl so it should work on most platforms.
2. While the examples at this site are all Prolog-based, the system could be used for non-Prolog systems.

Bugs

If the pod file is not in UNIX text format, pod2html will generate an empty file. Strangely, this is NOT true of the other pod tools (e.g. pod2latex, pod2man). Anyway, to fix this problem under Windows, use an editor that can save in Unix format like Note Tab-Lite: http://www.notetab.com/download.htm .

Author

Tim Menzies (tim@menzies.com )