in reply to Re: Crash Course in POD
in thread Crash Course in POD

It is important to remember not to document methods that the user of your module should not be calling directly. Use #c#o#m#m#e#n#t#s# for those.
Or you can steal Larry's own trick used while writing Camel III (which was done in POD): he "hid" little notes to self by using =for later. Or in this case, one might use =for internal use only. I prefer this over comments for two reasons. It is still accessible to POD tools if so chosen and can be extracted/marked up for an extended documentation. Secondly, it is a clear signal to human readers, more so than just mere comments.

Makeshifts last the longest.

Replies are listed 'Best First'.
Re: Crash Course in POD
by Abigail-II (Bishop) on Apr 23, 2003 at 09:20 UTC
    IIRC, the Camel wasn't written in POD. It was written in POD + extensions, to be processed by a special pod2ora program. I've the "POD"s of the second edition of the Cookbook here - if you run it through pod2text, you'll get quite some warnings about unrecognized markup.

    Personally, I would use POD if the intended end result was man pages. I'd use LaTeX if the end result is intended to be a document of some form.

    Abigail

[reply]
      Well, I just went by what Larry himself writes, in the POD chapter of Camel III - that they'd written the book this way.

      Makeshifts last the longest.

[reply]

      I'd use LaTeX if the end result is intended to be a document of some form.

      Never used it myself, but a while ago there was some talk about using pod for the first draft and then continuing with the document that pod2latex creates. Is that how you work, or do you start with latex? 

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

[reply]

        I'd rather start with LaTeX in that case - it is very human writable, though not as human readable as POD, and allows far more more control over layout than POD (optionally; you can let the LaTeX compiler figure out as much or as little by itself as you want). The pod2latex output is likely to be far more convoluted than a human written document.

        If you've never used LaTeX before, you should give it a spin - it is pure joy to write a couple lines of markup and get a gorgeously typeset document, esp compared to monkeying with "word processors" or even "office suites". Plus you can write the document in vi (and nicely syntax highlighted by vim), instead of wrestling a large GUI program that lacks a decent editor but eats oodles of RAM for all the pretty buttons. And then the results don't even look nearly as slick - the styles LaTeX comes with produce professional quality layouts.

        Makeshifts last the longest.

[reply]
        I'd start with LaTeX. Output of compilers (all the pod2foo programs are compilers) is more often than not unsuitable to be further processed by humans.

        I just finished a document introducing the DBI here at work, and it's written in LaTeX as well. I wouldn't be able to tell POD it should not break examples over pagebreaks. In LaTeX, I just make floating figures out of example programs and have LaTeX figure out the ideal placement. LaTeX automatically makes an index and a title page as well, and allows me to include pictures I've made with xfig. The document I made has nothing fancy, but it does use the three points I just made.

        Abigail

[reply]

In Section Seekers of Perl Wisdom