On Wed, Mar 5, 2008 at 3:35 PM, David Golden <[EMAIL PROTECTED]> wrote: > On Wed, Mar 5, 2008 at 1:06 PM, Ian Malpass <[EMAIL PROTECTED]> wrote: > > How about: > > > > =for method > > > > =head2 C<foo> > > > > Bit ugly, but it should work. Additional stuff after "method" could > > provide more metadata, etc. > > A simpler option might be to use the X<> indexing mark: > > =head2 X<C<foo>> > > That doesn't help with semantics, but does make it easier to identify > sections of interest. > > Potentially, the Z<> (null) tag could be used for metadata -- though > some parsers might warn if it contains something. That seems silly to > me -- why have a tag for ignoring its contents and then warn if it has > contents? > > Also, more generally, consider that formats that begin with a colon > are treated as POD and parsed as normal (c.f. perlpodspec and the "= > :biblio" example). So consider this in combination with the X<> tag > mentioned above : > > =begin :method > > =head2 X<C<foo>> > > Documentation of foo() here... > > =end :method
=for method has the least impact (if the next paragraph is left blank). According to the specs, it should be understood as leave the paragraph alone if you (POD processor) does not know about 'method'. On the contrary, dealing with =begin :method XXX =end :method many POD processors will disappear with the inner content of the begin/end piece. > That's all legal POD that shouldn't mess up existing parsers. > > David > POD is a little verbose and mixes content with markup as noticed by Andy with =item * C<foo> POD6 would provide exactly what Andy was looking for. But compatibility would be broken. The remedy would be writing documentation in POD6 and have a plugin as David Golden himself uses to extract WikiText and convert it to actual POD. Unfortunately, the POD6 to POD5 translator was not written yet.
