Virtuoso Documentation Project Readme

Archive Description

Key XML/XSL Files

Instructions For Win32

The XML sources are contained in the xmlsource directory. The top level document is virtdocs.xml. This file must contain a reference for all external files that are included in the documentation, this includes chapters, sections, and functions. See the relevant section in this document for more information about adding content to the documentation.

The documentation can be built from the makehtml.bat script. You will firstly need to configure your environment by editing the makehtml.bat file and adding a necessary entry for your machine using the others lines as an example. The environment variables %COMPUTERNAME%, and %USERNAME% are taken from the normal environment of a Win32 system and can be found by typing set in a DOS box. Multiple environments can be set here per machine/username to avoid having to keep versions for different machines in sync.

The batch file can then be run from the command line and can take switches. The more useful ones are:

makehtml mp <chapter_id>
eg: 
makehtml mp quicktours

The PDF (and PS) is generated using the HTMLDOC program. The PDF directory contains the file virtdocs_pdf.book which is a configuration file that HTMLDOC should use for generating the PDF correctly.

Writing Chapters

New chapters must be included in two places to be made visible to the documentation. Firstly they must be included in the virtdocs.xml file in the xmlsource directory, and in order for the new chapter to be rendered an entry for the file must be made in the chapter_list.txt file of the bin directory.

The file name and chapter label attribute of new chapters must mach exactly. The id attribute of the new chapter must be the same as the label but without the extension. The entry in the chapter_list.txt file then must match the id attribute.

New chapters begin with the following template:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- 
  $Id$
  Copyright (C) 1998-2018 OpenLink Software
-->
<chapter label="TBD.xml" id="TBD">
<title>TBD</title>
<abstract>
	<para>TBD</para>
</abstract>

TBD!

</chapter>

You will find the entries for other chapters in the virtdocs.xml file and chapter_list.txt file. Use these as examples to add new chapters. In the chapter_list.txt file you simply add a new line to the bottom of the list with the name of the chapter. For the virtdocs.xml file you have to add two lines. The first line is in the DTD section. The order of these is not important either, so you can make a copy of an existing chapter definition changing the entity name and filename reference as appropriate. Now you need output this entity somewhere in the documentation structure. You will find at the bottom of the virtdocs.xml file a list of the all the chapter entities, place yours where you see fit using the appropriate "&name;" markup.

Writing Functions

There is a template.xml file in the xmlsource/funref directory, USE IT!

After a function has been successfully written it must be included into the documentation. You need an entry in the virtdocs.xml file and the functions.xml file. Use the existing entries in these files for examples and please try and maintain alphabetical ordering. Although not required, this just makes life easier in the future.

Writing Sections

Adding text to an existing section is a no brainer, use the existing document content for examples. If you are adding new sections (sect[12345]'s) it may be suitable to add a new file and include this in the relevant chapter if the topic is long and isolated. There are many examples of this such as the wsdl.xml file, which is a section included in the webservices.xml file. Sections must have an entity definition in the virtdocs.xml file like chapters do but the entity is not output in that file! That means you include a:

<!ENTITY wsdl	 		SYSTEM "wsdl.xml">

Be very careful of correct nesting. Make sure that if your new section is a sect1, it must be output in a chapter. Likewise a sect2 inside a sect1...

Writing General Content