Publishing your document on the Firebird website

Naming the PDF file
Single-page HTML
Uploading the PDF
Uploading the multi-page HTML files
Updating the Firebird Documentation Index

In order to publish your document, you first have to build the HTML and PDF output. This is documented in the Firebird Docbuilding Howto. In the remainder of this section it is assumed that you have successfully built the HTML and PDF files.

Naming the PDF file

The build tools automatically name each file after the ID of the topmost DocBook element it contains. We don't change the names of the multi-page HTML output – these pages are primarily intended for online browsing, and changing even a single file name would immediately break a number of links contained in the other pages. But PDFs are often downloaded by the reader, and having files called qsg2.pdf or ubusetup.pdf in a download directory or on one's desktop doesn't really help to identify them as Firebird manuals. So here are some guidelines for the file names:

Make sure the name contains the word Firebird, preferably at the beginning;
Try to make it resemble the document title, but keep it short;
Use hyphens (“-”) to separate words;
If the title is long, omit parts like “manual”, “guide”, “howto” etc., unless leaving them out would cause confusion;
Use the language of the document, but ASCII-only (no accents etc.)
If (and only if) applying the above rules leads to a file name that already exists in another language, add the document language (or an abbreviation thereof) to the name.

To illustrate these guidelines, some of our existing file names are listed below:

Firebird-2.0-QuickStart.pdf
Firebird-Security.pdf
MSSQL-to-Firebird.pdf
Firebird-Generator-Guide.pdf
Firebird-nbackup.pdf
Firebird-2.0-Schnellanleitung.pdf
Firebird-1.5-Arranque.pdf
Firebird-et-Null.pdf
Firebird-nbackup-fr.pdf
Firebird-su-Ubuntu.pdf
Firebird-nbackup-nl.pdf
Guia-Escrita-Firebird.pdf
Firebird-1.5-BystryjStart.pdf
Firebird-Perehod-s-MSSQL.pdf

Single-page HTML

If and when we start publishing single-page HTML files on the website – produced with build monohtml – we should give them the same name as the corresponding PDF, but of course with an .html extension.

Uploading the PDF

If you have write access to the Firebird web server, make an SFTP connection to web.firebirdsql.org and upload your properly named file(s) to:

/srv/www/htdocs/pdfmanual (English docs)
/srv/www/htdocs/pdfmanual/fr (French docs)
/srv/www/htdocs/pdfmanual/ja (Japanese docs)
etc.

Release Notes however go to:

/srv/www/htdocs/rlsnotes
/srv/www/htdocs/rlsnotes/fr
etc.

If you don't have access to the server, ask someone else to upload the document(s) for you, or – if you are a project member – ask for a user name and password on the server.

Uploading the multi-page HTML files

Make sure you upload all the necessary files: the HTML files that together form your manual(s), the stylesheet firebirddocs.css (if it has changed since the last upload), as well as the subdirectory images with any content that has changed or has been added. To keep all the links working, it may also be necessary to build and upload the parent book of the document you have created or updated (or even the entire set). Upload the whole shebang to:

/srv/www/htdocs/manual (English docs)
/srv/www/htdocs/manual/fr (French docs)
etc.

Warning

If the pages in question belong to another base set than the default firebirddocs (e.g. papers or rlsnotes) do not place them in the directories mentioned here. We haven't made any clear rules for this yet, but multi-page HTML builds from different sets should not be mixed. If this situation arises, bring it up on the firebird-docs list.

Updating the Firebird Documentation Index

The Firebird Documentation Index at http://www.firebirdsql.org/index.php?op=doc is a PHP script that picks up most of its content from data files on the server. If you have updated existing documents that are already in the Index, you don't have to do anything here, unless you've changed the file name. But if you have created a new document or a new translation, you must add it to the Index. Here's how:

If you have created a completely new document

Look at the Documentation Index and decide which category is best suited for your document. (Categories are indicated with orange headers.)
Connect to the server, cd to /srv/www/htdocs/doc and look at the files starting with Cat_. Open the one that corresponds to the chosen category.
Read the instructions at the top of the file.
Create a new section starting with the document title in English, followed by a specially formatted line for each available version. For a new document, such a section could look like this:
```
Firebird Uninstallation Howto
en:/manual/fb-uninstall.html
en:/pdfmanual/Firebird-Uninstall.pdf
```
Each version line starts with the language code, followed by a colon, followed by a URL. For documents on our own server, this URL is simply the “absolute” path from the server root. Sections are separated by empty lines. The order of the sections in the file determines the listing order of the documents within their category on the Documentation Index web page. The order of the version lines within a section is irrelevant.
Save the file. If you've edited it on your own computer, upload it back to the server. Now refresh the Firebird Documentation Index page in your web browser and check if the document is listed where it should be, and if the links work well. Also verify that the links are in the right columns (HTML in the middle column, PDF and anything else in the rightmost column).
The PHP script does a pretty good job of auto-determining the document type, but there are cases where it gets it wrong. If this happens, add the file type – between curly braces – immediately after the URL on the version line:
```
en:http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_60_sqlref{html}
```
Once everything works fine, commit the updated category file to CVS. If you've checked out the Firebird web module from SourceForge, you'll find the category files (and more) in the folder web/website/doc. Use your SF user name and password to check out, otherwise you won't be able to commit your changes. Working with CVS is described in the Firebird Docbuilding Howto.

If you have translated an existing document into a new language, or added a new document type for it

Consult the Documentation Index to see which category the document belongs to. (Categories are indicated with orange headers.)
Connect to the server, cd to /srv/www/htdocs/doc and look at the files starting with Cat_. Open the one that corresponds to the category.
Read the instructions at the top of the file.
Find the section for the document in question and add the version line(s) for your additions, e.g.:
```
Firebird Uninstallation Howto
en:/manual/fb-uninstall.html
en:/pdfmanual/Firebird-Uninstall.pdf
fr:/manual/fr/fb-uninstall-fr.html
fr:/pdfmanual/fr/Deinstaller-Firebird.pdf
```
The order of the version lines within a section is irrelevant, but the title must stay on top.
Steps 5, 6, and 7 are the same as for new documents.