The official word on manual format for the GNU project is Texinfo. Technically, Texinfo lives two lives. Its first is that of a suite of TeX macros. The second is that of a source file for the makeinfo compiler. makeinfo produces some nice looking manuals in ps and pdf, but its html has a bit to be desired. You can include your own style sheets, and the HTML is clean. Without the stylesheet, though, the HTML looks like crap. When I use Texinfo, I get the vague feeling that I'm using a castrated animal. It has a single purpose in life, to create technical manuals. Period. I do like the info browser, though I think I'm one of the few. pinfo is a little nicer, but I often get people stating that w3m and lynx are better browsers for documentation, which brings us back to HTML. Bleh. My personal favorite right now it LaTeX. It is a mature documentation suite that can create output to just about anything. Markup is based on keywords that are very much like shorthand. It has a package extension mechanism "\usepackage ..." that lets you include new or useful macros; I routinely include the hyperref package for hyperlinks in PDF documents. The best looking HTML output from TeX, in my honest opinion, is tex2page, found at: http://www.ccs.neu.edu/home/dorai/tex2page/tex2page-doc.html. You need scheme to run it, but it recognizes many TeX formats (viz, plain TeX, LaTeX, and even Texinfo). A great resource for TeX information on the net is found here: http://www.tug.org/interest.html (This looks interesting, "texd, TeX as a daemon with a callable interface, written in Python." Crazy!) In any case, there are a lot of options out there for you, but IMHO LaTeX and TeX are the best if you want something that "Just Works(TM)". I've attached a generic Makefile that I use to build LaTeX documents. I use the vim editor with the default latex syntax markup. I had tried the vim-latexsuite script, but didn't like the keymappings. Besides, it reassigned makeprg to eTeX instead of my Makefile! grr! Things I have not included in this make file are generating and incorporating index, but that should be relatively easy to add. Oh, and before you seriously consider it, do not use reStructuredText for serious documents. Its a nice almost-markup for web pages or wiki pages, but not for documents. I wrote a paper with it once, and had to jump through some hoops to get it to look right. I hope this has been helpful. Chad -- Chad Walstrom <chewie at wookimus.net> http://www.wookimus.net/ assert(expired(knowledge)); /* core dump */ -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: text/x-makefile Size: 703 bytes Desc: Makefile Url : http://mailman.mn-linux.org/pipermail/tclug-list/attachments/20060211/a3acbc92/attachment.bin