Re: What's the best plain Documentation format?
by Abigail-II (Bishop) on May 26, 2003 at 22:15 UTC
|
For writing documentation, I would only consider three formats: plain
text, LaTeX, and POD.
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
| [reply] |
|
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
| [reply] |
|
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.
| [reply] |
|
| [reply] |
|
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
| [reply] |
|
| [reply] |
Re: What's the best plain Documentation format?
by adrianh (Chancellor) on May 26, 2003 at 17:16 UTC
|
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.
| [reply] |
Re: What's the best plain Documentation format?
by lachoy (Parson) on May 26, 2003 at 18:18 UTC
|
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
| [reply] |
Re: What's the best plain Documentation format?
by crenz (Priest) on May 26, 2003 at 21:11 UTC
|
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.
| [reply] |
|
| [reply] |
Re: What's the best plain Documentation format?
by jplindstrom (Monsignor) on May 26, 2003 at 19:22 UTC
|
I like the Wiki format a lot. I'm used to MoinMoin, but I'm sure there are dialects that are more expressive or powerful.
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
| [reply] |
|
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
| [reply] |
Re: What's the best plain Documentation format?
by Juerd (Abbot) on May 26, 2003 at 20:37 UTC
|
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' }
| [reply] |
Re: What's the best plain Documentation format?
by gjb (Vicar) on May 27, 2003 at 14:10 UTC
|
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-
| [reply] |
Re: What's the best plain Documentation format?
by John M. Dlugosz (Monsignor) on May 28, 2003 at 20:03 UTC
|
| [reply] |