"Paul \"LeoNerd\" Evans" <[email protected]> writes:
> Russ Allbery <[email protected]> wrote:
>> There are a few things that I've wanted to have in POD
>> for a while, although nothing that rose to the level of wanting to do
>> the work required to get it widely supported.
> Ah curious - I'd be happy to hear ideas.
One of the things I've wanted from nearly the start was some way of
marking up metasyntactic variables. POD is full of things like:
perl <file>
or:
push ARRAY,LIST
or the like, using various conventions mostly done via plain text, but
with proper markup they could get different formatting, different colors
in Pod::Text::Color, etc. Right now, some places use italics, some use
all caps, some use angle brackets, some don't mark them at all, etc.
The hardest thing about maintaining Pod::Man is that there are a bunch of
things that it is supposed to do to help not require excessive markup of
Perl code, including complicated rules about which C<> blocks get quotes
around them, but those rules all assume Perl. Right now, people have to
pass in flags to pod2man to disable the guesswork that doesn't apply to
their documentation. I'm not sure how this could be fixed with better
semantic markup without clusttering POD with a ton of markup, but I feel
like it should be possible.
Also, I know most folks here know this, but a reminder that people use POD
for a ton of things that are entirely unrelated to Perl, in part because
it's one of the easiest ways to write man pages without having to learn an
obscure formatting language and without having to write a ton of
impossibly verbose semantic markup.
Tables are an obvious thing to add and presumably can be implemented
natively in *roff although I have never used tbl and it might be a fair
bit of work. Implementing them for Pod::Text sounds really hard, but
maybe it won't be as bad as I'm fearing or someone else will do it for me.
I would like there to be a POD command for indicating the license of the
POD file itself so that the license text could be included in output
formats that support embedded comments, such as *roff and HTML. Not sure
what to do with the license in Pod::Text, but I think this would be better
than putting the license of the POD file in the user-visible text like
everyone does now. Really, that should be the license of the thing the
POD file is documenting, since that's what the user is reading about, and
that's often not the same as the license of the POD.
There was a fairly fleshed out proposal a while back for footnote support
that never went anywhere.
--
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 0gFzD gD,
00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{
rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print
