docbook-apps

  • 1.  Docbook for industrial usage

    Posted 09-07-2010 09:45
    Hi, yesterday I talked with Camille on IRC about getting docbook used more
    in industry. I am searching for companies that already use it and that could
    give a good example about what they do with docbook and why they use it. And
    I also got one first contact I am going to write to.

    The reason is: I am originally a translator and did quite some manuals. I am
    just getting back into doing things (after a longer family pause = kids ;-)
    and noted that in almost 8 years nothing has changed: manuals are still
    written with wordprocessors, images are still modified applying texboxes.
    Formats during translation get lost and require a lot of post-editing. All
    this does not happen when the translation is, for example, carried out in
    docbook format. Besides just the layout questions there are also some more
    which are related terminology consistance and the overall quality of a
    manual.

    I hope that by getting together some real good usage examples in industry
    and writing an article about why to use docbook and not a word processor
    (getting this then to companies) we can at least make some more people aware
    of docbook. It would help all of us to do better jobs.

    One side I never did myself, but would like to try out on my own is to
    convert a docbook file to pdf - all I found on the web seems to be rather
    old and from before docbook 5 - is there any new documentation on this? You
    know one thing is having just read it's possible and another is having it
    done at least once. (I am on OpenSuse btw.)

    Thanks for any help :-)

    Cheers, Bina



  • 2.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-07-2010 10:26
    On Tue, 7 Sep 2010 11:45:26 +0200
    Sabine Cretella


  • 3.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-07-2010 11:29
    I Sabrine,

    I routinely localize/translate O'Reilly manuals for the italian market
    and to other xml consultancy work for publishers. In the last couple
    of year O'Really has changed his workflow from FrameMaker to Docbook
    4.5 to go multi-output (print/pdfs/epub+mobi/html) in a standard
    compliant way.

    An industrial strength (assuming having someone competent in XSLT/FO)
    toolchain is:

    DB version: 4.5
    editing: Oxygen
    XSLT: customization layers of stock DB XSLT 1.75.2
    FO engine: Antenna House (FOP is not yet ready for industrial quality
    print production)

    As usual, the monkey wrench in the above toolchain is the authoring
    phase: if you need to use Word, _very_ strict styling and macro/xslt
    machinery is necessary for going from Word to DB.

    In the future I expect more adoption of DB5, but for the time being it
    is quite difficult to migrate all the existing XSLT customization
    layers (and as the old saying goes: if something works, do not fix
    it!).

    I have the impression most DB adoption is in the technical writing
    world (where some background in SGML/Frame exists). In other
    publishing sectors (e.g. novels and the like), DB workflows would be
    extremely useful (today everyone wants print pdf+epub), but there
    exist strong resistances due to old (bad) habits from DTP and the real
    world issues of xml first/early toolchains.

    This is my experience from the real world.

    I am convinced that in the last 8 years a lot indeed has changed!
    Simply non that many publishers yet realized this.

    regards,
    __peppo

    On Tue, Sep 7, 2010 at 11:45 AM, Sabine Cretella


  • 4.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-07-2010 14:08
    +--
    | Hi, yesterday I talked with Camille on IRC about getting
    | docbook used more in industry. I am searching for companies
    | that already use it and that could give a good example about
    | what they do with docbook and why they use it. And I also got
    | one first contact I am going to write to.
    +--

    Not exactly industry, but all our college's computer center
    publications are done in DocBook 4.3 (yes, yes, I know, I'll move
    to 5.0 if I ever finish migrating all our old HTML to our new
    Pylons site).

    http://www.nmt.edu/tcc/help/pubs/index/

    I currently maintain several hundred DocBook documents. DocBook
    is also my preferred framework for literate programming:

    http://www.nmt.edu/~shipman/soft/litprog/

    When I start a new coding project, the first thing I do is set up
    the directory for DocBook and write up the requirements. Next, I
    flesh out the specification. Next step is to write up the design
    and include diagrams and tables for such design artifacts as
    entity-relationship diagrams and schema pictures. Then the code
    goes right in the same document so it is single-sourced there.

    Here's our peer-reviewed journal article on this subject:

    Stavely, Allan, Lynda Walsh, and John Shipman.
    Lightweight literate programming: a documentation
    practice. Technical Communication 55(1), Feb. 2008.

    I love DocBook and wish to thank all the many people who built it
    and continue to maintain and enhance it. A marvelous tool and
    the pivot around which all my documentation and software design
    practice rotate.

    Best regards,
    John Shipman (john@nmt.edu), Applications Specialist, NM Tech Computer Center,
    Speare 119, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john
    ``Let's go outside and commiserate with nature.'' --Dave Farber



  • 5.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-07-2010 23:25
    On 09/07/2010 07:45 PM, Sabine Cretella wrote:
    > Hi, yesterday I talked with Camille on IRC about getting docbook used more
    > in industry. I am searching for companies that already use it and that could
    > give a good example about what they do with docbook and why they use it. And
    > I also got one first contact I am going to write to.

    In Red Hat and the Fedora Project, we produce all of our documentation
    in Docbook:

    http://docs.redhat.com

    http://docs.fedoraproject.org

    We transform the XML into single-page HTML, multi-page HTML, PDF, and
    EPUB using Publican, a tool developed in-house and released as free,
    open-source software: http://docs.redhat.com/docs/en-US/Site_Tech.html

    Red Hat manuals are published in those four formats in 22 languages, and
    the Fedora project publishes a smaller selection of manuals in anywhere
    up to 42 languages. Authoring in DocBook as opposed to a word processor
    allows us to maintain a single source for each document, regardless of
    how many different formats and languages we publish.

    One of my colleagues, Ryan Lerch, explained the "why" in a short comic:
    http://fossdocs.files.wordpress.com/2010/03/what_is_publican.png

    Although it's Publican-centric, the reasoning applies to DocBook more
    generally, regardless of the tool you use.

    > One side I never did myself, but would like to try out on my own is to
    > convert a docbook file to pdf - all I found on the web seems to be rather
    > old and from before docbook 5 - is there any new documentation on this? You
    > know one thing is having just read it's possible and another is having it
    > done at least once. (I am on OpenSuse btw.

    In Publican, it would be (for example):

    publican build --formats=pdf --languages=en-US

    You can find the spec file and source tarball here (the current version
    is 2.1): https://fedorahosted.org/releases/p/u/publican/

    The spec file is designed for Fedora, and would need some adaptation for
    openSUSE to account for different packaging for dependencies. If you get
    Publican working on openSUSE, we'd be happy to add installation
    instructions to our documentation.

    Cheers
    Rudi




  • 6.  RE: [docbook-apps] Docbook for industrial usage

    Posted 09-08-2010 00:02
    This thread makes me wonder if we should all update and add details to http://wiki.docbook.org/topic/WhoUsesDocBook

    David


    Original Message


  • 7.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-08-2010 05:06
    Sabine Cretella wrote:
    > Hi, yesterday I talked with Camille on IRC about getting docbook used more
    > in industry. I am searching for companies that already use it and that could
    > give a good example about what they do with docbook and why they use it. And
    > I also got one first contact I am going to write to.

    There are many companies using DocBook ranging from large corporations
    like HP, Sun, going through large open-source project (e.g. PHP uses
    DocBook for documentation) and finishing and smaller companies and
    individual projects.

    > One side I never did myself, but would like to try out on my own is to
    > convert a docbook file to pdf - all I found on the web seems to be rather
    > old and from before docbook 5 - is there any new documentation on this? You
    > know one thing is having just read it's possible and another is having it
    > done at least once. (I am on OpenSuse btw.)

    Processing tools are somewhat agnostic to DocBook version. DocBook XSL
    stylesheets produce quite raw PDF by default, but it is very easy to
    customize them. E.g. the following PDF was produced with customized
    stylesheets and XEP to match publisher guildelines:

    http://www.kosek.cz/knihy/phpxml/php5xml-ukazka.pdf

    Actually OpenSuse internally also uses DocBook for documentation, but I
    think that they use TeX for doing final typesetting of PDF version.

    Jirka

    --
    ------------------------------------------------------------------
    Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz
    ------------------------------------------------------------------
    Professional XML consulting and training services
    DocBook customization, custom XSLT/XSL-FO document processing
    ------------------------------------------------------------------
    OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
    ------------------------------------------------------------------




  • 8.  Re: Re: [docbook-apps] Docbook for industrial usage

    Posted 09-24-2010 17:15
    Hi.

    Wednesday 08 September 2010

    > [...]
    > Actually OpenSuse internally also uses DocBook for documentation, but I
    > think that they use TeX for doing final typesetting of PDF version.

    The TeX toolchain was long gone. We use a XSL-FO toolchain now. :)


    Tom





  • 9.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-25-2010 02:21
    On 9/24/2010 1:15 PM, Thomas Schraitle wrote:
    >> Actually OpenSuse internally also uses DocBook for documentation, but I
    >> think that they use TeX for doing final typesetting of PDF version.
    >
    > The TeX toolchain was long gone. We use a XSL-FO toolchain now. :)

    I don't know what toolchain that was, but we routinely use dblatex
    http://dblatex.sourceforge.net/
    It produces LaTeX, or better, XeLaTeX output.
    --
    Mike Maxwell
    maxwell@umiacs.umd.edu
    "A library is the best possible imitation, by human beings,
    of a divine mind, where the whole universe is viewed and
    understood at the same time... we have invented libraries
    because we know that we do not have divine powers, but we
    try to do our best to imitate them." --Umberto Eco



  • 10.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-08-2010 06:55
    Hi,

    On 07.09.2010 12:45, Sabine Cretella wrote:
    > Hi, yesterday I talked with Camille on IRC about getting docbook used
    > more in industry. I am searching for companies that already use it and
    > that could give a good example about what they do with docbook and why
    > they use it. And I also got one first contact I am going to write to.
    >
    > The reason is: I am originally a translator and did quite some
    > manuals. I am just getting back into doing things (after a longer
    > family pause = kids ;-) and noted that in almost 8 years nothing has
    > changed: manuals are still written with wordprocessors, images are
    > still modified applying texboxes. Formats during translation get lost
    > and require a lot of post-editing. All this does not happen when the
    > translation is, for example, carried out in docbook format. Besides
    > just the layout questions there are also some more which are related
    > terminology consistance and the overall quality of a manual.
    >
    > I hope that by getting together some real good usage examples in
    > industry and writing an article about why to use docbook and not a
    > word processor (getting this then to companies) we can at least make
    > some more people aware of docbook. It would help all of us to do
    > better jobs.

    The gnome desktop uses docbook in api reference manuals [1]. The
    reference is made with a tool called gtk-doc [2]. It extract comments
    from the sources and produces docbook xml. The generated docbook xml is
    xi:included into handwritten docbook xml.

    In the past also user manuals were written in docbook. Those are now
    written in mallard [3].

    Stefan

    [1] http://library.gnome.org/devel/references
    [2] http://www.gtk.org/gtk-doc/
    [3] http://projectmallard.org/

    > One side I never did myself, but would like to try out on my own is to
    > convert a docbook file to pdf - all I found on the web seems to be
    > rather old and from before docbook 5 - is there any new documentation
    > on this? You know one thing is having just read it's possible and
    > another is having it done at least once. (I am on OpenSuse btw.)
    >
    > Thanks for any help :-)
    >
    > Cheers, Bina
    >
    >




  • 11.  Re: [docbook-apps] Docbook for industrial usage

    Posted 09-08-2010 14:33
    FUSE (fusesource.com) does all of its documentation in DocBook 5.

    On 9/8/2010 2:55 AM, Stefan Kost wrote:
    > Hi,
    >
    > On 07.09.2010 12:45, Sabine Cretella wrote:
    >> Hi, yesterday I talked with Camille on IRC about getting docbook used
    >> more in industry. I am searching for companies that already use it and
    >> that could give a good example about what they do with docbook and why
    >> they use it. And I also got one first contact I am going to write to.
    >>
    >> The reason is: I am originally a translator and did quite some
    >> manuals. I am just getting back into doing things (after a longer
    >> family pause = kids ;-) and noted that in almost 8 years nothing has
    >> changed: manuals are still written with wordprocessors, images are
    >> still modified applying texboxes. Formats during translation get lost
    >> and require a lot of post-editing. All this does not happen when the
    >> translation is, for example, carried out in docbook format. Besides
    >> just the layout questions there are also some more which are related
    >> terminology consistance and the overall quality of a manual.
    >>
    >> I hope that by getting together some real good usage examples in
    >> industry and writing an article about why to use docbook and not a
    >> word processor (getting this then to companies) we can at least make
    >> some more people aware of docbook. It would help all of us to do
    >> better jobs.
    > The gnome desktop uses docbook in api reference manuals [1]. The
    > reference is made with a tool called gtk-doc [2]. It extract comments
    > from the sources and produces docbook xml. The generated docbook xml is
    > xi:included into handwritten docbook xml.
    >
    > In the past also user manuals were written in docbook. Those are now
    > written in mallard [3].
    >
    > Stefan
    >
    > [1] http://library.gnome.org/devel/references
    > [2] http://www.gtk.org/gtk-doc/
    > [3] http://projectmallard.org/
    >
    >> One side I never did myself, but would like to try out on my own is to
    >> convert a docbook file to pdf - all I found on the web seems to be
    >> rather old and from before docbook 5 - is there any new documentation
    >> on this? You know one thing is having just read it's possible and
    >> another is having it done at least once. (I am on OpenSuse btw.)
    >>
    >> Thanks for any help :-)
    >>
    >> Cheers, Bina
    >>
    >>
    >
    > ---------------------------------------------------------------------
    > To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
    > For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
    >



Related Content