Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Matts (1087)

Matts
  (email not shown publicly)
I work for MessageLabs [messagelabs.com] in Toronto, ON, Canada. I write spam filters, MTA software, high performance network software, string matching algorithms, and other cool stuff mostly in Perl and C.

Journal of Matts (1087)

Monday February 17, 2003
07:03 AM

Pod tip

[ #10624 ]

I've many times had difficulty in Pod writing method docs when you want to type:

  Call the method C<Foo->constructor($parameter)> to get a C<Foo> thing back.

The problem with that is the C<> section that the parser sees is just C<Foo->.

What I used to do is play tricks with E<> to try and get it to all work. But there's an easier way. In pod you can use multiple brackets followed by whitespace as delimiters, so the above becomes:

  Call the method C<< Foo->constructor($parameter) >> to get a C<Foo> thing back.

Hopefully this will help someone else out in authoring their Pod API docs.


List all Journal entries
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

Pod tip 3 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • ...and is one of the things that drives me up the wall with XML that I can't do something like that.

    Infact, the inablility to write code easily in XML is one of the main reasons that I wrote the entire of the advent calendar in POD not XML.

    • Hmmmm. You do know that you don't have to escape ">" in XML right? It's there if you need to, but only &amp; and &lt; are really necessary. And I don't need "<" all that often in Perl...

      I routinely write code in XML, and I've rarely needed to escape anything. One reason is quoted above, another is that I wrap large pieces of code in <![CDATA[...]]> anyway just so I don't have to worry about it. To be honest, I find I have to escape stuff in XML less often than I need to use the

      --

      -- Robin Berjon [berjon.com]

    • I try to be very careful regarding zealotry about languages. Pod is great for documentation and articles. Where it falls down is complex cross referencing, markup in verbatim sections, diagrams and tables, and so on. If you need all that you might be better off with sDocBook (or if you're darobin, a custom XML lingo).

      But yeah, Pod is great for the sorts of use like the Advent calendar, and my AxKit Wiki.
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.