Slashdot Log In
Writing Documentation
from the the-unglamourous-side-of-development dept.
"So far, I like aft,
mostly because it is simple to use, and gives me nice result as HTML.
Unfortunately HTML is not enough, since I also need a very good looking
printable version.
There are alternatives like DocBook,
which I could not get to work and udo
(Page is German, get the translation from the fish) which I have not yet looked
into very closely.
Then of course there is TeX and any number of WYSIWY-won't-G word
processors. I haven't used TeX much, I only tried my luck in writing
a few letters (and found out that it is not suitable for this). I went
through hell when I wrote larger documents with various versions of
MS Word and I am not really a fan of Star Office even though version
5.2 has not yet crashed on me (however 6.0 beta did). KWord, part of
KOffice doesn't seem to be stable enough yet.
I would prefer a simple ASCII only format as the source for being
converted to more complex formats anyway, especially since it could
be easily put into CVS for version management (Anybody tried that
with MS-Word documents? Don't!)
As all these projects show I am not the first one faced with this
problem. I wonder what experiences Slashdot readers have had with
these and other packages?"
Re:PEBKAC (Score:5, Insightful)
If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault.
To answer the article's question. I recommend LaTeX, LyX [lyx.org], latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).
--Bob
TeX gone? Nope. (Score:4, Interesting)
METAFONT is pretty much integrated into TeX if you're using... well, I've only used teTeX and MiKTeX, but there are scripts to autogenerate any fonts that are needed.
And... well, you can't compete with the userbase. It's been a standard for nearly twenty years. The original program is probably as close to bug-free as any large piece of software can possibly be. Did I mention the enormous userbase?
TeX is far from dead. It's Knuth's dream that a TeX file written today will be compilable and readable in a hundred years. Given how entrenched the system is, I think this is quite likely.
-grendel drago
Re:PEBKAC (Score:5)
A car crash isn't the same as an application crash, sorry.
Almost all application crashes are the developers fault. Only a very tiny percentage (< 0.001%) of application crashes are ever the users fault. Some of them may happen because the hardware or OS is buggy. But, that's not the user's fault. If the user goes into the registry and totally mucks it up, it still isn't the users fault. Even under Linux. If the user unplugs cards randomly from a non-hotswap PCI bus, that's the users fault. If the user breaks their system in some physical way, it's their fault. It is not ever acceptable behavior for a program to crash in the absence of a physical problem with the computer.
I switched (Score:5, Insightful)
Also, every time I changed anything at all, Word would move around the pictures and mess everything up - even though I had all the pictures positioned as "absolute." At the end of the publication, any 3 minute change at the beginning of the document took half an hour to fix.
For the next publication, I did everything in Latex. The added bonus there was that format is separate from content, and the format descriptors where already written by IEEE (and by my school for my thesis).
Out of curiousity (Score:5, Insightful)
A point about M$ word (Score:5, Insightful)
try YODL (Score:5, Informative)
http://www.xs4all.nl/~jantien/yodl/ [xs4all.nl]
LYX (Score:5, Informative)
Check out doxygen (Score:5, Informative)
For a real-world example... (Score:5, Informative)
We're using Doxygen to generate HTML and man pages (!) for libstdc++-v3 [gnu.org], the standard C++ library that comes with g++ 3.x. Doxygen can also generate LaTeX, RTF/Word, and some other formats which I don't remember. If you have some additional nifty utilities installed, and tell Doxygen where they are, then Doxygen can automatically use them. Take a look at the inheritence and collaboration graphs on the pages I linked to: normally they're much plainer, and not color-coded. But I had dot(1) installed, which can generate pretty graphs.
Incidentally, LaTeX is much better than TeX when doing letters. There's a set of macros specifically for writing letters, and I use them all the time for, say, business letters.
.I'm told that it's not that hard to write a module for Doxygen to teach it how to create a new output format, if the half-dozen it knows about don't fit your needs.
Documentation is not evil! (Score:5, Insightful)
- Do feature reqs (10%)
- Do design spec / unit spec (30%)
- Do documentation (30%)
- Write code (15%)
- Beta-test / debug (15%)
Notice that design and documentation take up more than half the time on the project. Implementing the code becomes very easy with good, fleshed-out design and documentation.As for solving your problem, I generally write documentation in-code using one style of comments and line-by-line comments using another style. Then forming docs from the code is easy: write a little perl script to extract the block comments, and format as you like.
Re:Documentation is not evil! (Score:5, Insightful)
ABSOLUTELY!
You should design every object and every function (down to what the functions input and return are) before coding everything. You should be able to write comments on the function (on the function, not in. Even having stubs for the function) before it is written. Then, you know EXACTLY what the function needs to do when you code it. You even have a nice reference doc for your teammates (if you use javadoc with java).
I've taken this approach MANY times, and I can't tell you how SIMPLE it is to code with this. Its like a homework assignment "Write a function foo, that takes two integers, adds them, and returns it as a real". The code practically writes itself. And the project manager usually doesn't have any trouble tying all the objects together.
I might as well add that this is a great technique to make open source work well and fast.
Re:Documentation is not evil! (Score:5, Insightful)
Sorry, gotta disagree with that. The place of design docs is not to mandate the details, like the exact function inputs and outputs. The place of the design docs is to paint the big picture, perhaps down to assigning the responsibilities to the major building blocks of your code (principle functions, classes, etc.).
Requirements change. This is a fact of life. No real project I've seen since I was a student had requirements that stayed fixed, or even close to fixed, during a whole development cycle. As a result, your design must change.
Furthermore, your initial design will probably be flawed in many ways you don't anticipate until you start trying to implement it. Unless you're copying an algorithm out of a textbook or a design you've used before, you'll be lucky to be even close to your final design on your first pass. As a result, your design will evolve.
If you attempt to record every little detail in the design docs, two things will happen. First, you will cripple the pace of development, as you spend more time updating paperwork than you spend developing. Secondly, your design docs will rapidly become out of date, and hence useless anyway.
The correct place for comments about the details is in the code. This is where you should record the exact input/output parameters of a function, the behaviour in error cases or the meaning of a little helper function. A combination of descriptive names for things and judicious use of comments will do far more for you than a 500 page printout of last month's code base.
Making your code its own detailed documentation allows for fast prototyping -- often the quickest way to find a good basic design -- and for ready modifications as the design evolves. This leaves design docs free to do what they should: recording the overall design.
Welcome to the 21st century, where the waterfall model dried up.
texinfo (Score:3, Interesting)
through the emacs formatter and use the formatted ascii output.
So, it's old and limited but still my favorite.
Doxygen (Score:3, Informative)
dan.
JavaDoc? (Score:5, Informative)
And I don't think "documenting" is the worst part of programming. Its very sterotypical.
I love design, and document while coding (usually in Java with Javadoc comments). Isn't that the way you are supposed to code?
Especially in a team environment (even more "especially" with Open Source), documentation is critical. Having a good design documented well is how developers should interact with one another.
Also check TogetherSoft. They have software that creates the UML while you code.
I also like Together's identification of titles. A "Developer" is someone that designs, codes, and documents. A "Coder" is someone that codes. Which are you?
Docbook, docbook, docbook. (Score:5, Informative)
Still, I love the format; it's clear, it's precise, and it's very well-suited to documentation.
BTW, I'd like to point out that, if you think documentation is the worst part of programming, you're probably not writing very good documentation. Documentation can be a lot of fun. Think of it as a way to make sure that you won't have to do the maintenance later, because anyone will be able to do it based on your writing.
Re:Docbook, docbook, docbook. (Score:4, Informative)
I finally found Morphon's XML Editor [morphon.com] and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).
Re:Docbook, docbook, docbook. (Score:4, Informative)
It's a bit of a pain to set up, but once it's going, it's great (much like most of Linux, I find
My only complaint about docbook is that it (currently) doesn't do math too well -- I use Walsh's stylesheets, and they don't seem to grok MathML yet -- so I have to stick with LaTeX for some things still. Oh, and its table support doesn't seem to be complete when using the TeX backend, so things may come out in unexpected ways.
LaTeX seemed the simplest way (Score:5, Insightful)
Re:LaTeX seemed the simplest way (Score:5, Informative)
In addition to producing HTML and PDF with latex2html and pdflatex, there are some other features in TeX/LaTeX that appeal to code monkeys like me.
1. Real include files. For example, you can write a mission statement page that gets included in the front of all your documents. When the mission statement changes, you only have to update it in one place, and all your documents reflect the change.
2. \ifthenelse{}{}{} conditionals. This is really handy when combined with the include files above. I have one set of source files that produce three completely different (but related) documents based on a few \def statements. For example, one's for internal use only and one's for wide release, but I only have to fix typos once.
3. Define (\def) statements. I keep version numbers and product names here. PHB says "We just changed the product name from "iCrap" to "eCrap". No problem. It's even easier than search-and-replace.
4. Comments. I comment the source files the my LaTeX documents. Most the time it's just snide remarks, but sometimes I leave useful comments behind.
%% The behavior described in the next paragraph
%% used to be a bug. Now we charge extra for it.
Another Great Benefit of Java (Score:3, Insightful)
I believe there are other systems that implement a Javadoc like utility for other language. Do a google for "Javadoc for C++" for example and plent of links show up.
Wiki (Score:3, Informative)
A fairly simple web application that allows a group to work on documentation together. Since it uses simple formatting rules, it's trivial to learn.
It's the simplest way I know to let a workgroup develop a document.
They have Wiki's that run on Perl, Python, Smalltalk, and PHP so it's easy to find one that you can modify to your heart's content.
Most of the advanced wiki's have all types of bells and whistles (Eg: version control, authenicated users). Some of the wiki's can dump everything from the Wiki database to static HTML or TXT for further processing (which is nice when you actually want to publish).
HTML, LaTeX, LyX., Word... (Score:5, Informative)
A few notes from my experience:
HTML: easy to write, easy to format. HTML TIDY [w3.org] will make everything beautiful for you. HTML actually prints very nicely. I believe most browsers will let you turn off the default page header/footers. I can see, however, that page breaks might be an issue. You'll probably want to use style sheets anyway, and there's a feature in CSS2 that allows for defining page breaks (Paged Media documentation [w3.org]). Also see Converting HTML to other formats [w3.org].
LaTeX: Personally, I'm a big fan of LaTeX. Never tried pure TeX. However, once (if!) I master the CSS2 paged media commands, I'll probably abandon LaTeX. I don't know that one's really any easier than the other; it's just comes down to the simple fact that I know HTML better.
LyX: I found this very non-intuitive and gave up on it quickly. As I recall, the tab key did not work as I expected it, and various things just weren't what I expected them to be.
Word: I know you, the poster, don't want to use Word, so this is for others who must use it. I dislike MS as much as the next /., but I must say that Word is actually a very good product. There are things that annoy me (especially placement of pictures), and there's the macro virus issue, but you probably don't need macros in documentation anyway. As someone else pointed out, there are versioning features in Word. In addition, there are collaboration features that let you track, accept, and reject changes. The style sheets are pretty powerful (most people never use them), and allow you to quickly and easily create tables of contents. And of course, if you're in Windows and have Word already, and assuming it does not constantly crash, it's really the easiest thing to use. Just don't try exporting your document to HTML!
Re:HTML (Score:5, Interesting)
You missed one of the nicest features of using HTML/XML for documention: the fact that with CSS you can get basic content transformation.
What does it mean? It means that you can have rules for online display (that we're most familiar with), different style rules that kick in only when you print (implemented in Mozilla and Opera), and different rules only when you are projecting a presentation (implemented [opera.com] in Opera). This lets you make it accessible on the WWW, yet write your documentation only once without futzing with a nicer "print friendly" copy. If you do a presentation, you can point your audience to the very URL you're using for their later reference. Less chance for confusion.
Word is horrible (Score:5, Insightful)
The problem is that it forces, FORCES, you to deal with presentation issues at all times. When I'm writing, I want to focus on the content. How is the material broken down into major sections, into chapters, into topics? What information needs to be presented before a new topic will make sense? What topics will be treated as reference material, needing easy lookup?
This is hard enough to do with regular interruptions, but with text it's possible. I write an outline, DocBookify it, then write straight text within it while using minimal tags. When I'm happy with the content, I work on presentation (and usually loop between them a few times.)
But Word is so damn helpful that I'm constantly interrupted. I mispelled a wrod or two, gotta fix it NOW. Esp. with the increasingly intrusive "autocorrection" that insists on "fixing" things. (And don't get me started on it's ideas of what a properly formed URL looks like, never mind the RFCs.) There's the issues around the Redmondian English. My grammar isn't perfect, but highly technical material often requires extremely complex sentences to adequately convey the nuances. Green lines are another distraction. Then there's the whole issue of lists, tables, indentations, etc. sucking your attention because you're forced to deal with presentation before you're entirely sure what's going into them. (Two tables or three? What drives columns, what drives rows?)
Is it any wonder I, and many other people, find Word documents to be unusually vacuous? Not every text document in a Jon Postel RFC, of course, but there seems to be a direct correlation between the meat in a document and its original format. Straight text seem to be written to HS or college level, Word documents seem to be written to Jr High level at most. The problem is the polish - Word documents often strike me as first or second drafts, not finished documents. But they sure are pretty.
No, you're an idiot (Score:5, Insightful)
1. Word actually doesn't force you to deal with presentation issues at all times. Are you familiar with outline mode? I usually do my first drafts in outline mode, which allows you to focus entirely on content and structure independent of formatting. Outline mode works with styles to specify formatting globally for a given level in the outline. So if the top level in your outline applies to chapters, you can easily define a chapter heading style that will be automatically applied to all the top-level items. It really works well.
2. It's been said already, but it's worth repeating: Real-time spelling and grammar correction are really easy to turn off. Really easy.
3. Lists & indentations. You should learn how to use styles. This is exactly what they are for. For example, my default template has a "bullet list" style. If I want something to be a bullet list, I apply this style to it. The "tags" aren't visible, but they effectively are there. If I ever decide that a bullet list needs to be indented differently, or have square instead of round bullets, I can make the change once for the style. Once you've set up your default doc template with a reasonable set of styles, you never have to worry about presentation during early stages.
4. I don't understand what you say about tables.
5. "Word documents seem to be written to Jr. High level at most"? What the hell? This is broad generalization at it's worst. I bet more doctoral dissertations are written in Word than anything else. Although I did get a good laugh thinking about what the average grade level of a
Now, I'm not saying Word is the end-all be-all. I'm just saying that you're an idiot because of the 10000 things wrong with it, you've picked issues that are almost univerally untrue, and simply reflect that you haven't learned to use it.
WordPerfect (Score:5, Interesting)
Not to mention WordPerfect's ultimate advantage over Word: Reveal Codes. In Word, any fouled-up formatting can only be fixed by *different* formatting. In WordPerfect, you can *remove* offending code. And it's more customizable, doing things the way you want them done, not the way Microsoft dictates. I could go on about dozens of other advantages, too.
Oh yeah, there are Linux versions available too (albeit using Wine).
Frankly, I'm amazed that any person with technical knowledge and expertise would use Word by choice.
docbook does work, and works well (Score:5, Informative)
and it works fine.
Grab some emacs elisp files from sourceforge
to round out the package and you are good to go
with tag completion and font color locking
in emacs.
Docbook advantages:
* no worries about formatting, just write content
* can generate html, postscript, possibly wml, carved stone tablets, etc.
* can be parsed by freely available xml parsers
to intelligently extract, say, all authors, all section titles. This could be done with raw
perl, but why rewrite an xml parser when so
many already exist?
* documents can be easily stored in an OODB,
using an xml->object marshaller, if you are
into that sort of thing. This allows
any number of documents to be subject to
the full power of the database querying
and indexing.
Latex (tex) is great, and I've used it for 20 years,
but its definitely not the same thing as docbook.
Latex
allows - encourages actually - one to think
about appearance while writing the document.
And you do get great looking output.
But you sacrifice everything that docbook/xml
offers in terms of document parsing for other
purposes.
No question - use LaTeX (Score:5, Insightful)
I went back and forth with all sorts of things: SGML based solutions, a few more "proprietary" utilities, etc. Finally, the latex-to-other-format conversion tools got to be good enough that I could use LaTeX as my primary format.
My most recent documentation is for FUSD [circlemud.org], a Linux framework for user-space devices. The original documentation source is LaTeX. Simply running LaTeX gives you DVI, which you can convert into publication quality Postscript [circlemud.org]. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF [circlemud.org], which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation [circlemud.org]. And, if you really need ASCII, you can get a reasonable rendering by running lynx (in its ASCII-dump mode) over the HTML.
latex2html comes with special LaTeX macros that let you specify hyperlinks inside your document. They are rendered as real hyperlinks in HTML, and footnotes in the printed versions.
obvious joke, sorry (Score:3, Funny)
...In the trial of the
graspee
Use DocBook and document as you code (Score:3, Insightful)
- it helps the planning process immensely by forcing you to really think about what your code is going to be doing, and
- it ensures that the documentation end of the project doesn't get short shrift; once the code is done it's too easy to gloss over the documentation when the next project is breathing down your neck.
DocBook easy to author with... the pain in the neck part is setting up a processing environment with Jade/OpenJade/DSSSL, but it's well worth it. It's also possible to use XSL/XSLT to process DocBook XML, but I don't know how involved the setup is. YMMV.Another vote for LaTeX here (Score:5, Insightful)
Put me down for LaTeX as well, please. In its favour (in this particular context)...
The only downside I can think of is the learning curve. Basic LaTeX use is fine, but for really good output, you're going to want your own class file and/or packages. That's fantastic once you've got it -- all your docs follow a consistent style, and you can make it easy for newbies to learn the tool. Someone has to be pretty sharp to write the class/packages in the first place, though, or you have to be prepared to buy in expert help for a couple of days.
Ten Reasons Why TeX/LaTeX is Better than Word (Score:5, Insightful)
The Best Solution (Score:3, Interesting)
FrameMaker, from Adobe.
Ventura, from Corel.
They both have roughly equivalent functionality. FrameMaker is more accepted in the technical writing world. Ventura has a much, *much* better user interface. Ventura also has an incredible user support group. [corel.ca] The latter two aspects put Ventura in the lead by several lengths, in my opinion. A feature comparison is available here. [coreluser.com] (Its automatic database publishing engine is worth it's weight in gold!)
Ventura is currently in beta-testing for a next-edition release. This edition is going to include XML support, presumably integrated with SoftQuad's products. Given that WordPerfect has had good SGML support for years, I find this to be very, very exciting news.
If you can get over any misgivings over the Corel name, you'll find that Ventura is the ultimate in long-document publishing. It's been around since 1986, and is more feature-complete than Quark, PageMaker, InDesign, and FrameMaker. And of those, FrameMaker is the only application that can be considered to be in the same class. Quark, PageMaker, and InDesign are short-document (ie. magazine advertisement layout) programs, and are absolutely horrible for use in long-document publishing.
FrameMaker and Ventura both fully satisfy your needs. Both can take in XML/SGML. Both produce PDF. Both can create HTML. Both handle documents thousands of pages in length with thousands of images. Both kick the living shit out of MSWord!
You only need to decide which is going to be easier to use, how much you'll want community support, which set of functionality you need, and how much you want to spend.
My money is on Ventura.
(It is, in fact, the only application I've ever used that I look forward to using. Every time I start it, I'm delighted!)
(Ventura users tend to be very enthusiastic about the product. We also tend to wonder why anyone would ever use anything else: we've tried the rest, and figure this is the best.
XML, XSLT and Docbook - a near-perfect solution (Score:5, Interesting)
I've been using XML and Docbook for a while now, and I really, really like it, particularly if you use Docbook as an intermediate format rather than what you actually write your documentation in.
For example, I've got some really nice stuff for building use cases in XML. I created my own DTD for a use case language (which I call UCML) that allows me to define actors, use cases, goals, glossary terms, etc. Use cases consist primarily of a sequence of steps (nestable) with links to actors, terms, other use cases or steps, goals, etc. along with some other tags that define the name, extends relationships with other use cases, termination states and conditions, preconditions, business rules, etc.
I also have some XSLT stylesheets that do a number of nifty things with these UCML documents. One stylesheet transforms UCML to HTML, complete with every imaginable hyperlink, tables of contents etc., and even deduces a bunch of relationships which it documents (and hyperlinks). For example, if a use case mentions an actor or another use case in its steps, the stylesheet adds a section to the HTML description of that use case that documents the fact that this use case uses (in the OO sense) that one, or that this actor participates, and adds similar information to the descriptions of the use case and actor that are referenced. This is just a sample, the stylesheet does a lot more, and produces very *usable* and consistent documentation.
Another stylesheet acts as a sort of garbage collector. Phases (groups of Use Cases intented to implemented together) and Use Cases can be marked as "dead", in which case the UCML->HTML stylesheet will "hide" them (they won't show up in the output). The garbage collector stylesheet takes this a step further and analyzes all actors, glossary terms, entities, goals, etc. and produces a new UCML document that does not include elements unreferenced by a "live" use case. So, I can mark some currently uninteresting use cases as dead, run the garbage collector, run the UCML->HTML stylesheet on the result and get a nicely formatted document that contains only the supporting information required for the included use cases.
HTML is not ideal for printing, though, and this is where Docbook comes in. I have a UCML->Docbook stylesheet that does essentially the same things as the UCML->HTML stylesheet. Then I can convert the Docbook to PDF, Postscript, TeX, etc.
I've also created my own XML languages for component models, architectural decisions documents and others -- it's pretty easy to gin one up whenever I come across another sort of highly structure document I need to write. Plus I have one that I use for simple, less-structured documentation that just provides sections, paragraphs, etc. Mostly I just have whatever->HTML stylesheets for most of these, since they're all intended to be read by developers who are less insistent than end-users on having printable formats.
So, I have nice, text documents that I can use EMACS on, manage in CVS, etc., stylesheets I can fiddle with (when I get sick of writing documentation I can always spend a little time improving the stylesheet code and justify it as "documentation" effort :-) ) and everyone else gets really nice docs from me. The biggest downside is that other people (non-programmer types who are uncomfortable with tagged text) are often uncomfortable with trying to edit my documents (sometimes it's a good thing, as it allows me to retain the "power of the pen", sometimes its bad as even trivial updates must pass through me).
The next steps with UCML are (1) figure out how to establish and maintain XMI-documented use cases and UCML-documented use cases and (2) write a WYSIWYG-like tool for editing them, for the tag-averse.
BTW, if anyone is interested in using the stuff I've described, drop me a line. I've been thinking about putting it up on SourceForge, but don't know if there's enough interest to make it worthwhile.
In praise of DocBook (Score:5, Interesting)
- First off, it's fully compliant SGML or XML, whichever flavour you prefer. DocBook documents are stored as nice plain ASCII which can be processed with any SGML/XML tool you happen to have lying around.
- Output options are virtually unlimited. IIRC, HTML, man, texinfo, plain text, (La)TeX and anything else you care to mention are available as output formats, with XSL providing a way to produce your own custom output.
- The Crunch: Text is marked-up for what it is, not what it's meant to look like, so you needn't know a single thing about formatting while writing content and vice versa. You know the advantages of using CSS instead of hard-coding HTML. Well, they count for DocBook too.
- Nifty features like creating tables of contents from the source and all that sort of thing that you thought only TeX could do.
- I suppose I should mention that it's extensible, hence the XML version.
--PhilRodApache Cocoon... (Score:3, Informative)
Use an Outliner (Score:3, Interesting)
Using an outliner allows great hierarchical structure allowing you to edit quickly.
A good outliner will also output to HTML/XML where you can apply a CSS file for both screen/print mediums. Mozilla, even IE 5+ will ensure your docs appear how you want. Heck, you can change the CSS file and not worry about the presentation at all. Just create a few CSS templates and off you go.
I don't know why you'd make it harder than you have to.
Be a little wary of DocBook (Score:4, Interesting)
What was hard was getting it set up, and getting help out of the DocBook people in the know. (They can be pretty unapproachable sometimes.)
What was also hard was getting print output to work nicely. I was running fine for a while until I upgraded openjade, and then blammo--two-sided print output doesn't work anymore. Openjade simply refused to put the two-side directive in the TeX output, so I did it myself.
And what is it about my document that causes openjade to take 3 minutes to pump out TeX output, when it does the HTML in about 5 seconds?
Why is it that when I put two tables on the same page openjade/jadetex doesn't take that into account and keeps printing text off the bottom of the sheet?
The other place I've looked is Xerces/Xalan/Fop at Apache [apache.org]. I like the Formatted Objects idea, and it seems pretty sound. Also, the whole thing was about 827 times easier to set up than the jade stuff. Unfortunately, the code is alpha and doesn't work very well, sometimes crashing during the render.
"How does ORA do it, then?" I hear you asking. They have custom in-house tools for processing DocBook that have been in development for some time. Word on the street is that they might be releasing them soon.
Conclusion: if you want print output, you might have trouble getting what you want with DocBook at this time. At least when I code TeX it does what I say. (I don't recomment plain TeX for documentation. Maybe LaTeX since it's easier to convert to HTML. And pdf(la)tex produces nice PDFs.)
texinfo or docbook (Score:3, Informative)
Ever thought man pages were limited in that you couldn't automatically go to a referenced manpage? Use info, hit tab until you reach the reference, then hit enter. Walla!
Yes, info has become my all-time favorite. Far beyond the limited HTML markup. Not convinced? I would like to bring to your attention a few posts already made concerning info(1) and the document format texinfo: 2818653 [slashdot.org] and 2819778 [slashdot.org]
I've recently started the chore of changing an existing TeX document into texinfo format. I would have loved to use a converter or a formatter from TeX to texinfo, but alas, such a tool was not available. vim's search and replacement works pretty well. Regardless, since texinfo docs can create TeX, XML, and HTML documents, I believe it's the best of the docformat-to-docformat wars. Additionally, it's a pretty simple markup to use.
Check out info2www [ericsson.se] by Roar Smith [mailto] for a simple way to push out your installed info docs.
Here's the GNU Texinfo [gnu.org] documentation.
The only other acceptable format, IMHO, would be docbook.