As previous discussed on pod-people
(<url:http://www.xray.mpe.mpg.de/mailing-lists/pod-people/2001-04/msg00005.h
tml>), I've been working on a pod2xml and xml2pod. While testing it
recently, I stumbled upon a problem in perlpod:
Perlpod says:
L<name/ident> item in manual page
L<name/"sec"> section in other manual page
L<"sec"> section in this manual page (the quotes are optional)
L</"sec"> ditto
and the textful variants: L<text|name/ident>, L<text|name/"sec">,
L<text|"sec">, and L<text|/"sec">
This clearly implicates that there's a difference between a "section" and
an "item".
But it's strange, because why is there no L</ident> or L<text|/ident>?
Why do I see, in perlfunc.pod, both L<perlvar/$^F> and L<perlvar/"$/">,
both linking to items? Is the first one a typo?
Pod::Text also observes this difference (in rendering), calling it "entry"
and "section":
} elsif ($section =~ /^[:\w]+(?:\(\))?/) {
$text .= 'the ' . $section . ' entry';
$text .= (length $manpage) ? " in the $manpage manpage"
: " elsewhere in this document";
} else {
$section =~ s/^\"\s*//;
$section =~ s/\s*\"$//;
$text .= 'the section on "' . $section . '"';
$text .= " in the $manpage manpage" if length $manpage;
}
However, Pod::Tree doesn't observe any such difference: it parses
L<foo/"bar"> and L<foo/bar> identically.
What I'd like to have happen is one of these three:
I) agreement that L<name/foo> and L<name/"foo"> are NOT THE SAME (even tho
people seem to confuse them). This should involve explaining why the
difference is necessary and motivated. Ambitious pod checkers should
possibly then go about enforcing the difference, so that one of
L<perlvar/$^F> and L<perlvar/"$/"> are declared wrong.
II.a) agreement that L<name/foo> and L<name/"foo"> are THE SAME.
II.b) a decree that L<name/foo> and L<name/"foo"> are HENCEFORTH THE SAME
(i.e., there was a difference envisioned, but lots of people didn't get it,
and nothing apparently broke, so let's nevermind about that intended
difference).
Any of these three should require at least that perlpod.pod be ammended or
clarified.
Since I like option IIa/b. most, I suggest this change to perlpod:
Change the entire current L section, which consists of this:
L<name> A link (cross reference) to name
L<name> manual page
L<name/ident> item in manual page
L<name/"sec"> section in other manual page
L<"sec"> section in this manual page
(the quotes are optional)
L</"sec"> ditto
same as above but only 'text' is used for output.
(Text can not contain the characters '/' and '|',
and should contain matched '<' or '>')
L<text|name>
L<text|name/ident>
L<text|name/"sec">
L<text|"sec">
L<text|/"sec">
to this, which hopefully expresses all sage advice about how to form a good
L sequence:
L<name> A link (cross reference) to name
(Name cannot contain the characters '/' and '|',
and sec should not contain a '|'. Use E<sol> and
E<verbar> instead.)
L<name> manual page
L<name/"sec"> section or item in other manual page
(the quotes are optional)
L</"sec"> section or item in this manual page
(the quotes are optional)
L<"sec"> section or item in this manual page
(the quotes are recommended; sec
also cannot contain a '|')
Same as above but only 'text' is used for display:
(Text should contain matched '<' or '>', and cannot
contain the characters '/' and '|' -- use E<sol> and
E<verbar> instead.)
L<text|name>
L<text|name/"sec"> (quotes optional)
L<text|/"sec"> (quotes optional)
L<text|"sec"> (quotes recommended)
(Not having a "text|" bit leaves it up to the pod
formatter to decide how to display your link.)
Or should one just explicitly deprecate L<"sec"> and L<text|"sec">, in
favor of L</"sec"> and L<text|/"sec">? I'd be especially happy with that.
In that case:
L<"sec"> and L<sec> (deprecated: use L</"sec">)
and
L<text|"sec">
and L<text|sec> (deprecated: use L<text|/"sec">)
I need clarification on whether L<foo/item> and L<foo/"section"> either are
or aren't the same, because I need to know whether to have PXML's "link"
element take two attributes (one for name, and one for section AKA item),
or three (one for name, one for section, and one for item -- altho one
would never use an item and section at the same time) -- it has to be one
or the other.
--
Sean M. Burke [EMAIL PROTECTED] http://www.spinn.net/~sburke/
