""
daCode documentation : Writing documentation for daCode
Compiling documents

 

Compiling documents

 

Requirements

 

To compile your own documents

You will need the following software to compile XML documents:

  • an XML processor, with the corresponding stylesheets. Jade and Norman Walsh's modular stylesheets is prefered; you may also use a XSLT processor or home-brewn tools. The may have additionnal requirements, depending on the type of output you want to produce.

  • A perl interpreter (most Unix variant, such as Linux or BSD, come with perl bundeled, if you're on Windows, Cygwin includes it);

  • a Unix shell (I don't know if bash is required, in any case, sh is). As for perl, it ships with Unix variants, and bash i bundeled with Cygwin if you use Windows.

  • to generated the API doc, PHPDoc (phpdoc.de)



 

To compile for daCode official documentation

You shall do this using only the makefiles, images and stylesheets provided, and using the appropriate software as described below.

You will need:

  • Jade;

  • DocBook v. 4.1.2 DTD;

  • Norman Walsh's modular DSSSL sylesheets and collateindex.pl;

  • tidy;

  • perl and bash, of course.



 

Compiling docs for the official daCode documentation

First, prepare the makefiles: cd to doc/ and run ./configure to adapt the stylesheets, script and makefiles. Use ./configure --help to find out which options are available.

Then cd to the HTML directory of the documentation you want to build (for exemple doc/user/user-fr/ or doc/webmaster/webmaster-en/ and type make. This shall generate the HTML version of the doc. You may have to use make clean before performing the actual make.

 

Compiling for your own

If you are using jade and DSSSL stylesheets, cd to doc/ and run ./configure to adapt the makefiles. Then use make doc_name to build the doc. The generated HTML will be put in build/doc_name. You may have to use make clean before.

 

Basic compilation steps

First step: convert the multilingual XML file to proper XML. Use doc/commmon/scripts/doctranslator.pl [-d path/to/docbook.dtd] lc files..., where lc stands for the language code. If you want to specifiy an alternate docbook XML DTD, use the -d option. The generated XML files have -lc appended to their basename.

Process the XML. Use you favorite tool to do that, this paragraph will only cover the compilation with jade. You will need to find the SGML declaration for XML on you system, usually named xml.dcl, and shipped with jade. Then use jade -d stylesheet xml_declaration doc-lc.xml shall do the trick.

 

Customizing the layout

We will only cover the use of DSSSL with jade for the rendering.

We have two drivers to daCode.dsl stylesheet, which is itself a driver to Normn Walsh's modular stylesheets. These drivers are basically internationnalisation stuff. The define %default-language% which is the language to use in the rendering, and $dacode-doc$ which is the translate of "daCode documentation" in the target language. Copying daCode-en.dsl and setting thos two variables to their correct setting shall be enough for a new translation. If you want to alter more thoroughly the layout, yoou will have to learn DSSSL, and create a new driver for the stylesheets. daCode.dsl may be a good start, as most of the code which controls the layout has been copied and slightly modified here.