[Firebird-docs] Changes to docset structure

[Paul V. <pa...@vi...>]

Hi all,

The first docs from the manual module will soon be published (in HTML)
on the project website. To make them look as good as possible, I've
prepared some changes to the docset structure and the stylesheets.
None of the changes have been committed yet. I'll list them here;
please respond if you have any objections, or ideas for further
enhancements:

- Until now the auto-generated HTML file names look like this:
  bk01ch01.html, bk02ch01s08.html, etc. Very uninformative, but for
  online browsing it's not disastrous. It IS disastrous however when
  the docs are committed - with these names - to the 'web' CVS module.
  For as we maintain the docs and add new ones, the order may be
  changed, sections inserted etc... this will cause lots of files to
  get different names, their previous names now being assigned to other
  files. That is *very* CVS-unfriendly. It screws up diffing, annotating,
  viewing file histories, and it also eats up more space on the server.

  Solution: changed a certain param in firebirddocs.xsl so the files
  take their names from the ids of the chapters or sections they
  contain. These ids will stay the same for a long time, often forever.
  A additional advantage is that as a human being, you can now also
  see what a file is about: migration-mssql-intro.html, docwritehowto-
  docbook-authoring-tools.html, ibfbcoex-running-ib-fb-together.html...

- Marcelo Lopez Ruiz' Migration Guide was inserted as a <book> with
  only one <chapter> which in turn had many <section>s. This looked
  silly, particularly in the TOC, so I merged the <book> and <chapter>
  layers into one <article> layer.
  I also changed the nested <section> tags to <sect1>, <sect2> tags to
  give the CSS finetuning entries a better grip on it.

- I gave the <set> and the <book>s ids, and gave the <set> a <title>
  ("Firebird Documentation Set").

- Commented out the Preface from the build, because half of the links
  it contains are broken by now, and the information as such (how to
  set up CVS - how to produce a DocBook file) can now be found in the
  more complete Docbuilding and Docwriting Howtos. Furthermore I think
  this information does not belong in a user doc - it's only for
  docwriters.

- Also commented out the Firebird intro. This document consists of two
  very short sections; together, they contain very little info, and
  part of it is not suited for normal users. The other part could
  serve as a basis for a nice introduction to Firebird though.

  Note: both the Preface and the Intro are still in our manual tree of
  course! We can pick them up any time we want. The commenting-out
  only means that they will not be included in the HTML version *now*.

- Moved Marcelo's Migration Guide (see above) into the Firebird
  Database Documentation book. Added a new doc: "Coexistence of
  Firebird and InterBase" to that same book.

- Changed some other (mostly cosmetical) things in the stylesheets.


I'll put up the complete HTML version on a temp location in an hour or
so, so everybody can see what's in there and how it's going to look.
Will post the URL here.


Greetings,
Paul Vinkenoog