Re: Proposal: =mansec PoD extension & manpage section usage
Eric Wilhelm
# on Sunday 28 May 2006 07:51 pm:
>It might be better to use an existing directive like "=for
>mansection" rather than creating a new top-level directive.
=for mansection won't work
Because this is a paragraph. It gets displayed by standard pod tools.
=begin mansection
This
And This
and even
this
...would go in the mansection bit (e.g. ignored by non-mansection-aware
pod tools.)
=end mansection
=head1 SEE ALSO
L<perlpod>
=cut
--Eric
--
"...our schools have been scientifically designed to
prevent overeducation from happening."
--William Troy Harris
---------------------------------------------------
http://scratchcomputing.com
---------------------------------------------------
Ken Williams
On May 29, 2006, at 2:25 AM, Eric Wilhelm wrote:
> # from Ken Williams
> # on Sunday 28 May 2006 07:51 pm:
>
>> It might be better to use an existing directive like "=for
>> mansection" rather than creating a new top-level directive.
>
> =for mansection won't work
>
> Because this is a paragraph. It gets displayed by standard pod tools.
I was thinking "=for mansection 5" or similar, which should indeed
work according to the docs in `perldoc perlpod`.
-Ken
Eric Wilhelm
# on Monday 29 May 2006 05:50 pm:
>> =for mansection won't work
>>
>> Because this is a paragraph. It gets displayed by standard pod
>> tools.
>
>I was thinking "=for mansection 5" or similar, which should indeed
>work according to the docs in `perldoc perlpod`.
Okay, that would work. I misread the OP as wanting to have particular
sections of the POD go in separate man sections.
If it is a tag global to the pod, "=for mansection #" will work.
In which case, I suggest that "=begin mansection #" should divide the
pod output into separate manpages so that API and internals docs from
one file can be subdivided.
--Eric
--
I arise in the morning torn between a desire to improve the world and a
desire to enjoy the world. This makes it hard to plan the day.
--E.B. White
---------------------------------------------------
http://scratchcomputing.com
---------------------------------------------------
Linda W
Eric Wilhelm wrote:
> # from Ken Williams
> # on Monday 29 May 2006 05:50 pm:
>
>
>>> =for mansection won't work
>>>
>>> Because this is a paragraph. It gets displayed by standard pod
>>> tools.
>>>
>> I was thinking "=for mansection 5" or similar, which should indeed
>> work according to the docs in `perldoc perlpod`.
>>
>
> Okay, that would work. I misread the OP as wanting to have particular
> sections of the POD go in separate man sections.
>
---
That might be a nice flexibility for someone at some point, but it
isn't necessary for what I would like.
> If it is a tag global to the pod, "=for mansection #" will work.
>
---
Great.
Maybe what I want to do isn't 'designed' to be done. My main
objective was to generate manpages for many "pods" that don't
install their documentation as manpages when they are installed.
Ideally, my idea was to sweep through the Perl include path
and look for pod's and pm's-with-pods (pwp's?) in the installed
modules then generate the manpages, putting them into appropriate
sections.
If there is already a manpage for a particular item, I'd probably
want to compare dt's and only generate a new page if the pod or pwp is
newer.
I haven't decided if there is any specific "order" in which I
should go through the includes, but I should (not to make this
overly complicated, but) do the scan over the include dirs in reverse
order, since at load time, perl will pick up the include file found
first. Theoretically, if someone's include tree is clean there shouldn't
be duplicates, but having had it happen to me, I know about "should"s. :-)
Also, theoretically, I "should" scan all man-tree in the MAN include
path for duplicates, but initially I may only look at the target tree.
I have seen man pages from "dist"-installed manpages in /usr/share/man,
but more often see pages installed through CPAN installed into /usr/man.
Thanks again for the comments...
-linda