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

10 of 58 comments (clear)

  1. I end up having a lot of the same questions by quinto2000 · · Score: 3, Interesting

    I was looking into doing this for a while with a number of the formatted documents my school needs to deal with. It turned out that the DTD was much more complex than warranted for the kind of stuff we were doing, but of course YMMV.

    --
    Ceci n'est pas un post
    1. Re:I end up having a lot of the same questions by ichimunki · · Score: 3, Interesting

      I was recently looking heavily at DocBook/XML and comparing it to (La)TeX. I found all the tools for docbook completely lacking, and the XML format to be completely unfriendly to actually writing. LaTeX on the other hand, seems to kick ass for writing, since the markup is short, sweet and easy to learn/use. Not to mention that the algorithms used to perform the layout were designed by a damn genius instead of mere mortals. I've now used LaTeX in conjunction with pdflatex and latex2html to use a single set of source docs to generate both a web site and a PDF file (not to mention that you could also crank out postscript or just about anything you might need to do with documentation... TeX was designed so Knuth could write computer books after all).

      DocBook, on the other hand, has a lot of complicated markup-- I mean who enjoys using the PARA tag to open and close each and every paragraph? It would drive me insane. Then, after you finally find an editor that suits your needs, you still have to monkey around trying to convert the documents. I was able to get a DB file into HTML without too much pain, but PDF? Never managed it. I spent too many hours on what essentially would have translated the DB XML into TeX source anyway! Why not just write in TeX and be done with it.

      Finally, there is LyX for LaTeX which looks to be a WYSIaboutWYG editor, although I find it very convenient to just use emacs. I think the only problem I've had so far is getting figures to lay out on within text how I want, whereas TeX is pretty happy shoving them later, so that the body of the text can remain as fluid as possible. You can see the results on my site (where I suppose I ought to include a tarball of the actual LaTeX source files and the simple shell script that drives all the processing).

      --
      I do not have a signature
  2. No Suitable Editors by GOD_ALMIGHTY · · Score: 4, Interesting

    Essentially your choices are Adobe Framemaker (~$800), Lyx (Open Source) and XMLmind (Freeware). There may be some others, but these are the ones I've looked at. These are the ones you can use like a WYSIWYG, but are more WYSIWYM (What you see is what you mean). For more info on WYSIWYM, look at Lyx's site.

    DocBook is a great spec, but the editors suck for the most part. Lyx can't import DocBook in reliably, and your Docbook is stored as a lyx file (latex I think). Lyx's Docbook stuff can be a bear to set up, even on a system like RedHat where most of the software comes installed. I only recommend Lyx to people who have experience with Lyx, to someone who just wants to write docs, it tends to be more trouble than it's worth.

    Framemaker will probably do everything you want and be a godsend with lots of nice features, but you'll pay for it, $800 for Win/Mac and ~$1300 for Unix.

    XMLmind is pretty cool, it does Docbook well but is a little slow, it has a little bit of a learning curve, but is prolly the best Docbook editor I've found for free. It's not Open Source though. It is written in Java, so you might have some speed issues, depending on the platform you run it on. I've been recommending XMLmind to everyone I know that asks about Docbook, it has a tree view of the DOM as well as a WYSIWYM view with stylesheets applied on the fly. It has property editors and a pretty smart insert tool that follows the DTD, only allowing you to insert allowed tags into other tags. It feels like more of a programmer's tool than Framemaker, but it should be fairly easy for most WYSIWYG users to adjust.

    <rant>
    I don't understand why on God's green earth OpenOffice or Abiword or KOffice, or anyone else in the OpenSource world has neglected this area. It's been three years since the LDP went to DocBook, GNOME uses DocBook as their doc format. Why in the hell don't we have decent document writing tools when everyone is always screaming about the lack of documentation in the OpenSource world?

    If we want more docs written, it needs to be easier to write them and shouldn't involve learning all about SGML or XML engines as well as a markup language to do it. DocBook is too big to keep in my head and I shouldn't have to think hard about how to write docs when my focus is the content I want to write for. Organizing technical info on a difficult subject is hard enough, stopping every five minutes to look up a DocBook tag or trying to better understand the structure is a huge barrier to getting the work done.
    </rant>

    But that's just my $.02

    --
    Arrogance is Confidence which lacks integrity. -- me
  3. Re:I try using XML to structure my docs... by Fweeky · · Score: 3, Interesting

    Um, then you tell it, using XPath, or even better; generate the listview using an XSLT like IE and Mozilla.

  4. Your site.. by Fweeky · · Score: 3, Interesting
    http://www.ichimunki.com/: (pretend I have <cite> around that ;)
    ``Deep'' linking discouraged because the page names are dynamic

    Ignoring the utterly braindead ``foo'' quotes, those filenames are ultra lame.

    DocBook lets you specify a section ID which ends up being mapped to a filename when generating HTML; doesn't LaTeX haeve something like that?
    1. Re:Your site.. by ichimunki · · Score: 2, Interesting

      The quotes are an artifact of LaTeX, which I'm sure could be easily removed by tweaking the latex2html script (it may even be an option)... however, as you see them, they are being strictly translated from the correct inputs to get left/right quotes in TeX, which then ensures they look right in printed copy. I'll have to look into it. While it doesn't bother me much, obviously it bugs someone. :)

      And yes, there is an option to have the resulting .html files have better names, but latex2html does not have any provision to prevent name collision-- so I opted out of it in this case (not that I needed to worry about that, so your point is valid and I will change that). LaTeX (like DocBook) has a facility for both regular names for chapters/sections/whatevers and a place to put abbreviated names (for use in places like tables of contents, references, and headers). The filenaming in latex2html does not use this, but rather a set number of words from the title (IIRC).

      In a perfect world, I'd like to see a system that combined the best of Wiki, TeX, and DocBook (I have nothing against XML, I just don't know if I'm in love with DB's DTD yet), so that you could have the pages be fairly interactive for online references (especially useful in a corporate setting), but still generate standalone documents from the entire work. All with complete revision control, of course.

      I settled on what seemed to be the best compromise available so that I could have a single set of source files produce both printed matter and a website. Ultimately the possibilities with XML seem greater (via stylesheets and xsltproc and custom document parsers written in languages like Perl or Ruby), but getting from XML to PostScript or PDF is the part I had problems with. I like to think if I had problems with it, so would others. 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.

      --
      I do not have a signature
  5. Here's a site that does just that by Anonymous Coward · · Score: 1, Interesting

    help.unc.edu, UNC-Chapel Hill's technical support website, uses Docbook (and XML) extensively. The publication framework is Cocoon 2 under Tomcat, but I'm sure if you like Perl you could use Axkit too =)

  6. Re:We did it. by pete-classic · · Score: 3, Interesting

    How about WYSIWYM (What You See Is What You Mean)?

    Try LyX.

    Just click "title" and type the title. Click a button to turn italics on/off, etc.

    See http://bgu.chez.tiscali.fr/doc/db4lyx/ and http://www.lyx.org/help/xml/xml.php

    -Peter

  7. Re:I try using XML to structure my docs... by Enry · · Score: 3, Interesting

    Look at how the Linux Documentation Project handles SGML/XML files. There are ways of handling this a lot better.

  8. What about OpenOffice.org by stonebeat.org · · Score: 3, Interesting

    At one point in time I was very involved in OpenOffice.org. Now I have lost track of the developement. There were some talk to including DocBook DTD in the distribution. Does anyone, if any progress has been made on that?

    --


    Consensus is good, but informed dictatorship is better