Slashdot Mirror
Writing Documentation
"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?"
Just out of curiousity, what are you writing documentation for? I myself would approach the problem according to what kind of software it was, and who the intended audience was.
It will do versioning. See the menu file/versions
the samba guys used to use YODL before they switched to docbook. pretty easy to use, and you can convert to other document languages including html, latex, etc.
http://www.xs4all.nl/~jantien/yodl/
Have you tried LyX? It's a very powerful multiplatform typesetting program. Seems to do everything you want it to do.
Marxism is the opiate of dumbasses
Doxygen lets you mark up your source code pretty easily, and generates decent looking documents. You can use the same markup (and cross-reference facilities) in non-code documents processed at the same time.
- 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.
This post expresses my opinion, not that of my employer. And yes, IAAL.
Call me a throwback or GNU-head but I like texinfo. The stuff you type reflects the structure of your document, it's plain ascii (easy to edit with emacs or your favorite editor), and compiles to online docs, html, or printed docs using TeX. It does make some impositions on your writing style but I find the texinfo formatting commands much easier to deal with than (say) html tags. I use it even when I want plain ascii docs. I just don't put in any "node" commands. Then I run the texinfo doc
through the emacs formatter and use the formatted ascii output.
So, it's old and limited but still my favorite.
It depends on your specific needs. Are you documenting the source or documenting program usage? For the former, doxygen may be useful to you. Generates HTML and LaTeX, amongs other formats.
dan.
Find something similar to Javadoc (unless you code in Java). Rational has a great set of suites to also document projects.
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?
Good quote, too many chars. Seriously, the slashdot 120 char limit sucks!
I'm doing a bunch of documentation right now, and I *LOVE* docbook. I agree, it's a bit of a pain to set up; we started with openjade as a basis, and worked from there.
:)
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.
My blog: http://www.seebs.net/log/ --- My iPhone/iPad app: http://www.seebs.net/seebsfrac/
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, latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).
--Bob
1^2=1; (-1)^2=1; 1^2=(-1)^2; 1=-1; 1=0.
I've been writing documentation for a little while now and LaTeX always seemed the best way to solve the problem. You can make nice pdf and print version. Yes it takes some time to get use to and most WYSIWYG people don't like it but it rocks in CVS.
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.
Try a Wiki.
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).
My father is a blogger.
Uh, wrong.
:)
Sometimes it is the hardware, malicious programs, other programs, or the operating system too.
You're right that it isn't the user's fault, but the blame can fall on any of the developers of any running software or hardware on the system, not just the application's developer.
Or, to sum it up, blame microsoft since they do it all
A few notes from my experience:
HTML: easy to write, easy to format. HTML TIDY 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). Also see Converting HTML to other formats.
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!
Remember WordPerfect? Version 9, SP4, is rock solid stable and does not suffer from Word's inability to handle long documents. (The primary culprit: Word's continuous repagination and reformatting, required by the document structure.) Versioning is supported, and WordPerfect, unlike Word, has the native ability to generate PDF files. Version 10, SP2 does even better, formatting hyperlinks automatically in PDF files, but I won't recommend it yet because there's a nasty interaction bug between it and Mozilla.
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.
TANSTAAFL
We're using the preloaded docbook on RH7.2
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.
I grappled with exactly this problem for years. I wanted something that would give me superb quality Postscript/PDF, good HTML, and at least passable ASCII text. (In 1994, it was still important to distribute ASCII documentation; not everyone had a web browser.)
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, 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. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF, which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation. 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.
I have to disagree. The developer does have the most important part in making something not crash, but you can NEVER take into account what a user can/will do. For example, if a user decides that they want to use MS Word as their file manager, and it crashes, is that the developers fault?
I would edit your statement to say something more along the lines of:
If an application crashes while being used as it was intended, it's the developer's fault.
"I have been charged with writing lots of documents"
/. submitter vs the hacker community the defendant was found guilty of writing documentation. He also asked for several charges of using meaningful variable names be taken into consideration.
...In the trial of the
graspee
- 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.Abandonware? Quite the opposite!
HTMLDOC downloads regularly surpass all of our other products combined, and we are actively developing it to support newer stuff like CSS1/2, XHTML, Unicode text, embedded fonts, etc.
Best of all, of course, is that HTMLDOC is (and always shall be) open-source software, with commercial support for those that need it.
I print, therefore I am.
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.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
My word processor was written by Stanford Professor Donald Knuth. Who wrote yours?
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 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.
Constitutionally Correct
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.
Need a Python, C++, Unix, Linux develop
MS Word is about the worst tool around for writers.
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.
For every complex problem there is an answer that is clear, simple, and wrong. -- H L Mencken
There are currently only two good long-document solutions:
:-) )
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. The latter two aspects put Ventura in the lead by several lengths, in my opinion. A feature comparison is available here. (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.
--
Don't like it? Respond with words, not karma.
We're using Doxygen to generate HTML and man pages (!) for libstdc++-v3, 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.
You cannot apply a technological solution to a sociological problem. (Edwards' Law)
WYSIWYG is also a pain in many ways:
LaTeX does have some disadvantages, however:
Lyx sounds interesting, although I haven't tried it. I'm not sure to what extent it just creates typical WYSIWYG problems while getting rid of typical non-WYSIWYG problems.
An important consideration is that TeX/LaTeX is open source, and there are free-as-in-beer implementations on virtually every platform. If you're trying to exist in the world of open source, you really need to use open-source tools.
Find free books.
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.
Note to ACs: I usually delete AC replies without reading them. If you want to talk to me, log in.
yes, if your application needs (or can) work with a specific hardware which requires a specific configuration, then your application should take responsibility to ensure that environment is present. aborts are bad! they should not be tolerated. an application should not allow a dumb user or dumb hardware to crash it.
StarOffice 6 uses a new file format which amount to a pkzipped archive containing four standard XML documents and in line objects as seperate files.
I've used both Staroffice and Tex extensively to document networks for customers at my workplace. And I think Tex is in zombie mode now - dead, but not quite realizing it.
Tex:
* Attempts to seperates content from presentation
* Can automatically produce some parts of a document based on others
* Is hand editable in plain ASCII
* Exports to many common file formats
It also:
* Uses metafont, a font system that is unlike every other modern Unix application in existence and is designed around the use on non scalable fonts
* Has non-programmer editing tools which still aren't really suitable for end users and don't produce the output intended.
StarOffice 6 contains all the advantages above - content and style can be kept seperate, the text file format is plain ASCII, stylesheets are used, and StarOffice can export to a lot more fileformats than tex can via the use of XSLT and StarOffice's own inbuilt filters.
The GUI editing program also shits all over the Tex tools I've used - a simple Word Processor application with 2 additions:
* The stylist, a style pallette which applies styles to parts of content and allows the editing of those styles
* The Navigator, a floating window which provides a heirarchical view of the document allowing the author to immediately see and edit the structure of the content as well as move to different parts of it.
Hence its pretty easy for a non programmer to produce a real structured document without extensive knowledge of the system. People who write good documentation are often non programmers - they write documentation from an end user POV for their fellow end users, and if the end users aren't programmers, the documentation person doesn't have to be either in my opinion.
Of course, you can always produce and manipulate StarOffice 6 documents from your text editor, shell or other scripts. I'm working on converting our old Tex documentation script to produce SUn XML Writer documents as we speak.
Oh yeah, and no more jumping through hoops deadling with metafont shittiness. Yay.
Its a pity the 6.0 beta crashed on the poster - personally I find its the most stable and fast StarOffice yet, and that 5.2 was flaky, especially with net installs.
I wrote a publication (16 pages, IEEE format) for Word and it was a REAL pain. Word stored the whole document in memory, which actually meant that part of it was cached to hard drive. I work in the Field of Computer Vision, so I necessarily had about 10 megs of images in there. Occasionally, that would be too much for the operating system, and I'd have to wait 15 minutes or so for the memory manager to catch and resolve some thrashing issues.
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).
Mod me down and I will become more powerful than you can possibly imagine!
- 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.
--PhilRodKDE Documentation Team: http://i18n.kde.org/doc
Uh, no.
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
Laws do not persuade just because they threaten. --Seneca
apache cocoon is an awesome publishing tool. I recently created a site that creates a web site and a series of PDF documents from the same source. Your input documents are as simple as you want them to be, because you define it yourself and transform it into HTML or XSL:FO via XSLT.
std::disclaimer<std::legalese> sig=new std::disclaimer; sig->dump(); delete sig;
Use an outliner. There are several out there, the one that springs to my mind immediatley is Omni Outline (www.omnigroup.com).
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.
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. 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.)
I use Word almost every day, and while many of your comments are true for default behavior, you clearly have not attempted to actually learn the program. To take the issues in the order you cite them:
/. post would be...
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.
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 and 2819778
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 by Roar Smith for a simple way to push out your installed info docs.
Here's the GNU Texinfo documentation.
The only other acceptable format, IMHO, would be docbook.
assert(expired(knowledge));