|
|
|
| Perl-Sensitive Sunglasses | |
| PerlMonks |
Re: What's the best plain Documentation format?by Abigail-II (Bishop) |
| on May 26, 2003 at 22:15 UTC ( [id://260904]=note: print w/replies, xml ) | Need Help?? |
|
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
In Section
Meditations
|
|
||||||||||||||||||||||||||||||||||