Plain text has two huge advantages. First, it's simple, you don't need any special tools to read or write it. WYSIWYG even in the simplest text editor, and it causes no problem for the blind (something I care a lot about). Second avantage is that it is nowadays about the only format that's cross platform. I can read plain text documents that were created more than 30 years ago, and I have no doubt that a plain text document created today will be readable 30 years from now. RFC's have been written in plain text since RFC 1, and they will be written in plain text for the foreseeable future. What's good enough for RFC's is certainly good enough for my documentation. Another advantage is that plain text is so "plain", it really lets you focus on the content.

LaTeX is great. It allows you to separate content from presentation by using stylesheets, without prohibiting you from doing complicated stuff. There are lots of free packages available enabling you to create sophisticated documents easily. It's the Perl of documentation languages, but with less ugliness. For documentation in dead tree format, it would be my first choice.

I only use POD for documenting Perl programs, and mainly because it's common to do. When installing stuff with CPAN, documentation gets automatically extracted. But the markup of POD is minimal, it doesn't give that much more than plain text is giving you. The existance of a pod2man, and the non-existance of text2man makes that I still use POD.

Abigail

Lucky girl boy (thanks particle). If I happened to get a (OK, 30 is too much) 10 years old text in Czech I'm sure I'd at least had to go and search for a charset convertor. And if I'd be lucky I would 1) find out what charset is the text in and 2) be able to find a convertor that still knows that charset.

If on the other hand I'd be unlucky the text would already be "converted" from a charset it's not in. I once wasted several days trying to find out why the heck do the accentuated characters come out wrong only to find out the FoxPro ODBC drivers automaticaly "converted" the strings from cp852 to win1250 even though they were in koi8cs or something. And since I was not able to turn the automatic conversion off I had to convert back and then convert correctly. If the data could talk I'm not sure what would it say.

Jenda
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
   -- Rick Osborne

Edit by castaway: Closed small tag in signature

I agree, although it's not quite as bad for German. You can usually guess the characters and search/replace them -- unless some stupid MTA decided to just throw away that 8th bit instead of using something like MIME.

I tend to go UTF-8 for my plaintext docs, and hope it'll be around for a while.

Can you give some tools for Latex, since I don't know much about it?

Graciliano M. P.
"The creativity is the expression of the liberty".

The tools I use are: a plain text editor like vi; latex, to take the latex files and turn them into dvi; xdvi, to display dvi files; dvips to turn dvi files into PostScript; and dvipdf to turn dvi into PDF. Oh, and lp to print the PostScript files.

Abigail

Check out http://www.ctan.org/ for a fairly comprehensive list of software and add-ons. See http://www.latex-project.org/ for some introductory documentation.

AFAIK Perl6 will be extending POD with some more features rather than abandoning it. Some of the Perl6 RFCs may give you some idea of what POD will turn into - but I imagine Larry et al will come up with something more interesting than the sum of the suggestions given so far.

I would seriously consider LaTeX. You can always use a subset and since it's turing complete you can make it do pretty much what you like. Create a custom set of macros to do what you need and no more.

Docbook may be worth looking at. There is also Simplified DocBook if you need something more basic.

Finally, creating a custom XML DTD for your documentation is always an option. However, I find that these rapidly turn into XHTML if you're not careful ;-)

My projects tend to be Perl. So I use POD for the perl code, and Docbook for the non-code docs.

You might also look into Doxygen, which seems to be popular for all sorts of programming languages, particularly for inline parseable comments a la Javadoc.

Chris
M-x auto-bs-mode

One thing you didn't mention about POD is that it is not so hard to convert it to HTML or LaTeX. You can even take the existing pod2html and pod2latex and modify them so that the output looks according to your specs.

I'd go for POD, since it is really easy to manage, and it is easy to output in a way so that everything has a common design.

The best of POD is that you can parse it, in other words, convert to anyformat.

Take a look at this. You gonna like it:
POD-Browser 0.01 released.

Graciliano M. P.
"The creativity is the expression of the liberty".

On the other hand, POD has a lot going for it, expecially when it comes to flexibility and power.

On the third hand, POD is really not that simple to use or clear to read. "=over 4", come on!

/J

I love wikis too, but you really run into a brick wall when it comes to outputting. IME they're really not appropriate if you're planning to print your documentation as a deliverable, or make it part of a larger effort. The flattened nature of wikis (everything linking to everything) also makes it difficult to print, which generally likes a hierarchical format (table of contents, etc.)

Chris
M-x auto-bs-mode

Pod pod pod pod pod pod pod.

Did I mention pod? :)

Okay, it's not the "best" one, but it's extremely easy and it integrates nicely with Perl.

Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

Personally I like Robodoc quite a lot. One can use the same format to document a lot of programming languages (Perl, C/C++, Java obviously) and generate documentation in various formats (HTML, LaTeX, RTF, etc.).

It runs on windows, unix and probably almost every operating system with a C compiler and a shell.

You can find Robodocs home page here. I've used version 3.x quite a lot and was happy with it. The latest version (4.x) should have an even richer feature set.

Just my 2 cents, -gjb-

—John