Re: HTML documentation system - design and planning

I don't know all the capabilities your site has, but you might want to consider docbook. It is an HTML markup that can be exported to PDF, HTML and PostScript (and more).

Here is a sort of Linux-oriented intro to docbook.

Some editors let you edit text then export the formatted document as docbook, e.g. abiword. LyX has been touted as a multiplatform solution. More often folks convert or write in XML directly, it seems. I'd at least prefer an XML editor if I couldn't use, say, AbiWord.

There is also a book which can be purchased or downloaded.

HTH, --traveler

Comment on Re: HTML documentation system - design and planning

Replies are listed 'Best First'.
Re: Re: HTML documentation system - design and planning by byronellis (Novice) on Sep 08, 2001 at 12:29 UTC
You can also check out AxKit (the site has been down as the author is moving but should be up again soon), an Apache perl_mod module. It's written (obviously) in Perl and provides out-of-the-book support for automatic DocBook rendering to HTML (in a couple of forms). It uses XSLT and XPathScript to do its dirty work (using the XML::LibXML and XML::LibXSLT modules), which is nice since you can actually easily integrate multiple XML markups (you could generate product specific or task specific ones, like todo lists that are much lighter weight than DocBook) by simply assigning different stylesheets and people looking at the output are none the wiser :-) There is also an XML markup aimed at simulating LaTeX (someone else mentioned LaTeX) though its name currently escapes me. I use LaTeX on a pretty regular basis, its fine for things like papers (nothing beats it for mathematical formulae), but it doesn't really have good facilities for web delivered documentation---it was meant for a static print world and it performs that task admirably.	[reply]
Re: Re: HTML documentation system - design and planning by Hanamaki (Chaplain) on Sep 08, 2001 at 20:38 UTC
If you have some time to invest, I would go for DocBook. The html Version of DocBook: The Definitive Guide by Norm Walsh and Leonard Muellner (O'Reilly, 1999) is available for free at O'Reilly's page, for easy browsing, or as a zipped download from docbook.org (html or sgml). Browsing a while through DocBook: The Definitive Guide should give you enough information to decide, wether this kind of encoding is the right stuff for you. Hanamaki	[reply]
Re: Re: HTML documentation system - design and planning by John M. Dlugosz (Monsignor) on Sep 09, 2001 at 09:58 UTC
DocBook is not what I'm looking for. It uses SGML markup, and that's just as "bad", if not moreso, than writing in HTML. I don't see any provisions for generating the master tables and index and such, too. However, I'm wondering if a two-stage approach might work. I can write a simple Perl tool to take an easily-typed markup and convert to formal XML, and that's all it does. I can bang on that to extend when needed, as I need more features. Anything that doesn't fit the mold can be written directly in XML. Then, another tool reads the XML document and produces the set of HTML pages, including the index and stuff. —John	[reply]
Re: Re: Re: HTML documentation system - design and planning by Hanamaki (Chaplain) on Sep 09, 2001 at 18:06 UTC
DocBook is not what I'm looking for. It uses SGML markup... .However, I'm wondering if a two-stage approach might work. I can write a simple Perl tool to take an easily-typed markup and convert to formal XML, and that's all it does. Yes, basically DocBook was sgml stuff. Fortunately since Docbook Version 4 there is also a XML-DTD and a XML subset of Docbook called Simplified DocBook. You could even convert your easily-typed markup to Simple DocBook. I don't want to talk you into some format like DocBook with a rather steep learning curve, but just want to show you an alternative. Hanamaki	[reply]