perldoc rewrite

<html><head></head><body><div style="font-family: Verdana;font-size: 12.0px;"><div>Dear Porters</div>

<div>&nbsp;</div>

<div>I posted here some weeks ago&nbsp; my wish for function and var index page but the issue behind it turned out to be much bigger.</div>

<div>Thats why I currently plan a rewrite of perldoc tool. mark and brian are on board and i just had fruitful discussions and input on and off YAPC&nbsp; including damian and sawyer.</div>

<div>&nbsp;</div>

<div>Even it will take some time to get even a&nbsp; functionaly equivalent replacement (first before I can add features),</div>

<div>I already want to discuss with you some changes that will be needed.</div>

<div>An detailed featurelsit will be posted later on blogs.perl but for now i want to announce the stuff that might be most disturbing from your point.</div>

<div>&nbsp;</div>

<div>1. I want make parameter parsing of perldoc stricter, so only input that completely makes sense will be run.</div>

<div>&nbsp;</div>

<div>2. at some point searchable keywords have to be included in the pod via X&lt;&gt; tags and in the main perl.POD the references to oterh pages has to be converted to</div>

<div>L&lt;...&gt; so i can categorize them by the X&lt;in front&gt; to get sensible search categories without guessing too much,</div>

<div>plus it would make it more similar what perldoc.org shows.</div>

<div>&nbsp;</div>

<div>3. I need the -M key (CLI option) for module related stuff. Since sawyer already told me I can&#39;t have the -m</div>

<div>&nbsp; the -M sems a good candidate since its very rarely used (alt formatter Module) and the we have good precedent of changing one very seldom used flag of perldoc by mark in past.(sorry but details to that are at home at my main machine).</div>

<div>&nbsp;</div>

<div>Thanks</div>

<div>Herbert</div></div></body></html>
0
deirdre_skye
8/11/2017 3:49:10 PM
perl.perl5.porters 46697 articles. 0 followers. Follow

4 Replies
23 Views

Similar Articles

[PageSpeed] 3

On 08/11/2017 11:49 AM, herbert breunung wrote:
> Dear Porters
> I posted here some weeks ago  my wish for function and var index page but the
> issue behind it turned out to be much bigger.
> Thats why I currently plan a rewrite of perldoc tool. mark and brian are on
> board and i just had fruitful discussions and input on and off YAPC  including
> damian and sawyer.
> Even it will take some time to get even a  functionaly equivalent replacement
> (first before I can add features),
> I already want to discuss with you some changes that will be needed.
> An detailed featurelsit will be posted later on blogs.perl but for now i want to
> announce the stuff that might be most disturbing from your point.
> 1. I want make parameter parsing of perldoc stricter, so only input that
> completely makes sense will be run.

This suggests the potential for extensive breakage.  Can you provide 
examples of input that currently runs but in the future may not?


> 2. at some point searchable keywords have to be included in the pod via X<> tags
> and in the main perl.POD the references to oterh pages has to be converted to
> L<...> so i can categorize them by the X<in front> to get sensible search
> categories without guessing too much,
> plus it would make it more similar what perldoc.org shows.
> 3. I need the -M key (CLI option) for module related stuff. Since sawyer already
> told me I can't have the -m
>     the -M sems a good candidate since its very rarely used (alt formatter
> Module) and the we have good precedent of changing one very seldom used flag of
> perldoc by mark in past.(sorry but details to that are at home at my main machine).
> Thanks
> Herbert
> 
0
jkeenan
8/12/2017 2:36:17 AM
Yes It will break a little, but only cases, where user added params
that cant be evaluated anyway and this behaviour is also different,
depending what param was in front.

My goal is to make prameter parsing regular (order should not matter).

An simple example that would break would be eg

perldoc reftut -h

becasue you cant really display help and retut at same time.
you have to say

perldoc -h
or
perldoc reftut

Hope that helps
Herbert

> On 08/11/2017 11:49 AM, herbert breunung wrote:
>> Dear Porters
>> I posted here some weeks ago  my wish for function and var index page but the
>> issue behind it turned out to be much bigger.
>> Thats why I currently plan a rewrite of perldoc tool. mark and brian are on
>> board and i just had fruitful discussions and input on and off YAPC  including
>> damian and sawyer.
>> Even it will take some time to get even a  functionaly equivalent replacement
>> (first before I can add features),
>> I already want to discuss with you some changes that will be needed.
>> An detailed featurelsit will be posted later on blogs.perl but for now i
>> want to
>> announce the stuff that might be most disturbing from your point.
>> 1. I want make parameter parsing of perldoc stricter, so only input that
>> completely makes sense will be run.
> 
> This suggests the potential for extensive breakage.  Can you provide examples
> of input that currently runs but in the future may not?
> 
> 
>> 2. at some point searchable keywords have to be included in the pod via X<>
>> tags
>> and in the main perl.POD the references to oterh pages has to be converted to
>> L<...> so i can categorize them by the X<in front> to get sensible search
>> categories without guessing too much,
>> plus it would make it more similar what perldoc.org shows.
>> 3. I need the -M key (CLI option) for module related stuff. Since sawyer
>> already
>> told me I can't have the -m
>>     the -M sems a good candidate since its very rarely used (alt formatter
>> Module) and the we have good precedent of changing one very seldom used flag of
>> perldoc by mark in past.(sorry but details to that are at home at my main
>> machine).
>> Thanks
>> Herbert
>>
> 
0
deirdre_skye
8/14/2017 9:38:18 AM
On Fri, Aug 11, 2017 at 5:49 PM, herbert breunung <deirdre_skye@web.de> wrote:
> Dear Porters
>
> I posted here some weeks ago  my wish for function and var index page but
> the issue behind it turned out to be much bigger.
> Thats why I currently plan a rewrite of perldoc tool. mark and brian are on
> board and i just had fruitful discussions and input on and off YAPC
> including damian and sawyer.

How would this index be used?

>
> Even it will take some time to get even a  functionaly equivalent
> replacement (first before I can add features),
> I already want to discuss with you some changes that will be needed.
> An detailed featurelsit will be posted later on blogs.perl but for now i
> want to announce the stuff that might be most disturbing from your point.
>
> 1. I want make parameter parsing of perldoc stricter, so only input that
> completely makes sense will be run.
>
> 2. at some point searchable keywords have to be included in the pod via X<>
> tags and in the main perl.POD the references to oterh pages has to be
> converted to
> L<...> so i can categorize them by the X<in front> to get sensible search
> categories without guessing too much,
> plus it would make it more similar what perldoc.org shows.

Which part of perldoc.org are you talking about?  It doesn't use X<>
tags for indexes or anything else.

>
> 3. I need the -M key (CLI option) for module related stuff. Since sawyer
> already told me I can't have the -m
>   the -M sems a good candidate since its very rarely used (alt formatter
> Module) and the we have good precedent of changing one very seldom used flag
> of perldoc by mark in past.(sorry but details to that are at home at my main
> machine).

This sounds like a terrible idea.  Why can't you pick a different letter?

>
> Thanks
> Herbert

There are plenty of users of the Pod::Perldoc API, both as a library
and as extensions.  This sounds like a lot of potential breakage for a
change that is not well explained.
0
haarg
8/14/2017 4:28:32 PM
>>
>> I posted here some weeks ago  my wish for function and var index page but
...
>> including damian and sawyer.
> 
> How would this index be used?

it would be normal pod page like the one called by perldoc perl
which I also consider a index page.

it would be an enhanced version of

http://perldoc.perl.org/index-functions.html

even the table of content of http://perldoc.perl.org/perlop.html
works as an index but for starter I would like see the 3 for core functions
special var and installed modules.


> This sounds like a terrible idea.  Why can't you pick a different letter?

I understand that you feel that way, but please see the whole picture (what
features we want and how sanely compromise between what is and where we want
to go). To search for module documentation will be used much more often by a
wide margin and -M for module makes much more sense than any other letter.
Alternative could be -p like package but thats awkward.

I think Brians idea for a --..  flag that enables sanely renamed option flags.
after some time people can get used the saner names without breaking anything.
but still i wanted know your opinion.


>There are plenty of users of the Pod::Perldoc API, both as a library
>and as extensions.  This sounds like a lot of potential breakage for a
>change that is not well explained.

sure its a core lib but frankly thats why i want to rewrite it because in
current state no one can touch it. I try to break as little as possible
and i posted here the worst two cases that I see absolutely necessary.
Soon there will be on blogs.perl.org a post which explains the plan in much
more details.

Cheers
0
deirdre_skye
8/15/2017 6:30:24 PM
Reply: