Re: [HIG] Mini-Guidelines style

[Maciej Stachowiak <mjs noisehavoc org>]

On 09Aug2001 03:33PM (-0700), Adam Elman wrote:
> 
> [Note: I'm choosing HTML here rather than docbook or anything else 
> because I know how to write HTML, and I think if we stick to the 
> below instructions, it'll be fairly straightforward to transform the 
> HTML into other formats as needed.  I don't want us to get bogged 
> down in learning docbook or anything like that just to write the 
> mini-guidelines; we're on too short a timeline.  'Course, if I'm the 
> only person who doesn't know how to write docbook, then I think I can 
> pick it up pretty quickly.  Again, though, I think it's more 
> important for us to get the content written in a consistent way and 
> we can figure out how to transform it later.)

Hi Adam,

It's important that the completed version of the HIG be published as
DocBook, because that is the standard for GNOME documentation (and the
HIG is at the very least part of the developer docs). There are many
good reasons for this including the ability to produce high-quality
printed output in addition to HTML. This means that before a final
version can be approved, it has to be in DocBook.

So if the initial version is HTML (which might be an OK way to start),
the schedule needs time set aside to convert the document to
DocBook. In general this cannot be done in an automated way, since
HTML is style markup and DocBook is semantic markup, so someone with
DocBook clue will probably have to go over the whole document by hand.

I think it may be easier to start in DocBook or at least convert to
DocBook quite soon once there is some basic content.

I bet you guys can get a lot of help from Dan Mueth on DocBook itself
and on setting upa build system that converts DocBook to HTML in an
automated way.

Regards,

Maciej