Slashdot Mirror

← Back to Stories (view on slashdot.org)

Using the DocBook DTD for Internal Documents?

Posted by Cliff on from the going-digital dept.

Saqib Ali asks: "These days, most of the Linux Documentation is created using DocBook DTD. I was wondering if it will be useful for a large Enterprise to create Internal IT documents using DocBook DTD. Any success stories where a large enterprise converted all of its internal IT documentation to DocBook, with management's support? Any other things/issues to keep in mind before embarking on such a mission?"

5 of 58 comments (clear)

  1. one open source approach ... by Boiotos · · Score: 4, Informative

    uses Cocoon2 as a web-publication engine. The Norm Walsh xslt sheets are your best general-purpose transformation, but they sometimes choke on Xalan. This Wiki Page should clear up that problem.

  2. Re:No Suitable Editors by Anonymous Coward · · Score: 1, Informative

    You may want to take a look at "Tagless Editor" from www.i4i.com.

  3. Re:I end up having a lot of the same questions by ttfkam · · Score: 4, Informative

    There is also a Simplified DocBook DTD. We used it at my last job. It is a small but useful subset of DocBook that can get you started.

    All Simplified DocBook files are also completely valid DocBook documents. But there are far fewer elements and constructs to keep in your head. It's also geared toward smaller items such as articles instead of complete books. At my company, we made a couple of template documents and then just had people fill in the blanks. People ended up working faster once we got them to stop worrying about formatting and styling (non-trivial).

    Start writing in SD and as the collection of documents grows, you can look into combining them into a cohesive DocBook collection as time permits and your experience level grows.

    --

    - I don't need to go outside, my CRT tan'll do me just fine.
  4. Re:Your site.. by ttfkam · · Score: 3, Informative
    But then I limited myself to Free Software, whereas someone willing to use non-Free software might easily find an off-the-shelf package to get around the PS/PDF hurdle.

    Check out Apache Cocoon and Norman Walsh's DocBook stylesheets at Sourceforge. It sounds very much like what you are looking for both for batch processing of documents (using command-line mode) and for online dynamic presentation. There is even a serializer to PCL5 in case you ever wanted to send directly to HP-compatible printers.
    --

    - I don't need to go outside, my CRT tan'll do me just fine.
  5. Re:Oh for heaven's sake by ttfkam · · Score: 3, Informative
    Yes, this isn't documented well enough. (I'm not being sarcastic -- it actually took a bit of hunting to find this)

    From http://xslt-process.sourceforge.net/docbook.php

    A better solution is to create a local copy of the DocBook DTD files. To do this go to http://www.oasis-open.org/docbook/xml/4.1.2/ and download the ZIP file containing the DocBook DTD. Put it in an accesible place on your file system, for example in /usr/local/share/docbook-4.1.2. Then modify the DOCTYPE of your DocBook documents to be:
    <!DOCTYPE book
    PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "file:/usr/local/share/docbook-4.1.2/docbookx.dtd" >

    I also know that there's a way to specify it as a general resource and to have a catalog that keeps from having to hardcode each file to a path, but I don't remember the syntax or the steps offhand.

    Hope this helps with your laptop problem.
    --

    - I don't need to go outside, my CRT tan'll do me just fine.