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.txt

223 lines
8.1 KiB
Plaintext
Raw Normal View History

================================================================
Logtalk - Open source object-oriented logic programming language
Release 2.30.1
Copyright (c) 1998-2007 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 shell and command-line scripts 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 THESE SCRIPTS!
Regarding conversion to (X)HTML, 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 xslfile/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 generated either 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 specificationfile 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 xmlsref/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,
you may want to define an alternate, global compilation directory to store all
the XML documenting files, thus ensuring proper working of links to other
entities in the generated (X)HTML files. This can be easily accomplished by
using the predicate '$lgt_alt_directory'/2, which is defined on the config
files, and by setting the altdirs/1 compiler flag to "on". For example:
'$lgt_alt_directory'(xml, '%LOGTALKUSER/xmldocs/').
...
'$lgt_default_flag'(altdirs, on).
...
Brief description of each file in this folder:
lgtxml.xsl
XSLT file for viewing XML files directly in a browser. The links
in the (internally generated) HTML 4.01 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 4.01 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.1 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.
lgtpdf.xsl
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)
and RenderX 4.4 (http://www.renderx.com/).
The "lgtpdf.xsl" file defines a parameter for the paper format (either
A4 or US Letter). The files "lgtpdfa4.xsl" and "lgtpdfus.xsl" import the
"lgtpdf.xsl" file and set the paper format parameter to the appropriate
value.
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
DTD file describing the structure of the XML files generated by
Logtalk.
custom.ent
Document type description defining XML entities for personal data
that may be used on Logtalk documenting directives.
logtalk.rng
RELAX NG file describing the structure of the XML files generated
by Logtalk.
logtalk.xsd
XML Schema file 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
* Lunasil Xinc processor (tested with version 2.02)
http://www.lunasil.com/index.html
* RenderX XEP processor (tested with version 3.8.1)
http://www.renderx.com/
When using the FOP, you must compile your Logtalk source files using
the compiler option xmlsref(standalone) in order to workaround a bug
on the XALAN processor used by this processor.
These script assume that the LOGTALKHOME and LOGTALKUSER environment
variables are 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 LOGTALKHOME and LOGTALKUSER environment
variables are 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 copies of the "lgtxml.xsl"
and "logtalk.css" files to the current directory, allowing direct
visualization of the XML files on a supported web browser.
These scripts assumes that the LOGTALKHOME and LOGTALKUSER environment
variables are 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).
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.