# Virtuoso Documentation Project Readme

## Contents

Archive Description
Key XML/XSL Files
Instructions for Win32
Writing Chapters
Writing Functions
Writing Sections
Writing General Content

## Archive Description

Directory | Description
--- | ---
asp | Contains various ASP samples for attempts to generate the XML Docs from MS IIS.
bin | Executables and scripts for generating other formats from the XML sources.
html | HTML output directory. Generated HTML will be placed here.
images | All images pertinent to the Virtuoso documentation project. All documentation images are contained in the root of images. Images for the navigation tree are in the images/tree directory. Other images such as titles and bullet points are contained in the images/misc directory.
pdf | Generated PDF goes here.
ps | Generated PS goes here.
stylesheets | Stylesheets used in the transformation from XML. The DocBook sample is also contained in the stylesheets/docbook directory. These are samples from the docbook maintainer.
xmlsources | The XML source code for the Virtuoso Documentation project.

## Key XML/XSL Files

virtdocs.xml | Base XML file which includes other chapter/section/function files for document content.
--- | ---
html_mp_book.xsl | root style sheet for producing HTML in multi page format from the XT program. Takes parameters for selecting chapter.
html_mp_chaptermenu.xsl | Current style sheet for producing left pane chapter menu with JavaScript for the multi page HTML. Suitable for the XT program.
html_xt_common.xsl | Included style sheet where most XSL work is done.
html_functions.xsl | Contains code for rendering functions and refentries.
html_no_toc_xt.xsl | modified html_xt to work better with PDF and PS generation.
html_debug.xsl | debugging XSL. When used will display key items with their labels, ids etc so they can be verified for completion and uniqueness.

## 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

Which lets you render only a chapter of the multipage html output. This can save heaps of time for testing.

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: readme.html,v 1.3.2.2 2012/03/08 13:13:48 source Exp $
      Copyright (C) 1998-2012 OpenLink Software
    -->
    <chapter label="TBD.xml" id="TBD">
    <title>TBD</title>
    <abstract>
    	<para>TBD</para>
    </abstract>

    TBD!

    </chapter>

Where all the TBD's need something. Use other chapters for examples.

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">

line but the &name; goes in the chapter, not the top level.

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

Try and stick to the DocBook DTD.

RFC links should come from the authorative location of:
http://www.rfc-editor.org/rfc/rfc####.txt