in reply to POD as a general documentation system

I've used POD as documentation. I've used HTML as documentation. I've used *roff as documentation. I've used LaTeX as documentation. I've used PDF as documentation. I still use the latter if I need to write something for a customer and it needs to look "fancy" (I write it in LaTeX, and translate the dvi to PDF).

But nowadays, I swear by plain ASCII documents. It's the only true platform independent format (yeah, there are non-ASCII platforms out there). Anyone can read it. Anyone can edit it. And just before you think "plain ASCII sucks, I need markup/images/whatever", realize that RFCs have been written in plain ASCII for more than 3 decades, and will be written in plain ASCII for quite some time. I can read RFC 1 (which was written in 1969 and contains "images") as easily as the newest RFC.

Plain ASCII rocks.

Abigail

  • Comment on Re: POD as a general documentation system

Replies are listed 'Best First'.
Re: Re: POD as a general documentation system
by Juerd (Abbot) on Mar 27, 2003 at 07:52 UTC

    Plain ASCII rocks.

    Yes, plain ASCII rocks. But one of the beauties of POD is that it is so easy to convert.

    POD is easier to write than plain ASCII documentation, if you want the same features. Although I don't use images in my documentation, I do use definition lists. POD makes creating a definition list very easy.

    And when I'm done, I pod2text my document. But I can also pod2html and put it on my website with nice markup.

    Anyone can read it.

    Anyone can read pod2text's output

    Anyone can edit it.

    If someone is uncapable of editing POD, that someone is VERY stupid.

    You don't have to learn anything before you can edit plain text. Or do you? Is indenting done with tabs or spaces? Do we use 72, 78, 80 or 40 characters per line? Or do we think of lines as paragraphs, and let the pager do the wrapping? How are lists layed out?

    With POD, it's much easier to have a consistently layed out document

    "images"

    I like POD's verbatim paragraphs :) 

    Juerd
- http://juerd.nl/
- spamcollector_perlmonks@juerd.nl (do not use).

[reply]
      "...Yes, plain ASCII rocks. But one of the beauties of POD is that it is so easy to convert..."

      I'll second that. I have often been tempted by complex markup languages until I came across Stas Beckmans site (stason.org) after attending a local pm about the upcoming Mod_Perl 2.

      All the documentation was available simultaneously in printable PDF (see the top RH icons) and viewable online via html and in Perl itself. For those that are interested it is processed using docset, Pod::HtmlPsPdf etc.

      And all editable via POD.
[reply]
Re: Re: POD as a general documentation system
by enoch (Chaplain) on Mar 26, 2003 at 17:21 UTC
    If I could have ++'ed a node multiple times, Abigail, you would have gotten all of mine for the day.

    enoch
[reply]
[d/l]
Re^2: POD as a general documentation system
by Aristotle (Chancellor) on Mar 31, 2003 at 02:44 UTC

    You could read RFC 1 just as well if it was written as POD.

    POD has hardly changed during the last 2 decades as well, right?

    And the little bit of markup introduced by POD allows one to make the document navigatable by means other than scrolling and searching for patterns.

    Metadata rocks. POD keeps the difference between marked up text and plain ASCII very minimal. POD rocks.

    Makeshifts last the longest.

[reply]
      POD has hardly changed during the last 2 decades as well, right?

      POD didn't even exist 2 decades ago. In fact, POD is less than a decade old, it came with perl5. And, given what's going to happen with perl6, I wouldn't want to bet money on "POD will not change the next decade".

      Besides, all POD tools are written in Perl. Having to install a dinosaur like Perl just to be able to deal with general documentation doesn't rock - it sucks. It's hardly any worse than requiring people to install Word or some other tool that reads Word format.

      Abigail

[reply]
        But you don't! Any Joe Random User will understand what 
        =HEAD1 SYNOPSIS

        [download]

        means. There's rarely a lot more markup in POD and the spec is very simple - even if it changes in the future, the basic syntax (=FOO) is not going to change. The fact that the tools in existence are written in Perl is a red herring. In their absence, less works just as well. Of course the format is so simple you can easily write parsers in another language. I've used sed once.

        I did mix up the "two decades" thing - code and docs were wrapped before Perl5 too, but I forgot the Perl4 way of doing that was *roff.

        Makeshifts last the longest.

[reply]
[d/l]

In Section Meditations