Re: Discussing Extending the POD Spec

"Paul \"LeoNerd\" Evans" <[email protected]> writes:
> Russ Allbery <[email protected]> wrote:

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

> I'm not quite sure I get what you mean here.

    =item new(ARGS)

    Create a new Pod::Man object.  ARGS should be a list of key/value
    pairs, where the keys are chosen from the following.

ARGS has no markup because no markup really fits, but it should be marked
up because it's not regular text.  I want to be able to write:

    =item new(M<args>)

    Create a new Pod::Man object.  M<args> should be a list of key/value
    pairs, where the keys are chosen from the following.

and then the formatter can decide whether to use all-caps, a different
font, a different style, or whatever.  Similarly for common man page
synopsis cases:

    pod2man [B<--center>=I<string>] [B<--date>=I<string>]

should be:

    pod2man [B<--center>=M<string>] [B<--date>=M<string>]

The harder problem is how to handle the sort of sample commands that are
currently set off in a verbatim block, where we can't use inline markup,
such as:

    This adds:

        .mso <language>.tmac
        .hla <language>

    to the start of the file, which configure correct line breaking for
    the specified language.

That should ideally be M<language>, but obviously that doesn't work there.
Sphinx has special syntax for this in the :file: and :samp: roles, but
that wouldn't work with POD verbatim blocks.

-- 
#!/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