Re: [docbook-apps] How do you manage your catalogs ?

[Stefan Hinz <stefan.hinz@oracle.com>]

Hi Richard,

> I'm not sure it would work for us.  We produce software and write our
> own documentation.  And there aren't many of us.
>
> What my colleagues are used to is ediiting in Word and producing PDF
> straight from it using a third-party pseudo-printer (BullZip) (*).  Some
> have started producing CHM instead, based on hand-edited HTML (ie edited
> in FrontPage or Expression Web).  We've been told that neither format is
> suitable for every one of our customers so I'd like to find a way of
> generating multiple formats - hence trying DocBook.
>
> So from this starting point I think we need a system where everyone can
> generate any output themselves.

The easiest thing to do would be an editor as XMLMind's XXE (as Stefan 
Seefeld pointed out), or Oxygen XML Editor which my department is using. 
Creating common formats like HTML, XHTML, PDF, and EPUB is 
pre-configured in Oxygen, so it's just a matter of a few clicks to 
produce those formats.

> At the moment some of the software and documents are produced by a
> manual build by an individual developer, and others are produced by an
> automated build.

That's actually how we are doing things in my department. We've set up a 
make-based system that works the exact same way on the central build 
server and when run locally; for example (for a document named book.xml):

* 'make book.valid': runs xmllint and other tools to validate book.xml
* 'make book.html'
* 'make book.pdf'
* 'make book.epub'
* etc.

The idea is to have an easy-to-remember set of commands that work both 
locally and "centrally", and a system that can be set up fairly quickly. 
More information can be found here: 
http://dev.mysql.com/doc/mysqldoc-guide/en/index.html (and the complete 
tool set is here: http://downloads.mysql.com/docs/mysqldoc-toolset.tar.gz).

HTH.

--
Cheers,

Stefan Hinz <stefan.hinz@oracle.com>, MySQL Documentation Manager

Phone: +49-30-82702940, Fax: +49-30-82702941, http://dev.mysql.com/doc

ORACLE Deutschland B.V.&  Co. KG
Registered Office: Riesstr. 25, 80992 Muenchen, Germany
Commercial Register: Local Court Of Munich, HRA 95603
Managing Director: Jürgen Kunz

General Partner: ORACLE Deutschland Verwaltung B.V.
Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Register Of Chamber Of Commerce: Midden-Niederlande, No. 30143697
Managing Directors: Alexander van der Ven, Astrid Kepper, Val Maher