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

[Johan Persson <johanp@aditus.nu>]

Hi,

From your text it is a bit difficult to judge how much of the DocBook writing/transformation concepts you are familiar width. your questions seems to imply some mild confusion on how things fit together (but on the other had you mention programming experience with XML? - so I don't quite understand what level you are coming from).

This makes it difficult to give good advise. it is also impossible to in a short mail like this give a complete tutorial on DocBook installation, process and example transformation.

Unfortunately as with anything powerful as DocBook, and the process to work with it, the learning curve is rather steep in the beginning since there will be many unfamiliar concepts.

If your company have little experience in DocBook, XML, XSLT, XSLT-FO, XPath, XML Schemas etc. it can be quite a challenge to get to grip with all parts. So doing a manual installation by downloading the XSLT stylesheets etc is definitely not going to be easy for you since you need several tools that interact and I would not recommend this. Since you seem to be a solid company the best way for you is most likely to get hold of some person with knowledge to help get you started. This will save you time in the long run.

If you want to do it on your own read on.

First you seem to be confused by all the URL with references to various XML documents. In a correctly installed system you will have something called an XML catalog. This is basically a map from URLs to a local copy of that specific document referenced to by the URL. The reason to use what looks like an external URL in documents is that in this way the files are portable and all system can just adjust this mapping file to match the local setup. Getting the external references is also possible but will of course take extra time.

There are a number of tutorials on DocBook on the Web but most assume you already have a working DocBook system installed.

I assume you are on a Windows system and in that case you are best of getting one of the authoring tools (say Oxygen or XML Mind) available. If you are Unix based then chances are high that you can install all tools necessary from your package manager. (From a personal view I find that Unix based system are easier since I usually build my document from build scripts - that does all my housekeeping)

One of the authoring tools will get you setup right away and you can start writing DocBook documents and do a basic transformation into, say PDF or HTML right away. However the look and feel of the resulting document (with default styling) is most likely not what you want in your end products. The default styling, while it works, is basic and you will need to customize that to fit your company graphic profile.

Doing this customization can be quite a challenging task. Customizing the printed output will require basic-to-medium knowledge of  XSLT, XSL-FO as well as XPath and how to fit in a customization layer in your transformation process. To customize HTML output will in addition to XSLT knowledge also require knowledge of CSS.

Your company should also decide on which elements from DocBook it will actually use. DocBook all in all probably have well over five hundred elements (I'm guessing - I haven't counted). I can hardly think of any single article or book that needs more than,say 1/10:th of that. So you will need to sit down and think of how your documents are structured with sections, footnotes, sidenotes, program-listsings etc. etc. This will also make the customization easier since you only have to customize those elements.

The best start to gain knowledge on the transformation from DocBook to an output format is to read Bob Stayton's book on DocBook XSL-Stylesheet (and how to customize that). Once you start to have specific questions on how to do a specific customization (and you will!) there are FAQ on the net as well as archives of this mailing list which has covered a lot of questions - and most likely yours already. There are relly few customization questions which hasn't alreay been asked - and answered.

If you can be more specific about things that confuse you I can try to give some more targeted answers.

/Johan

 

On 2012-01-17 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 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
>  =======================================================