Re: [Firebird-docs] A how-to on writing Firebird docs?

[Frederic G. M. <fg...@os...>]

As I've been working on the Gbak format and Helen and Ann suggested so, I'll
probably put up a small document on this subject.

How should I do it ? I normally work in OO or Word with custom stylesheets
for my usual artifacts, which seem similar to what you describe for Docbook.
Can I use these and just paste the elements in a docbook skeleton somewhere
? (where ?).


"Paul Vinkenoog" <pa...@vi...> a écrit dans le message de
news:Pin...@s4......
> Hi Mauricio,
[...]
> Because with DocBook XML, you mark up the _structure_ of a text and
> the _meaning_ of its elements: you tag things as chapters, sections,
> subsections, titles, warnings, code snippets, filenames, tips, user
> commands, etc.  etc...  There is no "pollution" by presentational
> markup like in HTML, RTF, Word and other formats.
>
> This results in a very clean and structured source text which is easy
> to maintain, totally platform-independent *and* presentation-
> independent,
>
> From this DocBook XML source, we can then (automatically) build HTML,
> PDF and other output for the readers. Stylesheets (which we can change
> if we want to) control how the structural markup is translated to a
> certain presentation.
>
> > Please, I don't have any specific objections, but all the steps
> > involved in the discussion list seem to make for a lot of trouble
> > for anyone participating in the effort.
>
> I'm afraid you are right :-(
>
> It takes time to get familiar with DocBook XML. Ten months ago I'd
> never heard of it - I learned using it because I wanted to help
> produce Firebird documentation. But now that I know it, I find it even
> easier to write then HTML or Word or whatever, precisely because I
> never have to worry about the layout while I'm writing!
>
> If I write a text in Word, I have to think about if I want section
> titles bold or not - or perhaps in a nice color? - and then I have to
> remember my decision so I don't do it another way ten pages further
> down. And how do I make up a code snippet? And a command line? And a
> warning? And... and... aaaargh!
>
> But even if I *do* make some great rules for all these elements, and I
> *do* apply them consequently throughout the text, the resulting
> document will still suffer from these drawbacks:
>
> - The information itself as to whether something is a code snippet, a
>   warning, or a filename, is not included in the document - because
>   I've already translated that info to makeup: font types, colors etc.
>
> - I only have a Word text now. How to convert to PDF and HTML? Yes, I
>   know: the latest Word versions do that, but you can't really control
>   _how_ they do it.
>
> If I write DocBook XML on the other hand, I rarely have to think about
> which tags to use, because In DocBook you tag a command as <command>,
> a filename as <filename>, a code snippet as <programlisting>, etc...
> Easy!
>
> Also, if everybody produces DocBook XML, we can have one common output
> style (defined by the stylesheets). If we'd all produce HTML it would
> be very difficult (and very frustrating for the docwriters) to have a
> common style.
>
>
> But - having said all that - if someone wants to help and he REALLY
> has a big problem with DocBook XML, he can write in another format
> too. But I hope everybody will at least give DocBook a good try before
> they decide not to use it.
>
>
> I hope I can finish the first - draft - Howto this week; it's about
> how to download the manual module and build the docs. A second Howto
> (hopefully within three weeks) will be on how to write docs in DocBook
> XML format.
>
>
> Greetings!
> Paul Vinkenoog
>
>  - no docs today, my mind has gone away -
>
>
>
> -------------------------------------------------------
> This SF.net email is sponsored by: The SF.net Donation Program.
> Do you like what SourceForge.net is doing for the Open
> Source Community?  Make a contribution, and help us add new
> features and functionality. Click here: http://sourceforge.net/donate/
> _______________________________________________
> Firebird-docs mailing list
> Fir...@li...
> https://lists.sourceforge.net/lists/listinfo/firebird-docs
>