Hi Philippe,
I've had some less-than-great encounters with the various ways
POD2ANYTHING converters deal with references like L<>, etc.
Philippe Schaffnit schrieb:
I've been trying to add some documentation to stress the similarity (and
hopefully differences) of '-f' and '-F': my first attempt was to add
plains
S<(c.f. -F, --modfilter)>
and
S<(c.f. -f, --filter)>
but then I thought that I might as well use an hyperlink, but... the
most obvious
L<S<(c.f. B<-F>, B<--modfilter>)>|/B<-F>, B<--modfilter>=I<FILTER>>
and
L<S<(c.f. B<-f>, B<--filter>)>|/B<-f>, B<--filter>=I<FILTER>>
don't really work: 'podchecker' doesn't complain, but 'pod2html' fails
to give valid references (I mean it doesn't recognise what I'm trying to
point to), the problem is the formating in the item header; it somehow
confuses 'pod2html'.
An L<> reference to a section titled "(c.f. -F, --modfilter)" wouldn't
make sense anyway, would it?
How about:
See also: The C<-F> or C<--modfilter> option.
Or:
Similarly for modules: C<-F> or C<--modfilter>.
Or somesuch. They're documented rather closely in the same manpage anyway.
If you insist on creating a real link to the other section, you'll
probably need to use the name of the section header explicitly (which
won't work because it's just an =item) or use an X<> index tag there and
reference to that. No idea whether that actually works. The ways of the
POD formatters are mysterious (to me at least). So don't take this as
gospel.
- get a suggestion on that (I've searched a lot, but couldn't find
anything very useful).
- drop this idea of having a link (...).
That would be the least work :)
- write it off as a bug in 'pod2html' (I've read some not so positive
comments on it), and hope that the issue will solve itself.
I don't think that is going to happen!
- reorganise the documentation not to have formating in the items text
(I don't think it's a good idea!).
Me neither.
HTH,
Steffen
