Comments

Ovid on 2003-05-17T19:25:03

I'm writing a fairly long document in POD and I realized that I was including notes to myself in the document, even though it's meant for someone else. Those notes would not only distract the person reading the document, but it would also detract from the point of the document. It's long enough, however, that I have to have those notes.

I could keep the notes in a separate document, but I know I won't remember to keep them in synch. Perhaps I could tag them and delete them when I'm done? No, I'll forget to delete one. The answer was so simple, though, that it was staring right at me. I had forgotten about the =for syntax.

    =head1 This is another section

    =for comment But this won't be displayed :)

I just mark those notes as comments and use a POD converter as normal. No extra steps to forget about. It's the little touches that I always appreciate.

---

Yes, a good trick!

merlyn on 2003-05-17T23:07:06

The Alpaca book was written using POD for everything right up to the last step. I put comments that I wanted Tom Phoenix to see in "=for tom", and comments meant for Linda as "=for editor" and reviewer comments and questions as "=for reviewers". Tom and Linda viewed (and edited) the POD directly, but we selectively extracted the reviewer comments in the reviewer copy, and it worked quite nicely.

Re:Yes, a good trick!

Ovid on 2003-05-17T23:50:53

Oddly enough, the long document is a book proposal I've been asked to flesh out and the comments are detailed notes of examples I want in the text :)

Time for a shameless plug...

kane on 2003-05-20T09:48:35

You have heard of Acme::Comment right?
And before you get alarmed, no you wouldn't be the first to use it in production code ;)