DTDs for Internal IT Documents?

Saqib Ali asks: "A DTD (Documentation Type Definition) defines the document structure with a list of legal elements. DocBook DTD is being widely used in creating Linux related documentation. However I am looking for a XML DTD that is more suited to internal IT documentation, and easy to learn and use. Preferably I would like to use a DTD that can be used with OpenOffice. What DTDs are other Slashdot readers using for for internal IT documentation? I have created documentation using DocBook DTD and hosted them on a Apache Cocoon . Cocoon lets me transform the XML to HTML or PDF. I would like to keep the same backend infrastructure (i.e. Cocoon) but try out other DTDs that are suited for IT related documentation. Any ideas?"

Comments

Why not Docbook?

[molo]

Is there some reason why Docbook is insuffient? More info at www.docbook.org.

-molo

Re:Why not Docbook?

[stonebeat.org]

few reasons:
1) I have been using DocBook for few years. So I know it pretty well. However to newbies, DocBook can be overwhelming (I have been there). I know there is also Simplified DocBook, but no good WYSIWYG editors for it either.
2) OpenOffice doesn't have very good support for DocBook. Setting up OpenOffice to support DocBook can be very tricky.
3) Not many good WYSIWYG editors support DocBook DTD. And if they do, it is not that easy to setup.

What I am looking for is a "Open Standard" DTD can be used to create simple documentation, and is well suited for IT related stuff.

Re:Why not Docbook?

[Rheingold]

1. How about Simplified Docbook?
2. Aside from its own document formats, DocBook is the only format OOo supports, AFAIK, so if that's important to you DocBook is the only option.
3. I don't really know of any WYSIWYG editors that support anything else that's XML-based.

In summary, I don't think there's a better solution than DocBook, despite the fact that it does not fulfill all of your requirements.

Re:Why not Docbook?

[nastyphil]

I don't really know of any WYSIWYG editors that support anything else that's XML-based.

How about MS Word 2003?

DTDs are pass

[Markus Registrada]

DTDs are '90s technology.

What you want is a Relax-NG Schema. DTDs only define the barest bones of XML structure. Validating against a schema lets you verify all kinds of things that a DTD can't even express.

(Don't be confused by W3C Schemas. That format stinks.)

Is a schema important for documentation? It depends on how much structure you need, which largely depends on how many uses you have for the documents. My employer actually puts the documentation itself in the schema, and generates manuals from the same text that validates important input files.

Re:DTDs are pass

[Quantum Jim]

What you want is a Relax-NG Schema. DTDs only define the barest bones of XML structure.

Except that DTDs are also currently the only standard way to expand general entities in a document. I wish there was a standard entity definition language independent of validation languages such as RELAX NG. Tim Bray once had an idea, but that seems to have gone nowhere. :-( XSLT could be used to do it, but transformations of that nature are slow and clunky when compared with entities. XML 2.0 needs a new doctype declaration mechanism. The SGML-inherited one is too limited!

Re:DTDs are pass

[Bazzargh]

I think /you/ are completely confused.

It stands for Document Type Definition, and includes all the human-readable specification that describes what all the elements mean as well as the formal, machine-readable part of the specification

Hmm. You mean it has comments? Because a DTD is nothing more than a machine-readable specification, which often (but not always) comes with comments.

If you somehow came to the conclusion that xml schemas (in general) are not meant to be human readable, take a look at the compact syntax for RNG.

Norm Walsh (ie Mr DocBook) is already making progress replacing the DTD infrastructure of DocBook with RNG. And guess what, he uses an editor (nXML-mode for GNU Emacs) that supports RNG!

I guess he must wear a blindfold? Or maybe you should take a read of James Clark's paper on the design of Relax NG?

Re:DTDs are pass

[Mr. Piddle]

What you want is a Relax-NG Schema. DTDs only define the barest bones of XML structure. Validating against a schema lets you verify all kinds of things that a DTD can't even express.

(Don't be confused by W3C Schemas. That format stinks.)

This is why XML still sucks. The technology is volatile, even down to the schema format!

So, even after several years of not knowing what to focus on to learn how to use XML effectively, I still wouldn't know what to focus on to learn how to use XML effectively. Standard interchange my ass.

Skip XML for source.

[FFFish]

Use ReST (ReStructured Text) and DocUtils. DocUtils outputs perfectly nice XML (ignore the HTML, LaTeX, and other options). It's then easy enough to use XSL:FO and FOP/XEP to transform the XML to PDF.

Been using it for a year, and I'm absolutely flippin' delighted with it. Structured documentation that's both open-standard and imminently readable, yet delivers great PDFs.

DTD? No, I use XSDs.

[malachid69]

I don't use DTDs, but I do use XSDs for all of my document formats. There is a good link to learn the basics here.

I usually use XSD with JAXB (Java XML Bindings) because it provides me with an Object-Oriented approach to reading/writing that specific format. There are also a couple projects to do that for C++ (Rogue Wave). Personally, I *love* XML Data Binding, because I no longer have to deal with DOM or SAX.

Re:DTD? No, I use XSDs.

[malachid69]

I think the thousands of acronyms that came along with XML has ruined a whole generation of computer science students.

Would you rather I had said this:

I don't use Document Type Definitions, but I do use Extensible Markup Language Schema Definitions for all of my document formats. There is a good link to learn the basics here.

I usually use Extensible Markup Language Schema Definitions with Java Advanced Programmer Interface for Extensible Markup Language Binding because it provides me with an Object-Oriented approach to reading/writing that specific format. There are also a couple projects to do that for C++ (Rogue Wave). Personally, I *love* Extensible Markup Language Data Binding, because I no longer have to deal with Document Object Model or Simple Advanced Programmer Interface for Extensible Markup Language.

Realistically, these acronymns are the only thing that make our posts even readable/understandable.

It's always a compromise

[ttfkam]

If you choose to make your own XML document schema, you lose out on the preprepared stylesheets and converters. On the other hand, a schema made for the task at hand is usually easier to use and understand.

As a compromise, you might to check out the progress on XHTML 2.0. It has a syntax not too far removed from the HTML we've all seen before, but 2.0 is closer to the DocBook model of semantics rather than presentation. It is also more likely to be supported by 3rd party clients in the future. (There is already an XHTML 2.0 renderer available for Mozilla.)

Whatever you do, make sure the markup relates to meaning and NOT how it looks. Looks change, but if you don't take care to the meaning/semantics from the beginning, it is prohibitively difficult to put in in later. For example, it's easy to make all annotations and citations red. It's not so cut and dried to change all red text to annotations (when citations or emphasized text may be formatted in red).

Why, O Why?

[Gothmolly]

Is PDF too simple? Too cross platform? Too non-needing-its-own-application-infrastructure? It sounds like you have too much time on your hands. Concentrate on getting your tech people to document things, take whatever they'll produce, as long as it's better than:

foo=bar*.734 /*Fred says this needed to be here*/

Re:Why, O Why?

[stonebeat.org]

Structure Documents. Structure Documents has it is own benefits:
# "Write Once, Publish Anywhere" - You have only to prepare single documents; you can either use them as they are with stylesheets or convert them later to different physical media and formats, including plain text, XHTML and PDF.
# Since your documents are in non-proprietary text format, you can edit them with any text editor, and assure their continuity and cross-platform compatibilty.
# The physical layout of documents is separated from the content.
# Retrieving specific information is very esay from structured document.

Re: Docbook WYSIWYG

[booch]

Morphon is a good WYSIWYG editor for DocBook and other XML dialects. It comes with DocBook stylesheets built in. Morphon is now free (as in beer).

DTDs for the humanities

[SgtChaireBourne]

Which DTDs have you looked at already and what do you plan to use them for?

Just off the top of my head, I recall TEI and TEI-lite being in wide spread use. There are quite a few subsets of both. In general it's often easier to strip an existing DTD down to what you need than to try to make a new one from scratch.

Docbook, as others have mentioned, is good for simple documents, or ISO-12083 for more complex ones are additional options.

Re:Issues with today's XML editors

[utopyr]

Have you tried the XML plug-ins with jEdit? Validate as you go. Also, Eclipse, with XMLBuddy.

I'm in daily debt to the folks who wrote these.