Pod tip

Matts on 2003-02-17T12:03:05

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

  Call the method Cconstructor($parameter)> to get a C 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 thing back.

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

---

Oooh, I've been useing that for ages...

2shortplanks on 2003-02-17T13:09:31

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

Re:Oooh, I've been useing that for ages...

darobin on 2003-02-17T13:29:01

Hmmmm. You do know that you don't have to escape ">" in XML right? It's there if you need to, but only & and < 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 C<< >> trick in POD.

Re:Oooh, I've been useing that for ages...

Matts on 2003-02-17T13:47:51

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.