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