root/tags/lgt2210/xml/NOTES

=================================================================
Logtalk - Object oriented extension to Prolog
Release 2.21.0

Copyright (c) 1998-2004 Paulo Moura.  All Rights Reserved.
=================================================================


This folder contains supporting files for converting XML documentation 
files (which are created when compiling objects, categories, or protocols) 
to PDF files or (X)HTML files using XSL style sheets. The documentation 
files may also be viewed directly in a web browser that supports the W3C 
standards XML, XSLT, CSS, and HTML 4 or XHTML 1.0.

The scripts provided in this folder are just samples, which you should adapt 
to your working environment. Some scripts expect that all files be in the 
same directory. Some others should be called from the directory containing 
the XML documenting files that you wish to convert. See the description of 
each script below for details. Make sure that the XSL processors you intend 
to use are properly installed before running the scripts.

Regarding conversion to HTML/XHTML, the links to the .xsl files on the 
.xml files and the links to the .css files in the generated .html files 
assume that all files reside in the same directory.

The choice of the default .xsl file to use is made in the config files by 
the '$lgt_default_flag'/2 predicate. You may also choose a different 
.xsl file by using the xsl/1 compiler option in the logtalk_compile/2 or 
logtalk_load/2 calls. The default file is lgtxml.xsl (described below).

The documenting files can be either generated as standalone XML files or 
contain a reference to either the Logtalk DTD file, logtalk.dtd, or to 
the Logtalk XML Schema file, logtalk.xsd. The reference to the XML 
specification file can be either a local reference or a URI reference. By 
default, all .xml documenting files contain a local reference but that 
can be changed either in the config files, by setting a Logtalk compiler 
flag, or by using the doctype/1 compiler option. Choose the option value 
that works best with your XSLT tools. To choose between the .dtd or .xsd 
specifications use the xmlspec/1 compiler option.


Brief description of each file in this folder:
 

lgtxml.xsl

    XSLT file for viewing .xml files directly in in a browser such as Mozilla 
    (version 0.9.2 or later) or Microsoft Internet Explorer 5.5 for Windows 
    (after installing the latest Microsoft XML Parser Release that is needed 
    for XSL standard compliance). The links in the (internally generated) 
    HTML files point to related XML files. UTF-8 encoding is assumed. Edit 
    the file if you use a different encoding.


lgthtml.xsl

    XSLT file to output HTML files from the .xml files. The links in the
    generated HTML files point to related HTML files. It can be used to 
    batch convert XML files to HTML files. UTF-8 encoding is assumed. Edit 
    the file if you use a different encoding.


lgtxhtml.xsl

    XSLT file to output XHTML 1.0 files from the .xml files. The links in 
    the generated XHTML files point to related XHTML files. It can be used 
    to batch convert XML files to XHTML files. UTF-8 encoding is assumed. 
    Edit the file if you use a different encoding.


lgtpdfa4.xsl
lgtpdfus.xsl

    XSLT files to generate PDF files from the XML files (formatted either 
    for A4 paper or US Letter paper) using XSL Formatting Objects. Tested 
    with the XSL-FO processors Apache FOP 0.20.5 (http://xml.apache.org/fop), 
    PassiveTeX 1.21 (http://www.tei-c.org.uk/Software/passivetex/), and 
    RenderX 3.7.8 (http://www.renderx.com/).


ie50.xsl

    XSLT file for viewing .xml files in Microsoft Internet Explorer 5.x 
    (using the outdated Microsoft XML Parser; works with both Macintosh 
    and Windows versions). The links in the (internally generated) HTML 
    files point to related XML files. It can be used to browse and view 
    the XML files directly.


logtalk.dtd

    Document type description describing the structure of the .xml files
    generated by Logtalk.
    

logtalk.xsd

    XML Schema describing the structure of the .xml files generated by 
    Logtalk.


logtalk.css

    Cascade style sheet file to render the HTML/XHTML output of the .xsl 
    files in a web browser.


lgt2pdf.sh
    (bash shell script)
lgt2pdf.js
    (JScript command-line script for Windows; requires WSH 5.6 or later version)

    Sample scripts to batch convert .xml files to .pdf files

    Supported XSL-FO processors:
        * Apache FOP processor (tested with version 0.20.5)
            http://xml.apache.org/fop 
        * RenderX XEP processor (tested with version 3.8.1)
            http://www.renderx.com/  

    When using the FOP, compile your Logtalk source files using the compiler 
    option doctype(standalone) in order to workaround a bug on the XALAN 
    processor used by this processor.

    These script assumes that the LOGTALKHOME environment variable is defined
    and that the chosen XSL-FO processor is available in the path.
    The scripts should be called from the directory containing the .xml files 
    you wish to convert. Call the scripts with the help option for a description 
    of the available optional parameters (type "cscript lgt2pdf.js help" or 
    "lgt2pdf.sh -h").


lgt2html.sh
    (bash shell script)
lgt2html.js
    (JScript command-line script for Windows; requires WSH 5.6 or later version)

    Sample scripts to batch convert .xml files to .html files. These scripts 
    also generate an index.html file which contains links to all the converted 
    files.
    
    Supported XSLT processors:
        * libxslt (tested with version 1.1.8)
            http://xmlsoft.org/XSLT/
        * Xalan (tested with version 1.7.0)
            http://xml.apache.org/xalan-c/index.html
        * Sablotron (tested with version 1.0.1)
            http://www.gingerall.com/charlie/ga/xml/p_sab.xml
        * Microsoft MSXSL (only for the JScript script)
            http://msdn.microsoft.com/library/en-us/dnxml/html/msxsl.asp

    These scripts assumes that the LOGTALKHOME environment variable is defined 
    and that the chosen XSLT processor is available in the path.

    The scripts should be called from the directory containing the .xml files 
    you wish to convert. Call the scripts with the help option for a description 
    of the available optional parameters (type "cscript lgt2pdf.js help" or 
    "lgt2pdf.sh -h").


html.sh
xhtml.sh

    Sample Unix shell scripts to batch convert .xml files to .html files. These 
    scripts also generates an index.html file which contains links to all the 
    converted files. The title of the index.html file can be given as a parameter 
    to the script. Edit the scripts to match your environment before running them. 
    Requires James Clark XT XSLT processor 20020426a or later version 
    (http://www.jclark.com/xml/). You will need either to copy your .xml files to 
    this directory or to copy these files to the directory where the .xml files 
    reside.


htmlnt.cmd

    Sample Windows NT batch script to convert .xml files to .html files.
    The script also generates an index.html file that contains links to all 
    converted files. The title of the index.html can be given as a parameter 
    to the script. Edit the script to match your environment before running 
    it and to chose between HTML or XHTML output. Requires James Clark XT 
    XSLT processor 20020426a or later version (http://www.jclark.com/xml/).
    You will need either to copy your .xml files to this directory or to copy 
    these files to the directory where the .xml files reside.


htmldos.bat

    Sample DOS batch script to convert .xml files to .html files. Edit the 
    script to match your environment before running it and to chose between 
    HTML or XHTML output. Requires James Clark XT XSLT processor 20020426a 
    or later version (http://www.jclark.com/xml/). You will need either to 
    copy your .xml files to this directory or to copy these files to the 
    directory where the .xml files reside.


pdf.sh

    Sample Unix shell script to batch convert .xml files to .pdf files.
    Edit the script to match your environment and paper format preference 
    before running it. Requires Apache FOP processor (http://xml.apache.org/fop).
    Tested with version 0.20.5 (to workaround a bug on the XALAN processor used 
    by FOP, you should use the compiler option doctype(standalone) when compiling 
    your Logtalk source files). You will need either to copy your .xml files to 
    this directory or to copy these files to the directory where the .xml files 
    reside.


pdf.bat

    Sample DOS batch script to convert .xml files to .pdf files.
    Edit the script to match your environment and paper format preference 
    before running it. Requires Apache FOP processor (http://xml.apache.org/fop).
    Tested with version 0.20.5 (to workaround a bug on the XALAN processor used 
    by FOP, you should use the compiler option doctype(standalone) when compiling 
    your Logtalk source files). You will need either to copy your .xml files to 
    this directory or to copy these files to the directory where the .xml files 
    reside.


Note that you can write other XSL files for converting the XML files to other 
formats besides PDF or (X)HTML. You can also write alternative CSS and XSL 
files to change the appearance of the (X)HTML and PDF files.