Re: [docbook-apps] Customizing and creating a stylesheet for docbook using the XML Mind or Oxygen XML Editor

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

Hi Daniel,

You might want to look at the MySQL documentation system, described on 
this page:

http://dev.mysql.com/doc/index-about.html

The MySQL Guide to Documentation linked from that page provides an 
overview of how we set up and handle DocBook things. There are also 
links for downloading the tool set and the mysqldoc repository which you 
can use to look at and learn from how to set up your own books.

The tool set requires a Unix-like system; in theory, it will run on 
Windows as well, but in practice all our writers use either Linux, Mac 
OS X, or a Linux virtual machine on Windows.

Even if you end up using a different system (say, Ant-based) it's 
probably worth looking at the Guide to Documentation. We've been using 
DocBook for all MySQL documentation since 2004, and we have a lot of 
content to handle.

Most of our writers use Oxygen XML Editor, some use vi or Emacs. Oxygen 
has validation and transformation built in, but it's not trivial to 
automate things, and this one of the reasons why we use our own set of 
tools. The tool set is based on a few select open source components 
(make, XML tools, Perl, FOP) which makes it easy to run the tools on any 
(non-Windows) computer.

Cheers,

Stefan

On 17.01.2012 09:43, daniel.keyes@finaris.de wrote:
> Hello,
>
> currently my company is thinking about transferring its user
> documentation into XML and docbook.
> Since we are an IT company, XML and programming in general is not a
> problem. But: We cannot find and adjust the stylesheet needed to create
> our custom documentation.
> We are currently setting up a prototype for our documentation, following
> the instructions from Walsh´s "DocBook 5: The definitive Guide" and
> working with the XML Mind Editor and a trial version of "OXYGEN Editor".
>
> Basically, we are satisfied with the results and trust in docbooks
> function (since having lots of trouble with Word), but the lacking
> transparency
> <http://shop.oreilly.com/product/9780596805012.do?sortby=publicationDate>makes
> it really hard to come up with a sample documentation/ prototype .Each
> file we open has at least one reference to a website we cannot open and
> dozens of files that don´t exist or are really hard to find. We checked
> the regular docbook.zip from the docbook homepage, but also all files of
> the respective editors. (Is there something as a "default" Docbook
> editor that you would propose?)
>
> Can anyone give me some advice, a link or even a how-to for adjusting
> the docbook stylesheet? Personally, I would love to use docbook for our
> user documentation, simply for the additional features it has compared
> to other text processing program, but only if I can adjust the
> appearance. Especially regarding corporate identity this is absolutely
> necessary.
>
> Thanks and with best regards,
>
>
> D. Keyes
>
>
> =======================================================
> Disclaimer
> The information contained in this e - mail and any attachments
> ( together the "message") is intended for the addressee only and may
> contain confidential and/or privileged information. If you have received
> the message by mistake please delete it and notify the sender and do
> not copy or distribute it or disclose its contents to anyone.
>
> FINARIS Financial Software Partner GmbH
> Sömmerringstr. 23, 60322 Frankfurt/Main, Germany
> Registered at Frankfurt/Main, HRB 52873
>
> Managing Directors:
> Dipl. Inf. Hermann Friebel, Dipl. Ing. Kai Bächle, Dipl. Inf. Werner Märkl
> =======================================================


--
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