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
|
