yap-6.3/Logtalk/xml/NOTES

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

Copyright (c) 1998-2006 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 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 
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

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