This repository has been archived on 2023-08-20. You can view files and clone it, but cannot push or open issues or pull requests.
yap-6.3/Logtalk/xml/NOTES
pmoura c2e03a81b9 Logtalk 2.24.0 files.
git-svn-id: https://yap.svn.sf.net/svnroot/yap/trunk@1282 b08c6af1-5177-4d33-ba66-4b1c6b8b522a
2005-04-22 23:57:45 +00:00

254 lines
10 KiB
Plaintext

=================================================================
Logtalk - Object oriented extension to Prolog
Release 2.24.0
Copyright (c) 1998-2005 Paulo Moura. All Rights Reserved.
=================================================================
This folder contains supporting files for converting and/or indexing 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 on 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
AND WORKING 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 flag 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 flag. Choose the option value
that works best with your XSLT tools. To choose between the .dtd or .xsd
specifications use the xmlspec/1 compiler flag.
As Logtalk uses a single namespace for all objects, categories, and protocols,
it is advisable that you define an alternate compilation directory to store
all the XML documenting files (see the predicate '$lgt_alt_directory'/2 on the
config files). This will ensure proper working of links to other entities in
the generated (X)HTML files.
Brief description of each file in this folder:
lgtxml.xsl
XSLT file for viewing .xml files directly in in a browser such as Safari
(version 1.3 or later), Firefox 1.0.x, 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 LOGTALKUSER 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"; depending on your Logtalk installation, you may simply need
to type "lgt2pdf" in order to run the script).
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 Windows JScript script)
http://msdn.microsoft.com/XML/XMLDownloads/default.aspx
These scripts assumes that the LOGTALKUSER 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 lgt2html.js help" or
"lgt2html.sh -h"; depending on your Logtalk installation, you may simply
need to type "lgt2html" in order to run the script).
lgt2xml.sh
(bash shell script)
lgt2xml.js
(JScript command-line script for Windows; requires WSH 5.6 or later version)
Sample scripts for indexing the .xml files in the current directory by
generating an index.html file which contains links to all the files. In
addition, these scripts also make a copy of the lgtxml.xsl file to the
current directory, allowing direct visualization of the .xml files on a
supported web browser.
These scripts assumes that the LOGTALKUSER environment variable is defined.
The scripts should be called from the directory containing the .xml files
you wish to index. Call the scripts with the help option for a description
of the available optional parameters (type "cscript lgt2xml.js help" or
"lgt2xml.sh -h"; depending on your Logtalk installation, you may simply
need to type "lgt2xml" in order to run the script).
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 flag 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 flag 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.