This is part of The Pile, a partial archive of some open source mailing lists and newsgroups.
To: Silicon Valley Users Group <svlug@svlug.org> Subject: Re: [svlug] Documentation markup preferences and reasons From: steve@theStarport.org (Stephen R. Savitzky) Date: 31 Dec 2000 10:43:09 -0800 Rick Moen <rick@linuxmafia.com> writes: > >> I'm wary of tools influenced by people who can't distinguish between > >> document markup and page layout. > So, there is much about the DocBook informational sites that suggests > that the brain-dead WYSIWYG mindset described runs rampant, there. I'd > have to go back and re-read them to cite specific examples, but I got a > dull ache in the back of my head just browsing them. > > And TeX definitely has none of that conceptual blindness about it. None > at all. You appear to have this almost precisely backwards. DocBook, from what I've seen of it, seems to be almost entirely semantic. It's likely that the _descriptions_ of DocBook have been written for WYSIWYG users, but the actual rendering of DocBook tags is done through the SGML stylesheet engine DSSSL, so how particular tags end up looking is entirely under the control of the stylesheet writer. TeX, on the other hand, is very nearly a pure layout language. It's the macro package on the front end that provides semantic layout. LaTeX is the most common; it's _almost_ pure semantics, but lets you drop down into raw TeX if you need to tweak something. TeXinfo is another. TeX also makes a great backend for typesetting SGML (or anything else, for that matter); both the DocBook toolset and ArborText's semi-WYSIWYG editor use it as a typesetting engine. My personal recommendations would be to use LaTeX for anything that is _only_ going to be rendered on paper, and DocBook or some other SGML variant for anything that needs to go on both paper and web pages. The semantic subset of HTML, with the addition of a macro preprocessor that expands user-defined tags, makes a good markup language for web pages. For _code_ documentation, I suggest extracting documentation from comments (JavaDoc and POD do this, in different ways, and are broken in different ways as well). The general idea is to use comments for commentary and derive the boilerplate (like function declarations) from the actual declarations. By the way, although XML is indeed merely a framework on which to hang markup languages, both DocBook and HTML can be "XML-ized" almost trivially. This gets you the best of both worlds, since there are a lot of tools around for parsing and processing XML. You can also take advantage of these tools by building your own parser for _any_ syntax and make it look like XML to the back-end. In the end, XML is nothing but a simple and standardized text representation for parse trees. ===