This page contains informations and instructions on how-to setup your environment if you want to contribute to the Firebird Documentation Project.

Used tools:
If you want to contribute to the Firbird Documentation Project, there are several tools that you have to install and configure. The first program you need is an CVS client which allows you to check out the latest version of the manual(if you want to actively contribute please ask in the "firebird-docs" mailing list for CVS write access). Next you need the Java 2 SDK(Standard Edition) and a XML editor. That's almost everything you need to check out, modify and compile the Firebird documentation.
The good news at last: All the tools presented in the next section are free.

• Download and install your favorite CVS utility. For Windows I recommend WinCVS. For Linux you don't need to download any additional software because CVS support should be included in your distribution.
• Download and install the Java 2 SDK(Standard Edition) from Sun Microsystems.
• Download and install your favorite XML editor. I recommend the Windows text editor ConTEXT. ConTEXT isn't actually a true XML editor but it supports syntax highlighting and that is enough for me. If you want an free XML editor which also supports XML syntax checking, try NT-Emacs. For Linux you can use Emacs which ships with nearly all distributions. If you want to use Emacs you have to check out PSGML Tricks and Editing SGML with Emacs and PSGML to enable syntax highlighting and checking.

After you are done with the installations create an environment variable called "JAVA_HOME" and point to the folder where you installed the Java SDK. Next you have to start your CVS client and check-out the modul "manual" from the Sourceforge CVS repository with the following commands:

• If you only want to check-out and don't want to contribute:
  "cvs -d:pserver:anonymous@cvs.firebird.sourceforge.net:/cvsroot/firebird login"
  and after you have successfully logged in use
  "cvs -z3 -d:pserver:anonymous@cvs.firebird.sourceforge.net:/cvsroot/firebird co manual".
  to checkout the manual in your local folder.
• If you have write access then you have to use the following command:
  "cvs -z3 -d:ext:developername@cvs.firebird.sourceforge.net:/cvsroot/firebird co manual"
  But remember that you need SSH access when you later want to commit changes to the manual tree. Please read the guides in the paragraph CVS - OS Specific Information about how to set-up and configure CVS and SSH access on Sourceforge.

Compiling the documentation:
Now open the prompt(terminal window) and change to the folder where you checked out the "manual" module. Next change to the folder "src\build" and execute the following command: "build defaulthtml"(there is a "build.bat" and "build.sh" files for both OS's in place). The compile process starts and you can watch the the generation of the output HTML files.

Deploying the compiled files:
Open the prompt(terminal window) and change to the folder where you checked out the "manual" module. Go on and change to the folder "dist\docs\defaulthtml". In this directory you can see the whole compiled Firebird Documentation in HTML format. Open "index.html" in your browser and you can see what already has been done by the Firebird Documentation Project.

1. Post in the in the "firebird-docs" mailing list and ask for CVS write access. This allows you to check-in your modified files.
2. Make sure your CVS write access via SSH is configured properly.
3. Choose your working area.

• Use tags to indicate the logical structure of the content, not to attempt to specify appearance.
  To reiterate, attempts to use the structural DocBook tags to influence presentation appearance are unlikely to produce useable results on all presentation platforms (html and pdf).
• Do what you can to ensure you turn in a valid DocBook file.
  If you notice any parser errors during documentation build, correct them to ensure XML validity. If you get absolutely stuck notify one of the documentation leads. The reviewers will correct any DocBook errors you create, but please try to reduce the number of errors.
  Constructing valid Docbook xml is much easier with the use of a xml-dtd aware editor such as emacs + psgml.
• All <chapter> and major <section> tags must have an id attribute. The id must be all lower case, with dashes seperating words: <section id="migration-mssql">
  This is very important since it allows other documentation writers to refer to your chapters and sections.
• When trying to decide between an ordered and unordered list, simply ask yourself the following question: "Does the order of the listed items matter?" or "If I change the order of the listed items, does that change the meaning of the list?". If you answer "No" to either question, then an unordered list is likely the logical choice.
• When referring to chapters, sections, code samples, figures and other parts of documentation use either <link> or <xref> element.
  <xref> element is more powerful since it creates both link and link text. You should use it whenever possible.
  For example: If there is a figure somewhere in the documentation <figure id="mssql-to-firebird-data-types"> then using <xref linkend="mssql-to-firebird-data-types"/> creates both the link to that figure as well as link text. Link text is usually autogenerated (in case of figures - figure number) or assigned by the author of that link target.
  <link> element also creates links, but you assign link text. For example: <link linkend="mssql-to-firebird-data-types">mapping MSSQL to Firebird data types</link>.
• Use <ulink> element to create links to other URLs. For example: <ulink url="http://www.oasis-open.org">OASIS, the home of Docbook.</ulink>.

Downloads:
Nothing yet.

Frequently Asked Questions:
Nothing yet.

Additional information and resources:
Nothing yet.

If you have any suggestions, bug reports or criticism please drop me an E-Mail.