Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer

What's the best plain Documentation format?

by gmpassos (Priest)
on May 26, 2003 at 16:46 UTC ( #260856=perlmeditation: print w/replies, xml ) Need Help??

This is not really a Perl question, but the monastery is good place to ask. ;)

I'm looking for a good and simple format for documentation. Actually is for wxWindows, we are looking for a standart format for the documentation, but it need to be simple and integrated with the API.

The format need to be simple, like POD, to everyone be able to write it fast. And need to handle C/C++ codes, since this is for C++ classes.

Now the wxWindows documentation is based on Latex, that is converted to HTML (and other formats). But the Latex format isn't simple, is hard like HTML (compared to POD). The idea is to also have a format easy to extract information by other programs (or at least be able to convert it easy to a XML base).

I was thinking in POD, but there is better ways?

If I'm not wrong, Perl6 won't use POD. What format Perl6 will use?

I will be glad if some monks list the documentation formats that they know (with some explanation/examples). ;-P

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

  • Comment on What's the best plain Documentation format?

Replies are listed 'Best First'.
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.


      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.

      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.


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.

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.

    M-x auto-bs-mode

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.

      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".

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!


      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.)

      M-x auto-bs-mode

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 => '', plp_site => '', do_not_use => 'spamtrap' }

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-

Re: What's the best plain Documentation format?
by John M. Dlugosz (Monsignor) on May 28, 2003 at 20:03 UTC

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://260856]
Approved by TStanley
Front-paged by hsmyers
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (2)
As of 2021-10-19 10:23 GMT
Find Nodes?
    Voting Booth?
    My first memorable Perl project was:

    Results (76 votes). Check out past polls.