Docbook tools

Steve Whitlatch

Several months back, I had some discussion on this list about creating a Java GUI that would allow users a mostly point-and-click interface to creating customization layers for use with the DocBook XSL stylesheets. Well, I wrote the application and here it is.

Announcing the first public release of DocBook XSL Configurator! Actualy two releases, one for version 1.65.1 of the DocBook XSL stylesheets and one for version 1.66.1.

They are available for download from Sourceforge: Sourceforge

DocBook XSL Configurator versions 0.5.2_1651 and version 0.5.3_1661 are alpha, since they have not been widely tested, but I know of no bugs and consider the software fully operational.

You can get a good idea of what DocBook XSL Configurator is and what it does from the following:

DocBook XSL Configurator

DocBook XSL Configurator is a Java application used to create DocBook XSL FO customization layers. The application presents users with a tabbed pane containing several tables. Each row in each table contains several cells, one of which is editable and contains the text of the default setting for a specific DocBook XSL FO parameter. Users create projects containing paths to DocBook XML, common-customization XSL, an external XSLT processor, etc. Users then click through the tables, select DocBook XSL FO parameters they want to include in a customization layer, edit those parameters, include the customization layer in a project, write out the customization layer as an XSL file, and apply the XSL to the project's XML using the project's specified XSLT processor.

DocBook XSL Configurator version 0.5.3_1661 is an alpha release. It supports version 1.66.1 of the DocBook XSL FO parameter set. It does not yet support the DocBook XSL HTML parameter set.

Default FO parameter settings, help text, and guidelines for attribute sets ("property sets") are taken from the DocBook XSL package's FO documentation. Attribute set defaults are just guidelines.

DocBook XSL Configurator also includes a "From the Wild" table that provides users with nifty little snippets of XSL intended to help with formatting not implemented in the DocBook XSL FO parameter set. Currently, the number of these snippets is very small; however, the "From the Wild" snippet collection has the potential to grow very large and be very helpful.

Target Audience

If you are a beginner with DocBook XSL, DocBook XSL Configurator can help you a great deal by bringing all the DocBook XSL FO parameters together, with help, in a GUI. You don't have to switch windows seeking help, and you don't have to manually type out the file containing the XSL FO customization layer.

If you are an expert with DocBook XSL, this application may still be of use to you. You may benefit from the speed with which you can create and edit customization layers; you may find that DocBook XSL Configurator projects help you organize documentation sets; or, you may find the application useful for saving customization layers and associating them with specific DocBook XML instances.

Requirements and Use

DocBook XSL Configurator should work with any Java runtime environment compatible with Sun's Java Virtual Machine version 1.4.2 or later. However, each version of DocBook XSL Configurator needs a specific version of the DocBook XSL stylesheets. For example, DocBook XSL Configurator version 0.5.3_1661 needs DocBook XSL stylesheet version 1.66.1. Running a version of DocBook XSL Configurator with a version of the DocBook XSL stylesheets for which it was not intended could produce errors.

Running DocBook XSL Configurator requires no adjustments to your CLASSPATH, and the DocBookXSLConfigurator.jar file can be placed anywhere in the file system.

To use DocBook XSL Configurator, you first build a project. The project contains information DocBook XSL Configurator uses to help create a PDF or PS file from a valid DocBook XML file. The process would go something like this:

1) Select New Project from the File menu. A New Project dialog appears.

2) Navigate through the dialog, providing the following: the name of an XSLT processor, the entire option string to be passed to the xslt processor, location of the DocBook XSL stylesheet to use, location of a common-customization XSL file, an FO processor command string , a PDF viewer command string, a PS viewer command string

DocBook XSL Configurator uses the information provided to run the programs in your tool chain as external subprocesses.

3) Click through the tables, selecting check boxes for the parameters you want included in your XSL customization layer, and edit the parameter settings as necessary.

4) Save the project.

5) Select parameters and edit them as you like. Then, select Write XSL from the Execute menu. DocBook XSL Configurator presents you with a dialog. Choose a name and a location for the file to save. This is your XSL customization layer. Make certain that the filename and path match with those used when you created the project. Keep the same name and path of this file when you update it. Whenever you wish to change this customization layer, adjust your selections and edited parameters in the GUI, and then overwrite this file by selecting Write XSL from the Execute menu.

6) Select Process XML from the Execute menu. DocBook XSL Configurator runs the XSLT processor specified in your project using the options supplied. You should probably make certain that your XML is actually a valid DocBook XML instance first. While the XSLT processor is running, you can continue with your work. When it's finished, DocBook XSL Configurator presents a dialog box containing any messages produced by the XSLT processor. The dialog box is presented regardless of errors detected.

7) Select Process FO from the Execute menu. DocBook XSL Configurator executes the entire FO processor command string from your project settings. While the FO processor is running, you can continue with your work. It typically takes several minutes to complete. When it's finished, DocBook XSL Configurator presents a dialog box containing any messages produced by the FO processor. The dialog box is presented regardless of errors detected.

8) Select 'Display PDF' or 'Display PS' from the View menu. As with 'Process XML' and 'Process FO', DocBook XSL Configurator runs the project's command string as an external subprocess. When running the PDF or PS viewer command strings, DocBook XSL Configurator presents a dialog box containing messages returned from the subprocess only if it detects something went wrong.

Alone, DocBook XSL Configurator will work only partially. To make full use of it, you need the following:

- a valid DocBook XML instance. If you are new to DocBook XML, you should begin with Norman Walsh and Leonard Muellner's book, DocBook: The Definitive Guide, available online at: oasis open

- some understanding of how the DocBook XSL package works with DocBook XML. Bob Stayton's book, DocBook XSL: The Complete Guide, available online at: http://www.sagehill.net/docbookxsl/index.html, is probably the best resources available for learning DocBook XSL.

The project GPLed and open to additional developers. I'm currently the only developer. Send any bug reports to me, via the project.

Steinar Bang

Off the top of my head, I know of the following ways to transform DocBook XML into PDF, with open source/free/semi-free software:

Transform into XSL:FO, and then use one of the following to create PDF from the XSL:FO

Use the DocBook SGML DSSSL style sheets, and jade/openjade, followed by TeX

Transform into RTF, by one of the following, and then use AbiWord or OpenOffice to create the PDF:

JFOR (Java) http://www.jfor.org/

XmlMind FO Converter (Java, free for personal use) http://www.xmlmind.com/foconverter/

DocBook SGML DSSSL style sheets and jade/openjade

Use DocBookInConTeXt (TeX. Takes DocBook XML source as input) http://www.hobby.nl/~scaprea/context/

Use the DB2LaTeX XSL stylesheets, and process with LaTeX http://db2latex.sourceforge.net/

Use doctranformer (written in Java) to transform DocBook XML into LaTeX or lout for processing into PDF sourceforge

Did I miss any?

Igor Zlatkovic

Sorry if these instructions are a bit verbose, they are straight out of my tutorial (which is not available on the Internet yet)

(DaveP. They are just right!, just that I didn't have the courage to tell Daniel :-)

btw, the manual for using xsltproc can be found at xmlsoft.org

And the Windows information is at Igor's homepage

For windows:

The files you will need are available from fh-frankfurt.de

You will need to download:

The latest libxml download, at the time of writing: fh-frankfurt.de

The latest libxslt download, at the time of writing: fh-frankfurt.de

The latest iconv download, at the time of writing: fh-frankfurt.de

Extract the following files from the libxml

C:\docbook\xsltproc\ (or whatever)

Extract the following files from the libxslt archive and place in

Extract the following files from the iconv archive and place in

C:\docbook\xsltproc\ (or whatever)

Finally, append C:\docbook\xsltproc\ (or whatever) to the PATH environment variable.

For solaris you can get the files here: http://garypennington.net/libxml2/

For other Unices: ftp://xmlsoft.org/

The official download page: garypennington.net

Ok, I think thats everything.

It was for me. Many thanks. xsltproc is getting a very good reputation! If you aren't a java fan it's the processor to have.

Bob Stayton

Most problems with print output are in the FO processor, not the DocBook XSL stylesheets. PassiveTeX is another FO processor that formats verbatim elements properly, and it runs on Windows as well as Linux. I've written a draft of a short PassiveTeX Howto article that I've included below. If you would be willing to try it out and give me feedback, I'd appreciate it.

Getting started with PassiveTeX

This article describes how to install and run PassiveTeX.

Installing PassiveTeX

PassiveTeX is an extension of the TeX typesetting system that permits conversion of XSLFO files to PDF. More accurately, it is an extension of other extensions such as pdftex, pdflatex, and xmltex. For this reason, trying to add the necessary packages to an existing TeX installation can sometimes lead to mismatched components that don't work together. Because of the large number of files involved in a complete TeX installation, it can be difficult to sort out the problems.

Currently the easiest way to get PassiveTeX working is to install a new TeX system that supports it. Sebastian Rahtz, the author of PassiveTeX, has assembled such a system and made it available as part of the TeX Live CD distribution. Version 7 of TeX Live CD defines several "schemes", which are selections of TeX packages designed for particular purposes. One of those schemes is called "XML Typesetting". That scheme includes the PassiveTeX pieces needed to process XSLFO files generated by the DocBook XSL stylesheets.

The TeX Live CD has support for Windows, Linux, UNIX, and MacOSX systems. It also permits you to run your TeX processing almost entirely from the CD, installing just a minimum number of files. Since the size of a TeX installation for DocBook is over 200 MB, that may be a necessary option. But it does make the processing run more slowly because it has to read many files from the CD each time.

To install PassiveTeX from the TeX Live 7 CD:

1. Obtain a TeX Live 7 CD Instructions for obtaining a TeX Live 7 CD are available at: tug.org You can obtain the CD by joining the TeX User's Group (TUG), or you can download the CD image and burn your own CD. It is a huge download and requires a fast Internet connection.

2. Start the installation program On Windows, the CD may automatically start when you put the CD in the drive. If not, then run \bin\win32\TeXLive.exe to start it manually. Then select Install->TeXLive. That will start the setup wizard. On Linux or UNIX, run sh install-cd.sh in the top directory of the CD. The file itself is not executable, which is why you need to precede it with sh. That command presents a text interface for selecting installation options.

3. Select the XML Typesetting scheme As you step through the installation interface, you can select where TeX installs, what languages you want to support, and other options. The important step for DocBook is to select the "XML Typesetting" scheme. If you aren't offered a scheme selection as part of the options, then your TeX Live CD is older than version 7.

4. Run the installation After you have selected all the options and scheme, run the Install and sit back until it completes.

5. Adjust some TeX settings You need to increase the values of certain TeX parameters to process DocBook files. The settings are located in the following file:

Windows: \Program Files\TeXLive\texmf-var\web2c\texmf.cnf

Linux or UNIX: /usr/TeX/texmf-var/web2c/texmf.cnf

Make a backup copy of the original file, and then use a text editor to locate and change the following values to be at least these sizes:

6. Set environment variables To use a TeX system, it needs to know where the commands are located (PATH) and where the TeX configuration files are installed (TEXMFCNF). So you need to set these two environment variables. On Windows they should be set automatically, but you should check them anyway.

You can test to see if your installation is working by typing at a command prompt:

pdftex -ini "&pdflatex" pdfxmltex.ini

That will generate a lot of status messages, but should result in a file named pdfxmltex.fmt.

Using PassiveTeX

PassiveTeX will convert a .fo file created using one of the XSLT processors into a .pdf file. Once the system is set up and working, you should be able to execute the following command on your .fo files:

pdftex --interaction nonstopmode "&pdfxmltex" myfile.fo
pdftex --interaction nonstopmode "&pdfxmltex" myfile.fo

You want to run the same command twice in order to resolve page numbers in the table of contents. You'll notice that it generates a lot of status messages. If you don't end up with a myfile.pdf file, then something went wrong. All the noise is recorded in a log file named myfile.log, which you can scan for clues as to what went wrong.

Dissecting this command:

* The pdftex command runs the version of the TeX formatting engine that generates PDF output instead of the original TeX DVI output.

* The --interaction nonstopmode option forces it to keep going even if it comes across something questionable. Generally the questions it asks can only be answered by a TeX expert.

* The "&pdfxmltex" argument tells the formatter to use the TeX format file named pdfxmltex.fmt that was installed with the XML Typesetting scheme. This is the PassiveTeX extension that parses the XSLFO file and applies TeX formatting.

Note

Tables processed by PassiveTeX currently require width specifications with units in colspec elements. Proportional width specifications do not work.

Gary Lawrence Murphy et al

For a collection of mini-reviews and links to various editors, try teledyn.com and click on the Editors subject link

Also added:

The free (or that can be used for a limited amount of time) tools I know:

Ian Castle

for Windows users without a suitable compiler, pre-compiled binaries of the OpenJade 1.3.1 tools and libraries are available.

Please note that these binaries are provided as a simple courtesy - no warranties, no support etc (but I would be interested to know if they don't work! - report problems on the sourceforge page). Its available on Sourceforge

Windows Source: openjade-1_3_1.zip Windows Binaries: openjade-1_3_1-bin.zip

The most recent release of Openjade, OpenJade 1.3.1 is now available to download at Sourceforge

OpenJade 1.3.1 is very much a maintenance release. It is fully described in the release notes which are available from the location above (and included in the release).

OpenJade 1.3.1 pulls together the various patches and fixes that have been made and tested since the previous release of OpenJade, back in 1999. In addition, the new release supports new platforms and the latest GNU and Microsoft compilers "out of the box".

Eric Raymond

Eric S. Raymond has announced the release of a new utility, called "doclifter" that "lifts documents from troff source form (using the man, mdoc, ms, or me macros) into DocBook."

Bob Stayton

They might try: sourceforge.net Haven't tried it myself, though.

Various

For win32, Markus Hoenicka offers

SGML for NT describes the setup of a SGML and XML editing and publishing system on Windows. You'll get step-by-step instructions to install and configure Emacs, PSGML, (Open)Jade, TeX, JadeTeX, xsltproc, Xalan, XT, Saxon, FOP, PassiveTeX, DocBook SGML and XML DTDs, DocBook DSSSL and XSL stylesheets. In brief, the whole toolchain to work with DocBook on either the SGML or XML side. You can choose between a plain Win32 setup or a setup using Cygwin, allowing you to work in a unix-like fashion.

The name for the tutorial is historical, as it started with a few simple HTML pages describing my setup of the SGML toolchain on Windows NT (XML was not yet an issue back then). I still think of XML being a part of SGML (not entirely true, but sortof). If someone can come up with a fresh catchy name for the tutorial *without slashes* to make clear it embraces both SGML and XML, I'll be happy to use it.

The focus on the Windows platform is not due to the fact that I'd love it so much but due to my personal experience that the SGML/XML stuff is so much more cumbersome to piece together on Windows as compared to e.g. the major Linux distributions (I guess my installation instructions could be compressed to one shell command on Debian with approximately the same result).

It is available at my home page

David offers other sources:

Here are a few links to get you started (compiled from a recent thread on the docbook-apps list):

Linuxdoc For FreeBSD. A personal one, prepdoc

Julien LETESSIER adds

The fact is I've written a DocBook-app howto, er... Tutorial... Whatever, originaly with OS X in mind, but finally it's not at all OS X specific.

It describes a classic DB/XML processing chain using the Apache tools and gives lots of doc pointers.

It's a good introduction before using the comprehensive DB package I developed for projectomega.org.

Those interested can download it at in pdf, or browse it at this url (for now)

It will be available on projectomega.org as soon as it's completely finished; I'll repost then.

Sorry for the probable errors, I've only been speaking English for 10 years. Feedback welcome :)

Jonathan Marks

I wrote a Q&D Guide to install a docbook on RH 7.1. I've looked it over again. It looks simple to convert this process to Win$$. I'll include it below and annotate (>>>Win$$) suggestions for Win$$ conversion. Let me know how you fare.

This is a hybrid installation where the programs tetex and openjade are installed from RPM, and the definitions are installed from their source the remaining definitions installed from their source.

References: http://www.linuxdoc.org/authors/index.html#resources

1. INSTALLATION

1.1. Install Tetex Installed the latest Redhat version, 1.07-27 rpm. Openjade uses tetex macros. Installed all the tetex packages.

1.2. Install Openjade. Installed the latest Redhat version, 1.3.-17 rpm.

1.3. Install DocBook DTD's Got DocBook SGML 3.1 and DocBook SGML 4.1 from oasis

Get DocBook XML 4.1.2

1.4. Install DocBook Entity Definitions Got the entities and un-tgz'd it repeatedly into each of the above DTD directories

1.5. Install DSSSL Stylesheets. Got the latest (1.72) style sheets and documentation The latest version is now 1.73.

1.6. Install the LDP Customizations

2. CONFIGURATION

2.1 Create the following symlinks

2.2 Create the following file:

2.3 Add the following env variables to startup file I use bash, so add the following to /etc/profile

2.4 Apply the LDP customizations

Log out and in again for env variables to take effect.

Get a docbook sgml template to verify the installation.

For multifile html (on one line). openjade -t sgml -d c:\docbook\docbook-dsssl-1.73\html\ldp.dsl#html <sgml-filename>

for single file html (on one line) openjade -t sgml -V nochunks -V rootchunk -d c:\docbook\docbook-dsssl-1.73\html\ldp.dsl#html <sgml-filename>

for a single rtf file. (0n one line) openjade -t rtf -d c:\docbook\docbook-dsssl-1.73\html\ldp.dsl#print -o <rtf outfile> <sgml file>

To get from rtf use Win$$'s wordpad, and print using adobe's Acorobat distiller.

3 Validating and Publishing xml or sgml

To validate sgml nsgmls -sv -c $SGML_CATALOG_FILES <file>.sgml

To validgate xml nsgmls -sv -c $SGML_CATALOG_FILES $SGML_SHARE/dsssl/dtds/decls/xml.dcl <file>.xml

The following script creates a <filename>.output subdirectory, into which it creates a dvi, tex, single html, chapterised html, pdf, ps, and txt files.

Execute publish as follows to hide unnecessary warning clutter.

Ian ?? and Bob Stayton

Google suggested : this

I've not tried it ;-) but it looks like the answer to your prayers.

Bob Stayton provides the basics.

Here is one simple setup for DocBook on Windows. It has three pieces: the DocBook DTD, the DocBook XSL stylesheets, and the xsltproc stylesheet processor.

1. Download and unzip the DocBook XML 4.1.2 DTD from: http://www.oasis-open.org/docbook/xml/4.1.2/docbkx412.zip

2. Download and unzip Norm Walsh's DocBook XSL 1.45 stylesheets from: http://telia.dl.sourceforge.net/docbook/docbook-xsl-1.45.zip

3. Download the libxml kit to convert your XML to HTML from: http://www.fh-frankfurt.de/~igor/projects/libxml/index.html

You'll nee both the "libxml binaries" and "libxslt binaries" zip files. The kit includes xsltproc, an executable that applies an XSL stylesheet to an XML file.

Then you can generate HTML using:

Yes, xsltproc on Windows accepts forward slashes. You'll need to get xsltproc in your PATH, or give a full path to the command. And your xml file will need to include a <!DOCTYPE> that indicates the path to the docbook XML DTD.

The nice thing is that this same setup also works on Unix or Linux (except you'll probably be downloading and compiling source instead of binaries for libxml).

Ian Castle

Currently I am very happy with the SGML/XML -> PDF via jade/DSSSL toolchain. We (my company) don't really have any open issues. We are using the toolchain to produce release notes, user guides and, more recently, course notes (which are mainly being converted from MS word documents).

However, you will need to apply patches to the basic tools to get them to this working point.

The problem is that openjade and jadetex are interdependent. Jadetex expects openjade to be producing output consisting of various "macros". Changes in jadetex over the years have added macros - particularly in the support of double sided printing. The released 1.3 of openjade only really supports jadetex 2.7 (as does jade 1.2.x).

You need openjade 1.3 (the released version) + a bunch of fixes from Francis J Lacoste (this fixes bugs and fits nicely with jadetex 2.20 - 3.3 ) + a small patch from me which ties openjade to the recent releases of jadetex ( 3.4 - 3.11)

You want the latest DSSSL style sheets (>= 1.70 which have some key fixes for double sided printing and correct pagination of recto/verso pages) - more specifically, support OpenJade extensions required for correctly double sided printing). Of course, the latest version will do.

You want the latest (3.11) version of jadetex because this simply has the least bugs.

The recent versions of jadetex have better control of whitespace/layout, orphans/widows, tables + support for working two side printing (added in 3.4) + support for roman numerals in "front matter".

However, the DSSSL stylesheets have some problems with deciding what is front matter and when the pages start esp. when you have a complex mix of "parts" etc. There isn't really a correct generic fix. The fix that murray was talking about works for the situation where your book consists of front matter, table of contents, preface, part I, chapter ...., Part II etc... It won't work if you decide to stick a preface before each part for example. This is why it isn't in the official stylesheets - because it isn't really a solution - just reduces the problem for the most common applications.

You can find the BSD style sheet which contains this fix at freebsd website

Search for "Castle"...

I've submitted a patch for OpenJade against what was in CVS when I made the patch... this hasn't been applied, and in either case there has been no recent release of openjade. There needs to be - as openjade is being done a great disservice - when the released version contains so many flaws which have been fixed.

So, in my opinion, the best Linux DocBook SGML -> PDF toolchain is mine ;-). Fortunately, Camille included the patches to openjade + jadetex 3.11 + DSSSL stylesheets 1.72 in Mandrake 8.1. So this has the best tool chain.

If you have rpm2cpio on your debian system you can download the mandrake 8.1 RPM at the sunsite website

And extract the source + the patches. The patches you want are

[I can email these to you if you like - I don't want to bombard the list with them]

The other patches are mainly to do with the RPM build enviroment, final file locations and some fixes for the 2.96 compiler.

Further praise for Mandrake... I bought the 8.0 Boxed release and was pleased to see that the printed guide that comes with it was actually produced by openjade/jadetex - so they used a linux tool chain all the way through the production process (as this predated the roman numerals patch and a few others it looks a bit tatty..). This compares with Redhat 7.1 manuals (last version I looked at) which was authored in DocBook, produces the HTML with openjade - but used Arbor Adept/Epic (or whatever it is) running on Solaris for their printed manuals.

I hope Mandrakesoft have carried on this process in 8.1 as it is a good example of the "Dog Food" principle....

I also looked at using htmldoc, but it is inferior to the results that you get with a "fixed" openjade/jadetex toolset.

Sasha Zucker

I am using OpenJade and DocBook XML 4.1.2 to develop documentation on my PowerBook running MacOS X 10.1. OpenJade can is easily installed with Fink, a Unix software package manager for OS X that is a Perl front-end to ported Debian package utilities (e.g., apt-get, dselect). I highly recommend fink to all MacOS X users. For more information, visit sourceforge.

Note that the OpenJade pacakge is in fink's unstable branch. The only problem with the package is that it throws away files included with the source (e.g., xml.dcl) that you need to use OpenJade. This problem is easily fixed by untarring and manually installing the source files after installation. I am going to work with the package maintainer to fix this problem.

Allin Cottrell

This is a small set of files enabling literal pass-through of TeX math to jadetex, in the context of DocBook -- i.e. lets you use TeX math rather than MathML in the SGML/XML source file. Includes a utility to auto-generate PNG images from the texmath elements for use in HTML. Small addition to the DTD, a few DSSSL bits and pieces, plus some perl hackery.

Comments welcome.

Bob Stayton

I've been investigating external cross referencing with olink for some time, and have developed a new way of doing it using olink. I've assembled a customization kit for the new olink I've been working on. This kit permits anyone to form cross references between DocBook 4.1.2 documents and have them resolved by the XSL 1.45 stylesheets. Once it is set up, it is easy to use. Most of the effort is in setting it up.

I've put the kit (newolink.tar.gz) on my website> if you want to pick it up and test drive it. It includes the customizations, example files, and a sample Makefile to process the files (using xsltproc). It includes a HOWTO file with instructions for using the tools on your own files.

If you want to browse the toolkit files, I've also checked them into the DocBook SourceForge CVS tree. They are in:

You should be able to run the examples out of your working directory if you fix a couple of paths.

One of the examples (modular.xml) illustrates how you can use XInclude and this new olink to create modular content files, where each module is a valid XML document instead of a system entity.

This is the first release of this kit, and it doesn't have all the features I would like to eventually see. I'm also pursuing this with the DocBook Technical Committee to see how it fits in with future plans for DocBook.

Feedback is welcome.

Chris Maden

Try the xslt-process minor mode:

Kevin Conder

To convert docbook HTML output to plain text I use lynx in Windows at work. It works like a charm: Command is "lynx -dump -nolist in.html > out.txt"

Get your lynx for Windows here:

Sam Steingold

A way to deal with this is to convert to texinfo first and then use makeinfo to produce info text files.

The reason I think this is a good way is that texinfo format is (just? almost?) as rich as DocBook, so there should be no information loss in that conversion, and the makeinfo process of texinfo->text conversion is very well thought through, widely tested and used, and known to work.

Bob Stayton

Various documentation forms are based on plain text. In order to obtain good plain text output from html, I've found html2text to be the best tool for the job.

DaveP. I've hosted it here since the author seems to have disappeared.

Bob Stayton

I wrote a tool called LiveDTD to assist me in writing an extensive customization layer for DocBook. It converts a DTD into a browsable hypertext document, and it made navigating the maze of parameter entities much quicker. You can see a browsable version of DocBook 4.1.2 and a customized version DocBook 3.0 at: Sagehill

(the page above that describes the LiveDTD interface). When I have a question that requires looking at the DTD, I always use the live version now.

Also from that website you can download the livedtd.pl Perl script that makes these things. It is very useful for developing and maintaining a customization layer for a DTD.

Christopher R. Maden

The training package is currently available at my webpages, as a zip file >; it will probably move when I get around to integrating it into the site. It is entirely undocumented right now.

That zip includes:

The DTD has a <class> element which should be used as the root. Each <unit> can have <slide>s at the start; slides.xsl will create HTML slides from them (with slides.css and left and right.gif). The files.xsl stylesheet will extract any <programlisting> with a filename attribute for use as sample files with the class. Finally, handout.xsl will generate PDF output for distribution to the class.

The files.xsl and slides.xsl stylesheets use the XSLT 1.1 draft with SAXON to do separate file output; this could be tweaked for other processors. The handout.xsl stylesheet uses the pre-REC version of XSL for use with older FOP; that would need to be changed for the most recent version, as well.

Someday I'll document all of this

Markus Hoenicka

It is not my intention to bore anyone, but let me again tell you that the tool you wish to have already exists and is ready to use. Let's compare BibTeX and RefDB for the sake of clarity again:

- You enter your LaTeX references into a flat-file database in the BibTeX format

* You enter your references for a SGML or XML document into a SQL database. Input can be either RIS, DocBook, or BibTeX. As RefDB is Unix-style, you can write other import filters in any language that can send output to either stdout or to a file. Using a SQL database means better scalability for large collections and added benefit if you share your data with colleagues (think workgroups, departments, access control...)

- You use style files in the powerful but somewhat cryptic BibTeX format for your LaTeX documents.

* You specify the bibliography and citation styles for SGML and XML documents in XML files which are essentially templates for the sequence and appearance of bibliography and citation elements. These are also loaded into a database. This means they are pre-parsed which speeds up the formatting of bibliographies.

- In a LaTeX document, you specify with the \bibliography command which external bibliography file to use. You specify with \cite commands which references you want to cite (and appear in your bibliography). With the natbib package you gain other citation styles like textual citations: Miller et al. reported [4] that...

* In an SGML or XML document, you specify an external entity with the name of the SMGL or XML file that will contain your bibliography. In DocBook documents you specify with <citation><xref..></citation> constructs which references you want to cite. Parenthetical and textual citations are supported.

- You run latex on your LaTeX document. This will create an .aux file which contains (among other stuff) a list of all citations.

* RefDB uses a DSSSL script to extract a list of all citations from SGML or XML documents into an XML document (which you can edit to add other, not cited references)

- Then you run bibtex on your LaTeX document. This will use the bibliography style you specified in the document and will create a cooked bibliography in a .bbl file

* Then you run a RefDB app on your SGML or XML document. This will use the bibliography style you specified on the command line and will create a cooked bibliography in a SGML or XML file. It will also create a small stylesheet driver file specific for your bibliography style.

- Finally you run latex once or twice again to finalize your document

* Finally you run Jade or an XSLT processor on your document to transform it to the final output. This step uses the RefDB-created driver files to format the RefDB bibliographies (leaving alone potential other bibliographies) and the RefDB citations (leaving alone potential other citations). The stylesheet driver files essentially take care of character properties like font weight, posture etc. for various parts of the citation or bibliography. The citations are neatly hyperlinked with the references in the bibliography in all output formats that support this.

Please note that neither BibTeX nor RefDB do any "search-and-replace"-style mangling of your sources. The cooked bibliography is kept in an external file in both cases. This way it is easy to reformat your document for a different bibliography style without touching the document source. And the whole thing works for DocBook, TEI, and any other reasonable DTD (with a little stylesheet tweaking, that is).

Once again, more info is available at sourceforge Please visit this url to view example documents formatted for two different journals.

RefDB does use bibliomixed on purpose. I think the choice between raw and cooked is a compromise between philosophy and ease of implementation, speed of execution etc. I see the main purpose of auto-generating bibliographies not in creating beautiful and philosophically correct *source* documents, but to help users create correct *formatted* output. The intermediate bibliography element is a means to achieve this. The DocBook DTD explicitly defines the bibliomixed element to create bibliographic output that would be too tedious or complicated to create on the stylesheet level alone.

RefDB can import BibTeX bibliographies and use these data to create DocBook bibliographies.

Taken together, RefDB seems to be the only available tool to actually format bibliographies and citations in the output created from SGML and XML documents. RefDB does this without modifications of the DocBook DTD, and without mangling the document source. RefDB is not limited to DocBook, but does TEI as well and can be extended to any other document type.

RefDB stores far more information for a bibliographic reference than just the bibliographic data. As RefDB was designed from the ground up as a collaborative tool, it is necessary to store a part of this information, like personal notes or availability information (i.e. a URL to an electronic offprint or a description where to find that paper copy), separately for each user. So the database is necessarily relational, which cannot be achieved with a flat file. Another reason for using a database server is of course the better scalability. A flat file is fine if you collect a few hundred references, but it is a bottleneck if your workgroup collects several thousands of references. Searching a flat file of that size with regular expressions and several search criteria is not very performant.

I don't know why you want to put your database under CVS control, but if you have to you can do similar things with RefDB. You can either dump your databases to a SQL script (which is a plain text file) or you can retrieve all references in RIS format (which again is plain text). Both formats would be suitable for CVS and can re-create the SQL database.

Future versions of RefDB will support different database servers (so from your point of view you can choose your poison), including an embedded SQL server which does not need an external database server.

Norm Walsh

Several people on this list have asked about DiffMk, my tool for generating changebars automatically for DocBook (and XHTML and XML Spec) documents.

The brave at heart will find a first beta of my Java rewrite of this program at my web site

It works better, including support for a UI and word-level diffing, but it's a lot less mature and stable than the Perl version. Still, I've been using it successfully for a while so...share and enjoy!

P.S. Uh, except for the share part. I'd be just as happy if it didn't get mirrored around the globe in its current crude state.

Bob Stayton

In XMetal, you can do two things:

1. Create standard template files for each of the kinds of documents you want to create. Then you can add those templates to the File->New interface.

2. You can customize each element when it is inserted to include any children or structure you want to add. See Tools->Customizations->General->On Insert. The customizations are associated with the current DTD.

Bob Stayton

You should try PassiveTex: Oxford I find it works better than FOP.

But getting it working can be a bear. I've never gotten PassiveTex working over an existing TeX installation. There were always fatal errors, of a type that didn't make enough sense to me to fix.

I have gotten PassiveTex working on both Win2K and Linux by doing the following:

1. Download the TexLive CD image and cut a CD.

2. Install the entire TeX distribution from the TexLive CD.

3. Follow Sebastian Rahtz's directions from the above webpage *to the letter* to install PassiveTex in the new TeX installation.

Like FOP, it isn't perfect, but it is useful.

Michael Wiedmann

Jon Grov announced earlier today on Freshmeat his package "dblup" (DocBook to LaTeX using Perl) which might be of interest for some people:

"dblup (Docbook to LaTeX using Perl) enables easy and quick conversion from DocBook documents to valid, human-readable LaTeX markup. It only supports a very small subset of the DocBook-DTD."

See: sourceforge

Holger R

I recommend that you use TeXLive instead of the teTeX that comes with FreeBSD. It's available from dante

(That's the German TeX Users' Group, you should probably pick a site closer to you).

Grab the file texlive-final-20010730.iso.bz2

This ISO image contains TeX setups for various Unix derivates (including FreeBSD) and for Win*. In my opinion, it's got the best setup for TeX stuff related to SGML/XML processing.

Norm Walsh

See the oasis website

Fabian Mandelbaum

There is anonymous CVS access and also a mailing list available!

Please, check mandrake website for details about all this.

Jirka Kosek

You must set environment variable SP_ENCODING to value "XML" or "UTF-8". In the first case, nsgmls will use encoding specified in XML declaration, in the second UTF-8 will be assumed.

Togan Muftuoglu

In your customization add the following

Tim Waugh

For nroff output from XML, better to use db2man, an improved version of which is included in the xmlto RPM package. See http://cyberelk.net/tim/docbook/ for pointers to the packages you need.

You can get xmlto from here

Tim Waugh

cyberelk has information about which RPM packages you need to install for Red Hat Linux.

Gary Lawrence Murphy

Abstract

A quick 5-minute review of using LyX 1.2 for DocBook authoring. Keep in mind this is not meant to be an exhaustive review or be any sort of evaluation of LyX on its own merits, this is only a quick review of LyX with regard to editing DocBook articles in relation to the other free XML editing tools such as XXE and Emacs psgml-mode.

First Impressions

The first item that appears when trying to use the new experimental branch of the LyX word processor for DocBook is the appearance of the same familiar LyX interface; it's not totally obvious that this thing does DocBook at all. The import choices list the long defunct LinuxDoc, along with MsWord, but no DocBook. On closer examination, though, there is a DocBook Article template option.

Selecting that option, it's still not totally obvious. The filename is still a .lyx file. Highlighting text with the intention to mark it as a literal or some other DocBook tag is also not apparently obvious, and there are no interface objects which are obvious as DocBook markup.

First Commands

The first thing that does work as expected is to select a new section. This produces a proper section heading, numbered as one would expect.

Selecting a subsection, though, immediate makes the current paragraph into a subsection heading rather than opening a new heading; LyX apparently does not use a ??mark and select?? editing model, but instead uses the more confusing ??set mode and proceed?? model.

The issue remains, than, of how to introduce docbook markup.

Basic Markup

Adding basic markup like subsections follows as the usual LyX sequence of opening a new line, selecting the mode, and continuing to type, with a carriage return to end that mode and return to standard text. The other buttons, on the other hand, follow a select/op mode where text can be selected, and then the font changed via ! or the little man. The semantic meanings of these markup elements is not explained.

Entering tags

This part is pretty elusive; I'm not going to go to the manual for this because an interface should be self-revealing, but it expect this may be a place where you need to actually educate yourself as to the designer's intentions. Ditto for the buttons which, being xform based, have no tooltips --- it's anyone's guess what a ! or a little man might mean (unless you're an old-hand at LyX). The basic philosophy, then, is ??to do this, you got to know how?? but I always wonder if it is then true that since you had to learn something to use it anyway, why not simply learn the markup?

There's another button marked ??font?? with an arrow below it, but clicking this only fills the status line with ??(Changed) (font-free)?? ... whatever that means.

you do get itemized lists which repeat for each item until you back-space over the bullet

and then you can't type the next paragraph until you enter a bullet item and use the style-set to change it to standard. Most of the actions of the interface will happen from the style-select box. and this has no concept of what is valid and what is not; you can insert any tag inside any other regardless of the legality of it within the current DTD. Many of these options also have no real meaning for DocBook (such as ??paragraph?? which changes the font rather than introducing a paragraph break or something tangible like that).

I do see GUI buttons in the stylesheet, but I've been unable to discover how to add my own; IIRC, LyX lets you insert LaTeX commands inline in the text, and I expect the DocBook way is to use this facility to insert the special elements.

Special effects

There are some special effects in the style menu which may be useful, but it's not obvious what these do or how to use them; you just have to try them and see,

Description

this appears to be a description line which probably does the same as an itemized or enumerated list in creating a style that is

repeated

for subsequent lines and continued until you enter a new line and switch it back to the standard markup.

If there are hotkeys for these mode changes, there is no indication in the interface.

In addition to the style settings, LyX has a menu item caled ??insert?? which contains some special objects to put into the text.[1]to return from these objects, you have to move the cursor outside of the bounding box on the GUI display.a hyperlink insert is also a bit of a break from the flow; my biggest complaint about this mode of working is that it upsets the flow of the writing as you have to stop, fill out some sort of box (sometimes a modal dialog, sometimes an inline box) and then jump out of it to return to your prior mode.while you do this in the flow of the text, the formating given by LyX in the GUI display will become skewed as the new element will be inserted inline across the full width of the page; with the note attached to this paragraph, the line of text just prior to the note becomes justified to show only four words on the line equally spaced. This makes proof-reading a little difficult; I can click on the ??note?? icon to collapse it, but that also moves my cursor to the point before the icon, so I have to re-navigate back to the end of the sentence to continue. Again, there may be hotkeys for all this, and I do hope there are, but there are no clues as to what keys these might be.[2]Arrow keys appear to get you out of the boxes if you happen to be at the end of the box text. Arrows will also freely navigate within these displayed inline boxes as if they were part of the page.

First DocBook

With a bit of experimentation, it seems LyX saves its document in its native format, but offers an export function to save the current document as SGML DocBook; selecting this option flashes a brief message to say the file has been saved with the same name but with the .sgml suffix.

Working with Structured Docs

This is where LyX has always shined, and 1.2 does not disappoint: The Navigate menu shows the structure in an outline format allowing you to quickly move from section to section.

Printing DocBook

Producing the printout proved to be painless; the SGML produced is a little ugly but not unworkable (and you could probably use tidy to fix it); passing the exported SGML into xsltproc --html with the xsl-stylesheets produced this file as a beautifully formatted HTML rendering of a DocBook article.

Conclusions

For those who like LyX, I think you're going to be very happy, but for those who don't, be prepared for some oddities and frustrations. This is not an XML editor, it isn't a DocBook editor, it is a structured text editor that just happens to offer a DocBook export format (no idea if it imports DocBook).

For my own use, I don't think I will switch from psgml-mode, but I may use it as a means to produce simple documents or to rapidly flush out a document which I will later massage with Emacs psgml-mode. Just from this cursory look at the interface, it is apparent you can customize a lot of it, for example, it is preset with CUA keybinding which I expect can be changed to VI or Emacs (although, again, if the user can do this, the user could handle using Emacs in the first place).

Ed Dixon

Interesting! Does anyone have experience with this? Is the free lite version good enough for DocBook use? Or do you need the pro version?

Mike

There's DocParse: commandprompt.com

It's no free software, no source code provided and doesn't seem to be very configurable (according to the docs at least, it has exactly three configuration options -- to set the DOCTYPE on the resulting DocBook document). But looks like it's (relatively) inexpensive at least.

Unknown

Take a look at the following articles to learn about converting Word 2000 to sDocBook (simple Docbook):

Converting Word documents into Simple Docbook XML ibm.com

Converting RTF documents into HTML documents ibm.com

Converting RTF documents with graphics into HTML documents ibm.com

XML zone tips ibm.com

why don't you download the free or evaluation version of YAWC? This is a VBMacro Template, add-in for Word that will output Simple Docbook or XHTML provided you use the YAWC defined named styles. The YAWC site is yawcpro.com

Chris Scott

There is Rtf2fo (RTF being word's ASCII format) at rtf2fo.novosoft.com. I've only used it a couple times but it seems like it should solve what you are trying to do. You'll have to pay for it though. I've also started a project merging JFOR (www.jfor.org) with FOP (http://xml.apache.org/fop/index.html) so that one can go back from FO and output documents in RTF (or pdf). It should make an appearance in the next few months. The best thing about JFOR and FOP is they are open source.

Yann Dirson

sgml2x 0.99.4 is out. This release adds more comfort:

Yes, this is not yet 1.0. I may add support for index generation before that, and even a couple of other things listed in the TODO list.

Homepage: alcove-labs.org Savannah: savannah.gnu.org Download:savannah.gnu.or

sgml2x allows to easily format a SGML or XML document using DSSSL style-sheets, and provides the following features:

The document-class used to look for the style-sheets, and the output format, is for now only derived from the name with which the program is called, so you will want to call this program through symbolic links like docbook-2-pdf.

sgml2x is a implemented as a shell wrapper around jade(1) (or, preferably, openjade(1), although we use the generic name jade throughout this documentation), jadetex(1) and other tools.

Marc Wiener

I've been using Avenue for about 2 weeks now with a pseudo docbook DTD. I just tried loading docbook (V4.1.2) and have been successful with making the root element book. On the other hand I had nothing but trouble with my small docbook based DTD. Avenue kept crashing on me consistently. I have a call open with Quark who were able to reproduce it, but haven't heard from them in a week. My impression of the software is not favorable. I've gotten it to work for us by making a DTD that has every Quark style as a child of book and then transform it to my DTD using Omnimark (and finally to the full docbook). It's far from elegant, but it works. If it was my choice and deadline pressure didn't loom I'd drop avenue and use Noonetime.

I'm using Quark 4.1 and AvenueQuark 1.01

Bob Stayton

For those who were interested in using FrameMaker with DocBook XML, it looks like FrameMaker 7.0 will do that. I just received my copy of FrameMaker 7.0, which combines the standard FrameMaker and FrameMaker+SGML into a single product that also does XML. It comes with a DocBook XML 4.1.2 application, which means an EDD (Frame's version of a DTD), read/write rules for moving between XML and Frame's .fm file format, and a set of paragraph and inline formats.

I was able to do File->Open on DocBook 4.1.2 XML documents, if they had the correct DocBook PUBLIC identifier in the DOCTYPE. The document becomes a Frame structured .fm file, which means you are working in a WYSIWYG formatted view. You can turn on the tag boundaries for editing elements, but be sure to turn them off before saving as PDF because they show up there. The only problem I've seen so far is that literallayout line breaks aren't always preserved.

When you open a <book> document, Frame creates a standard Frame book file and divides the chapters into individual Frame documents.

I think the formatting styles in the app need some work, but Adobe says that the app they provide is just a starting point for the user to improve upon. I can't comment on its behavior as an XML editor yet. I see a couple of oddities when I round-trip XML files through it, but that may just need some tweaking of the read/write rules.

But at least FM7 loads DocBook XML 4.1.2, which is a big improvement over FM6+SGML. If nothing else, there is now a new hardcopy formatting engine for DocBook, if you can afford it. More importantly, if it works as advertised, it will open up DocBook authoring to a large class of users who prefer a word processing environment.

Ed Nixon adds

Here's a link to the thread where this was discussed on the docbook-apps mailing list: redhat.com Bob Stayton and I both posted details there about bugs/deficiencies in the current DocBook support in Frame 7. Here's a summary of a few things we've noticed so far:

From Bob:

1. The DOCTYPE declaration is changed from one with a PUBLIC identifier to one with a SYSTEM identifier, pointing to the FrameMaker copy of the DocBook DTD. The PUBLIC identifier is lost.

2. Default attributes are actually filled in on every element that has them. So every <filename> becomes <filename moreinfo="none">, etc. It's certainly valid, but mostly a lot of clutter since the DTD provides the same information.

3. Many ASCII characters are inexplicably converted to character entities. "C++" becomes "C&plus;&plus;", and http://localhost becomes "http:&sol;&sol;localhost".

4. When Saving As XML, I got a long error report about the xml:space attribute not being declared for <literallayout> and other elements. Turns out that the export rules add that attribute. It appears the left hand is complaining about the right hand.

5. My <ulink> elements inside my <literallayout> elements disappeared.

6. Blank lines at the end of a <literallayout> or <programlisting> disappeared.

From me:

7. I get an error for any footnotes I insert within Frame 7. It exports them as invalid <Footnote> elements -- uppercase, instead of the lowercase they should be. Also, it doesn't display real lowercase DocBook <footnote> content as footnotes -- only the invalid uppercase <Footnote> content is displayed correctly.

8. It also seems to add invalid 'align = "acenter"' attributes/values on inserted <graphic> and <imagedata> elements.

9. I found that all of my <ulink> elements disappeared on import into Frame 7 -- not just the ones inside <literallayout>.

It does allow you to insert <ulink> content into documents, but doesn't actually turn that content into hyperlinks (it doesn't turn <link> content into hyperlinks either).

So as far as I can tell, the only mechanism for inserting URL hyperlinks is to use the native non-XML FrameMaker hyperlink markup (i.e., type "message URL http://foo"; in the Special>Hypertext dialog, just as you would in Frame 6). On export to XML, these native Frame hyperlinks show up as processing instructions:

       <?FM MARKER [Hypertext] message URL http://foo?>

that aren't going to be useful to any applications other than Frame.

There is an Element Tag submenu under Special>Hypertext, but <ulink> and <link> are not on it.

10. On the upside, it does let you use the native DocBook <xref> element for inserting cross references, and exports those to XML correctly.

???

A nice way to integrate docbook and math-rendering via tex its DBTeXMath (ricardo.edu), maybe you should give it a try

Michael Fuchs

I want to announce DocBook Doclet. The DocBookDoclet creates DocBook SGML 3.1 or 4.1 and XML 4.1.2 code from Java source documentation. It is helpful if you want to print reference handbooks of your API.

About: The DocBook Doclet creates DocBook SGML or XML from Java source documentation or HTML files. It is helpful if you want to print reference handbooks of your API. Normally it is used with the Javadoc tool but it can also be used as a standalone application to convert HTML to DocBook. Additionally it comes with a Swing application to manage documentation projects and to transform the resulting DocBook files to PDF.

Changes: This version is of special interest of those, who want to convert HTML to DocBook XML 4.2. There was a total rewrite of the tokenizer, the parser and the transformation engine. The rewrite is not finished yet and invalid DocBook Code might still be created, but the transformation should be much more robust than in prior versions. The HTML - DocBook converter is now deployed as an independant jar archive (html2db.jar). A solution for deeply nested tables is also provided: Tables which are nested more than one level are swapted out to the parent of the topmost table.

For more information, see freshmeat.net

Bob Stayton

I don't know of a stylesheet for text output, but you might look at html2text. It gives you control over indents and such. It is available from: ~mbayer

Bob Stayton

So far i've managed to use Xinlcude and do things along the lines of:

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML 
V4.1.2//EN" "docbookx.dtd" [
<!ELEMENT xi:include (xi:fallback)>
                  <!ATTLIST xi:include
                      xmlns:xi  CDATA #FIXED 
"http://www.w3.org/2001/XInclude"         
                      href       CDATA                        
          #REQUIRED
                      parse      (xml|text)                   
           "xml"
                      encoding   CDATA                        
          #IMPLIED
                  >
<!ELEMENT xi:fallback ANY>
                  <!ATTLIST xi:fallback
                      xmlns:xi   CDATA #FIXED   
"http://www.w3.org/2001/XInclude"
                  >
]>

<article>
  <articleinfo>
    <title>Test</title>
    <author>
      <firstname>Sagar</firstname>
      <surname>Shah</surname>
    </author>

  </articleinfo>
  <section id="MyFirstSection">
    <title>foo</title>
    <para>la la</para>  
    <xi:include 
href="docbook-tech-support-1.dbk#xpointer(id('OtherIssues'))"/> 
  </section>
</article>

This all works fine :-)

I don't know how mature it is, but the Xinlcude support in libxslt and libxml2 works great for me :-)

I'm also using xincludes with xsltproc with good success. To do so, you just add --xinclude to your xsltproc command line. I understand that Cocoon implements xincludes as well, but I've not tried it. I've looked but not found support in Saxon for xinclude.

I've kept my xinclude usage simple: a master book document that contains just a sequence of <xi:include> elements to pull in the chapter files. Many people set up their books using external entities this way. The advantage of xincludes is that each chapter file can be a complete XML document with DOCTYPE declaration. That means chapter files can be loaded into an XML editor and validated individually without doing DOCTYPE tricks.

With a simple book file like this, I never have to load my book document into my XML editor, where it would complain about the DTD not declaring <xi:include> elements. I did try creating a DTD customization, but decided I didn't need it with this simple setup. I just make sure my individual chapter files are valid.

xsltproc supports xincluding part of a document using the #id syntax to locate an element by id. I tried some other XPointer syntax, but couldn't get it to work. I also tried using nested xincludes, but the internal ones were not 'included'.

To validate my book, I use xmllint, which is included with xsltproc:

xmllint --xinclude --postvalid --noout book.xml

I've run into situations where I wanted to process my content with tools that don't support xinclude. For those situations, I preprocess my book file to resolve the xincludes first. I use xsltproc --xinclude and a trivial XSL stylesheet that outputs all elements and attributes. Then I run the results through the other processor.

Unknown

There is a OpenOffice to Docbook converter (in French and in developpement) : chez.com

As soon as the 0.3 version is released, it may be translated in english and post to this list.

The source code may still be useful for a Docbook to OpenOffice converter.

Steve Ball

In an effort to live in a M$ free world, I've developed an XSL stylesheet for the DocBook Slides DTD v3.0b1 that produces an SVG rendition of a set of slides. The idea is to have a slideshow that mimics PowerPoint without having to use PowerPoint (IOW, it's "pointless").

Until recently I used HTML for slides. The problem with that is that the navigation elements are always visible and that the presenter must use the mouse to locate and click on the 'next' link. I always found that to be awkward.

Instead, these SVG slides use a mouse click to navigate to the next slide. At the end of the slideshow, the last mouse click returns to the title foil. On all foils except the title foil there are hidden navigation 'buttons' for the previous foil and to return to the TOC foil. Moving the mouse over these buttons reveals them (navigating backward is an infrequent task, so having to use the mouse to do that is OK for now, but see below).

Please note that SVG doesn't readily support scrolling, so it is up to the user to ensure that foil content will fit within the slide boundaries. Most SVG viewers will allow panning, but that's a poor substitute. Also, SVG will not wrap long lines. Again, it is up to the user to break up long lines into smaller, digestable lines.

The stylesheet hasn't been tested on foilgroups; I'll be implementing and testing them soon. Also, very few of the DocBook elements are supported - only para, itemizedlist and imageobject. However, I thought I'd share this early work ASAP to get feedback and suggestions.

I have put up a page on our website with the download and usage instructions: zveno.com

Future work (apart from handling foilgroups and more elements) will include:

Pradeep Padala

For conversion from tex and wiki to docbook, TLDP has some tools here http://tldp.org/downloads/ wt2db can also handle text to docbook conversion to some extent.

For conversion from man pages to docbook, you can use this tool. http://www.tuxedo.org/~esr/doclifter/ It has link to some what stable and old distribution. I wrote a patch for this to add some more functionality. You can get the patch and the devel version at http://www.cise.ufl.edu/~ppadala/projects/doclifter I am not distributing doclifter. It's for your convenience only. You should ask Eric for proper release info.

I also wrote a patch to tidy which does the conversion of html to docbook. Details here. http://www.cise.ufl.edu/~ppadala/tidy Let me know, if you need help on this. I have successfully used it on HTML documents submitted to TLDP.

Yann Dirson

There is also perlsgml. The code's quite old, and there are useful patches around, but it usually works fine, and gives a result similar to TDG. patches: utoronto.ca and ftp, debian site

Michael Smith

Eric S. Raymond recently released v1.0.0 of doclifter, a Python 2.2 utility that converts man pages and other troff/nroff/groff documents to DocBook XML and SGML. I wrote up a short news item about it:

Here's a summary of the main features:

Stefan Priebsch

Today, we released the e-novative DocBook Environment (eDE) 0.5.3, a ready-to-go environment to work with DocBook on Windows. You are welcome to download it for free at docbook.e-novative.de.

Any questions, comments and suggestions are most welcome.

Markus Hoenicka and Egon Willighagen

for people interested in a comparison between JReferences and RefDB I'd suggest to go back in the list archives about 1 year. We had a funny discussion back then.

I haven't tested any recent releases of JReferences, but from what I've gathered from the current discussion I see the following main issues that set RefDB apart from JReferences:

- RefDB works with DocBook XML and SGML documents, TEI XML documents, and LaTeX documents (with somewhat limited capabilities). Other SGML/XML document types can be added without modification of RefDB itself (just some stylesheet hacking).

- RefDB does *not* require any changes in the DTDs. Documents remain valid against the stock DTDs, so using RefDB does not create an interchange issue.

In the next version (October 2002) JReferences will not require that too

- RefDB does not modify the SGML/XML source document. The bibliography is created as an external entity. The citations (which are actually xref elements) are rendered by pulling in the appropriate information from the bibliography element and are hyperlinked (in HTML and PDF output) to the corresponding references in the bibliography. The advantage of not modifying the source document is that reformatting the document for a different bibliography style is a snap.

JReferences does change the doc, but that is easy to change... Might be an advantage too sometimes...

- RefDB uses a bibliography style database to render citations and bibliographies according to a specific style of a publisher or of a publication. This includes aspects like the sequence of the elements (authors, year, title, journal, volume, issue, pages...), the rendering of the author names (FM Last, F.M. Last, F. M. Last, Last,F.M. and all other permutations), as well as the rendering in the output formats (volume bold or italics, journal names regular or italics etc). Both author/year and numeric citation styles are supported. The styles are defined as XML documents.

A tie?

(Markus comes back with)

I wouldn't say so. One important difference is that JReferences uses Java classes to implement bibliography styles (it apparently does not know citation styles at all), whereas RefDB uses XML documents that define both the citation and bibliography style of a particular journal or publisher for up to 26 publication types (article, book, chapter, unpublished, thesis etc). I can expect anyone writing DocBook documents to be able to create an XML style specification without knowing how the RefDB C code works, but I wouldn't bet that all DocBook authors know enough Java to create a new JReferences style.

- In addition to the document-based bibliography output, RefDB can generate raw bibliographies in DocBook SGML/XML, TEI XML, RIS, BibTeX and a few other formats.

JReferences supports BibTeXML, DocBook, BibTeX at this moment only.

- RefDB is a multi-user system. Users can share a common reference database and still maintain their personal info (notes, reprint status, availability etc).

- RefDB uses a SQL database to store the references. The current stable branch uses MySQL, the development branch in CVS uses MySQL or PostgreSQL. Support for an embedded SQL library is in preparation.

These two are the reason why I continued JReferences after that discussion about a year ago. I still think RefDB is an excellent program, but not if you do not have a MySQL server around...

- RefDB uses scriptable command-line clients as well as a web interface. This offers both a convenient graphical interface and the power of unix plumbing.

True. JReferences will have a editor in the future.

- RefDB can store far more information per reference than actually is used to display the reference. Additional information includes an unlimited number of keywords, an URL to an electronic offprint, personal notes, availability information (where is that paper copy?), abstracts etc. This greatly simplifies retrieving the proper references and maintaining a large collection of paper or electronic offprints.

JReferences supports this too by using BibTeXML file database... Many ways to do it...

- RefDB can directly import RIS (the lingua franca of Windows reference databases), BibTeX and DocBook (with a little stylesheet tweaking) references. TEI import is in preparation.

JReferences support import of RIS, BibTeX, DocBook and BibTeXML.

Therefore I wouldn't support the notion that RefDB and JReferences are "similar" but the decision is left to those who actually use and compare both apps.

To see the RefDB bibliography capabilities at work, I suggest to visit: sourceforge.net

You'll find links to a DocBook SGML document transformed to HTML for two different biomedical journals, as well as a link to a TEI XML document transformed to PDF.

More info: sourceforge

jreference sourceforge with an intro at sourceforge.net

Markus's final response is:

Another issue are multiple citations containing consecutive reference numbers. Some styles just list them, others convert them to ranges, i.e. (1,2,3) vs. (1-3). I couldn't find any support in JReferences for this.

Many journals use some sort of author/year citation styles with all its intricacies. This includes the same author name formatting issues as in the reference styles, plus the fact that in citations the number of cited authors usually is limited and that the first and subsequent citations of the same reference may be formatted differently

Another helpful thing are in-text citations, like Jones et al. wrote recently (2001). Again, I don't see JReferences support this.

The main weakness of JReferences appears to be the missing support for document transformations. As far as I can interpret the JReferences sources (some sort of documentation would be helpful!), the modified documents are rendered by the default stylesheets. This is clearly insufficient for all styles that require parts of the citations or of the references to be rendered e.g. in boldface or in italics. This can't be (and should not be) encoded in the SGML document. RefDB creates matching driver files (DSSSL or XSL for DocBook, XSL for TEI) based on the citation and reference style which helps to render the document properly in any of the available output formats. This is essential if e.g. your publisher accepts only formatted Word documents, which is quite common in the life sciences these days.

All this doesn't mean that JReferences is bad software, but you should be aware that a large number of the bibliography styles used in life sciences is currently beyond the scope of that software, whereas RefDB handles them gracefully.

Stefan P