XMLPublication user documentation

by J.M. Vanel , Copyright © J.M. Vanel - 2001-2002 Back to main page

Last update:

Installation

First you need a Java runtime (JRE) or JDK; I use a 1.4.0 JDK; it probably still works with 1.3 . See below for ressource URL's.

We thrive to make installation easier, our goal is "no installation". We hope that an Ant build.xml file will be able to fetch everything. But for now, this is it:

• Unzip the distribution
• set the EDITOR environment variable to your programmer's editor suitable for XML files (must use a DTD-less editor for now, since we haven't done a DTD!); on Linux I put gvim; if you have none on Windows just put notepad or write
• install Ant , a Java based build tool

• in the distribution directory type : ant

Below you will find examples of environment variables settings for different OS.

In addition for desktop publishing connectors you will need one or more of the following (optional, not needed if your source documents are regular XHTML) :

• tidy to convert HTML into XHTML
• the Perl module Spreadsheet::ParseExcel; get them from Comprehensive Perl Archive Network (CPAN) ; download and install in this order:
  • IO-stringy-1.220
  • OLE-Storage_Lite-0.08
  • Spreadsheet::ParseExcel

Basic use

1. copy the directory empty_project/ into a new directory (no space in directory name), say myProject/
2. drop in myProject/ any number of source documents with the following suffixes:
   • .table.htm or .table.html for table structure
   • .parag.htm or .parag.html for paragraphs and sub-paragraphs delimited par h1 and h2 titles
   • .xls file for MS Excel files
3. type "ant" in a shell (Unix or Cygwin or DOS) in myProject/ directory
4. possibly edit the USER_SETTINGS/thesaurus.xml file in the newly appeared window; I reassure you, it works unchanged
5. direct your browser to the generated pages at html/index.html
6. possibly repeat steps 2 to 4 (or 3 and 4 ); at step 4 possibly edit other things in USER_SETTINGS/ directory (see below "Customization" )
7. upload the html directory to your Web site
8. type "ant clean" in a shell , or just "ant clean-html"

In any situation, you can directly type ant. XMLPublication will start an editor for USER_SETTINGS/thesaurus.xml if it sees that it might not be up-to-date. See below for sample files.

Philosophy of use

• XMLPublication will never erase or modify your source documents in the project directory, nor the content of the USER_SETTINGS/ subdirectory;
• XMLPublication will create your Web pages automatically, and then, seeing what you get, you can adjust settings and redo them.
• Behind XMLPublication is the power of Ant, a make-like build tool that ensures that result pages are updated when needed.
• A search engine à la Google is a good thing, but if you don't know which keyword(s) to type, you are embarrassed. XMLPublication allows to present to the Web user just the relevant keywords for each rubric.
• The USER_SETTINGS/thesaurus.xml file is a specification of how the index pages shall be generated. It is a "declaration of interest" in rubrics and keywords attached to them. If a rubric or keyword doesn't appear in thesaurus.xml, it will not appear in index pages. A starting-point thesaurus.xml is generated by XMLPublication, containing all the words in each rubric. Since this certainly too much for most documents, you will want to remove some or many keywords by editing thesaurus.xml. Although this is the normal way to do, you can also reuse index entries from books or other documents in the same domain of knowledge.

Customization

Document treatment

After any change, just type ant in a shell to remake the Web pages.

• edit the thesaurus.xml file to modify the way rubrics (fields) are indexed:
  • if you want XMLPublication to scan the document source file(s) for index entries in rubric myTag1, instead of using the given index entries, modify like this:

    <rubric use-keywords='no' ...

  • if you want to remove index entries in rubric myTag2, remove some of the <w> elements

  To help you edit this file you can consult the USER_SETTINGS/publication.xml file which is an exact image of the index entries present in all the document source file(s) . The first time the project is processed, thesaurus.xml is created from publication.xml. Afterwards, thesaurus.xml is never modified by the framework, but publication.xml is always updated with respect to document sources.

• you can customize how to generate a human-readable name and an HTML file name from an item by editing the USER_SETTINGS/item_file_name.xslt file. For a first trial you can consult the kernel/item_file_name-generic.xslt file which works with any source document, although the item_name, which will be displayed in the HTML pages is not satisfying for all documents;

Web pages generation

• You can customize the site specific XHTML wrapper (presentation.html), the user document header (book-title.html ), or again the thesaurus.xml file, and re-type "ant" ; only the necessary files will be updated.
• CSS formatting: most of the HTML generated by XMLPublication has class attributes. This allows to associate CSS styles to specific elements of the Web pages. This is the standard way to specify colors, fonts, and styles in Web pages and all HTML editors support this. In XMLPublication the best way is to define styles in the site specific XHTML wrapper (presentation.html) .
• New! Merge items (from different document sources) having one same rubric (typically the species name); in thesaurus.xml at first level add this :

  <merge-items according-to-label="my-rubric-label" group-by="rubric|source" />

  and type in the shell "ant all-merge" .

  Instead of the default, which is to create one HTML page per item, this will generate one HTML page for each different value of the specified rubric, thus merging items from different document sources.

XHTML documents

If your source documents are regular XHTML (like those produced by Amaya), they must have suffix .xhtml or .html . in the work/directory of your XMLPublication project. Files ending with .html and .xhtml are considered OK and are simply copied in $WORK directory.

Non-XHTML files

Files ending with .htm are considered non-XHTML files and a corresponding .html is generated in $WORK directory; the tool does an automatic tidy for MS Word and other editors producing non-XHTML files. So if you have an MS Word file file.htm containing paragraphs and sub-paragraphs, rename it file.parag.htm before calling ant .

Table or paragraphs?

Currently there is no "expert system" to guess the kind of HTML! It would be difficult to develop such an "expert system" because you can have <table> inside paragraphs or the revers. So we rely on file suffixes on source documents:

• .table.html or .table.htm or for table
• .parag.html or .parag.htm for paragraphs and sub-paragraphs delimited par <h1> and <h2> headers

Samples

The sourceDocs/directory in the distribution contains various source documents that you can drop into a copy of the empty_project/ directory. Any number of source documents can be put, with common rubrics or not, with table or paragraphs initial structure, and XMLPublication will generate consistent index pages by rubrics.

Troubleshooting

Rarely processing is blocked at the tidy stage; just kill -15 the process or kill the window and make ant clean .

Tips

If you type ant -logfile ant.log, the messages of XMLPublication will be kept in that file. You can add to that -verbose to have extra information about what ant does.

If you type ant -projecthelp , you will see the intermediary targets (steps) making the XMLPublication workflow.

If you type ant schema.xml , you will get a digest of the content of your source documents, combining an XML Schema-like syntax with element count information. This is a 100% generic stylesheet (example2Schema.xslt) that you can reuse for any XML file!
There is also "ant statistics" to generate statistics on the number of items (<h1> tags) and rubrics (<h2> tags) .
"ant helpers" launches schema.xml, statistics and words-list-by-rubric.xml.

Ressources

• Saxon XSLT processor
• Ant (Ant is a Java based build tool )
• Cygwin
• eXist , a very usable XML - XPath - DOM retrievial engine, that indexes text content

XML editors : these are good for DTD-less documents :

• vim - Vi IMproved, a programmers text editor http://www.vim.org/ : comes with Linux and Cygwin
• XED -http://www.ltg.ed.ac.uk/~ht/xed.html : alas no good for iso-8859-1

Recommanded (X)HTML editor :

http://www.w3.org/Amaya/ from W3C, a good (X)HTML editor, with MVC design, and SVG and MathML capabilities; converts HTML to XHTML and windows-1252 encoding to iso-8859-1 or utf-8

Examples of environment variables settings

Here is an example of a .bash_profile file for Cygwin for ant :

export ANT_HOME=d:\\ecoropa\\Seedsavers\\jakarta-ant-1.4.1
export JAVA_HOME=c:\\Program\ Files\\JavaSoft\\JRE\\1.3
export PATH=$(cygpath -u "$JAVA_HOME")/bin:\
$PATH:$(cygpath -u "$ANT_HOME")/bin
export EDITOR=notepad

Here is the same example for a regular Unix :

export ANT_HOME=/usr/local/jakarta-ant-1.4.1
export JAVA_HOME=/usr/local/JavaSoft/JRE/1.3
export PATH=$JAVA_HOME/bin:$PATH:$ANT_HOME/bin
export EDITOR=gvim

Here is the same example for a DOS autoexec.bat :

set ANT_HOME=d:\ecoropa\Seedsavers\jakarta-ant-1.4.1

set JAVA_HOME=c:\Program\ Files\JavaSoft\JRE\1.3 

set PATH=%JAVA_HOME%\bin;%PATH%;%ANT_HOME%\bin
set EDITOR=notepad

Back to main page