[Disclaimer: I haven't read perlpodspec yet, so some of my questions may
be answered there. Feel free to point me there.]
On Sun, 23 Sep 2001 23:05:06 -0600, in perl.perl5.porters you wrote:
> The I<indentlevel> option to
> "=over" indicates how far over to indent, generally in ems (where
> one em is the width of an "M" in the document's base font) or roughly
> comparable units; there is no I<indentlevel> option, it defaults
^
> to four.
Looks like there's an "if" missing at the point indicated.
> If you start with bullets or numbers, stick with them, as
> formatters use the first "=item" type to decide how to format the
> list.
Is that supposed to read like that - "formatters use the first '=item'
type to decide", without qualification? I would have expected "...as
*some* formatters use..." or "...as formatters *may* use...".
Specifying that this behaviour is required is not necessarily bad (it
makes things predictable), but I wouldn't have expected it, so I'm just
making sure I understood correctly.
> =item C<=cut>
>
> To end a Pod block, use a line beginning with "=cut", and a blank
> line after it. This lets Perl (and the Pod formatter) know that
> this is where Perl code is resuming.
There need not be a blank line before it?
Further up, '=cut' is listed with command paragraphs, and a paragraph
appears to be "text...with just a blank line before and after", though
the concept of "paragraph" doesn't appear to get defined explicitly.
> A command "=begin I<formatname>", some paragraphs, and a
> command "=begin I<formatname>", mean that the text/data inbetween
> is meant for formatters that understand the special format
> called I<formatname>.
The second =begin should probably be =end.
And you don't seem to say explicitly whether the format name on the =end
has to match the format name used on the =begin (it could conceivably
just be documentation, so you could use =begin html / =end stuff, or
perhaps even =begin html / =end (without format name on the =end, sort
of like #ifdef foo matching #endif).
Also, whether =begin/=end blocks may be nested, e.g. for specialisations
of format, and if so, what constraints are placed be on the =end
commands.
Also, what's the format of an I<formatname>? /\S+/? /\w+/? /.*/?
/[:\w]+/?
> =item *
>
> C<EE<lt>htmlnameE<gt>>
>
> Some non-numeric HTML entity name, such as C<EE<lt>eacuteE<gt>>,
> meaning the same thing as C<é> in HTML -- i.e., a lowercase
> e with an acute (/-shaped) accent.
Any valid HTML entity name? Or only those that map to Latin-1? What
about ™, for example? Or €?
Hm, and you don't appear to state explicitly the nesting rules for
formatting codes -- e.g., it's apparently possible to nest B<> and I<>
and E<> in C<>, since you do so, but you don't say it's possible. Can
you nest an C<> in a B<>? An L<> in a F<>? An E<> in an L<>?
> In fact, you can use as many repeated angle-brackets as you like so
> long as you have the same number of them in the opening and closing
> delimiters, and make sure that whitespace immediately follows the last
> '<' of the opening delimiter, and immediately precedes the first '>'
> of the closing delimiter.
As I understand it, the intent is that exactly one whitespace character
is deleted while rendering such multiple-bracket delimiters; this should
probably be mentioned, since it's otherwise vague whether C<< foo >> and
C<< foo >> render the same or differently. (By my understanding, the
first is "foo" and the second is " foo ".)
Also, is it "whitespace" after the opening and before the closing
delimiter? I've always used a single space for safety; would a tab or
newline also work? This could be pernicious if someone writes C<< foo >>
and the >> gets broken over onto a new line during editing -- then there
would suddenly be *two* whitespace characters before the closing
delimiter.
Cheers,
Philip
