So Andy's thoughts on -o vs. -f and Sean's mentioning of perlop etc.
executables got me thinking... perlop , displays the section of perlop
about the comma operator? Okay, but then you have to know , is documented
in perlop. But what if they want to look up taint? (This is an extension/
reformulation of Andy's argument that operator/function is a distinction the
end user needed be aware of).
So ignoring -q and -f for now, which are grandfathered in...
I think a general purpose query system is in order, -Q for query
Here's how I envisage it. Given an index (more on that later) -Q EXPR
checks the index to determine which page(s) has information about EXPR.
All perl man pages would be in the index, and so you need not know where
anything lives to display the relevant section.
The index lookup is bound to be potentially slow, due to the large number
of entries. So, in the event that you know where something lives you can
tell query which page to process. You might do this like so -Q=perlvar
'$MATCH' or equivalently -Q=var '$MATCH' (since presumably all core pod
is prefixed with 'perl', it's optional). Thusly -f is merely an alias for
-Q=func (-q isn't quite an alias for -Q=faq).
The index. Well presumable for speed a DB would be good. But this is perldoc
afterall, so we probably ought to keep it plain text. What about perlindex.pod,
which would just be a giant list of
=item EXPR
perlfoo.pod
Where EXPR is in the simplest case a string to eq vs. the EXPR given -Q,
but might also be a large string wherin the -Q EXPR might be a substring.
Or EXPR might be a regexp. The paragraph for =item EXPR contains the name
of the page(s) with information on EXPR. eg;
=item getgrent
perlfunc
=item -T taint
perlrun, perlsec, perlfaq7
And finally, well it seems this will require a reworking of at least some
of the perl documentation, most specifically perlop (which is why I never
got anywhere with my -o for operators many many moons ago). pages need to have
clearly delimited sections for each thing they are describing, either =item or
=headn so perldoc can parse out the appropriate paragraphs for
display. Furthermore, this would allow at least portions of perlindex to be
built programmatically by parsing the documentation.
*ducks*
PS> When did the perltoc layout change? Or did it? I seem to remember it
having just a list of the various manpages at the top. That might be
nice before getting into what each one contains.
PPS> executables named after the various pages might then simply be links
to perldoc proper which could fall down to -Q=$0
--
H4sICNoBwDoAA3NpZwA9jbsNwDAIRHumuC4NklvXTOD0KSJEnwU8fHz4Q8M9i3sGzkS7BBrm
OkCTwsycb4S3DloZuMIYeXpLFqw5LaMhXC2ymhreVXNWMw9YGuAYdfmAbwomoPSyFJuFn2x8
Opr8bBBidccAAAA=
--
MOTD on Prickle-Prickle, the 69th of Chaos, in the YOLD 3169:
Life is the little things...
