Slashdot Mirror
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?"
Is there some reason why Docbook is insuffient? More info at www.docbook.org.
-molo
Using your sig line to advertise for friends is lame.
I personally would love to find a good DTD for the humanities, but haven't yet found it.
"He who would learn astronomy, and other recondite arts, let him go elsewhere. " -- John Calvin, commenting on Genesis 1
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.
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.
--
Don't like it? Respond with words, not karma.
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.
http://www.google.com/profiles/malachid
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).
- I don't need to go outside, my CRT tan'll do me just fine.
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:
/*Fred says this needed to be here*/
foo=bar*.734
I want to delete my account but Slashdot doesn't allow it.
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).
Software sucks. Open Source sucks less.
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.
Beta is broken and the link to classic doesn't work. Stop wasting our time or there won't be anybody left here.
One thing I haven't seen much of is an XML editor which does real-time validation of the document against a DTD or XML Schema. The ones I've seen do only XML syntax (ie. well-forming) validation in real time, and syntax highlighting as a benefic side-effect. But you have to start the validation against DTD/Schema by hand (ie. push a button) and the feedback is in many cases raw output from the validator presented in a separate pane or window. What I'd like is the highlighting to give me useful feedback the split second I stray off of the DTD/Schema, as I type, with the additional more verbose messages in a separate pane.
Another issue I have with XML editors is their take on suggesting completion alternatives for the element or attribute currently under the cursor. Of course, most give you everything the DTD or Schema for the document has to offer. However, I'd like some kind of "most likely to be used" mode I can switch on/off and which will reduce the available completion set to the things that are most likely to be used for that particular document and position.
i ate crayons when i was a kid and now i have two braincells and the blue ones taste nicer
I am a DocBook newbie and yes, despite the fact I am an old timer going back to nroff and VMS runoff days, I have to admit DocBook ramp-up is significant. I found that the XXE editor from xmlmind.com to be quite helpful as it is DocBook DTD aware and also presents the edit window through a CSS - fooling many newbies to think that it is a word processor. I use OpenOffice as well but found the DocBook support in it rather lacking. Will check out the Morphon site - thanks...
The company I'm working for are currently working on a "business narrative markup language" which is intended to be an overly simple markup for writing business documentation. I think it's going fairly well, though without a trial in the real world it's hard to say.
The main problem we found with XHTML were a complete lack of useful structure (e.g. in XHTML2 you can have plain text inside a section, or a paragraph inside a section with plain text inside the paragraph, or <l> elements inside the paragraph with plain text inside the paragraph. Three different ways to mark up exactly the same thing. If you don't know why that is bad, try to write an XPath which selects the first line of text of the first section in the document.
The main problem we found with DOCBOOK is that there are far too many elements for any mere mortal to learn, and we wanted a secretary to be able to understand our language. By contrast, ours achieves most of its structure through nested items, and blocks of text (effectively paragraphs.)
There are also groups in OASIS trying to nail exactly this sort of thing but XHTML2 is being a fairly big pressure, to say the least.
Karma: It's all a bunch of tree-huggin' hippy crap!
A "roll your own" approach works quite well. Assuming you only need a small number of features, you could either just devise a small set of elements to do the job, or you could devise an outer structure and include XHTML or XHTML2 as the content of sections in that structure.
This is the way I'm working on the development weblog I've been rolling. If I need a new element to bring in more semantics, I invent it at the time I need it. Since nobody else needs to use the content, and XSL does all the presentational transformation, this approach works quite well.
Karma: It's all a bunch of tree-huggin' hippy crap!
We use Morphon in our company for DockBooks. The primary draft writers - industrial engineering interns (it's for an industrial engineering application) - had very little problem figuring it out.
Boo Yeah!!!!
-- Stefie