Mailing List Archive

I think this is a good idea. I'd like to be part of modernizing and
updating Perl's documentation.

I think the Perl documentation could use re-work in places to make it
more "novice-friendly".

- Scott

On 10/23/20 9:17 AM, Jason McIntosh wrote:
> Dear Porters,
>
> I just completed a draft of a Perl core documentation style guide, the main deliverable of a TPF-funded project I began last month (https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7). It, plus a handful of supporting documents and other notes and recommendations, can be found here: https://jmac.org/misc/perldoc/
>
> As that web page states, two proposals stem from this work:
>
> 1) Perl 5 Porters adopting this style guide as a standards document for Perl’s core documentation, and adding it to Perl’s source distribution as either a man page (in `pod/`) or a porting document (in `Portling/`).
>
> 2) Perl 5 Porters establishing a documentation team or manager within p5p, tasked with maintaining and improving Perl’s core documentation, and essentially running it as its own open-source sub-project within the greater Perl project.
>
> As a follow-up action, I’d like to make a pull request out of the style guide, but only after giving p5p a chance to review and comment on the work outside of a source-control context. So, please consider me very interested in any questions or comments about this work.
>
> I’d also be very happy to further discuss either of the above proposals. To be quite clear, I am interested in accepting an ongoing role regarding documentation management, should one be created.

I’d also like to take part in ongoing documentation improvements.

-Felipe


> On Oct 23, 2020, at 1:44 PM, Scott Baker <scott@perturb.org> wrote:
>
> I think this is a good idea. I'd like to be part of modernizing and updating Perl's documentation.
>
> I think the Perl documentation could use re-work in places to make it more "novice-friendly".
>
> - Scott
>
> On 10/23/20 9:17 AM, Jason McIntosh wrote:
>> Dear Porters,
>>
>> I just completed a draft of a Perl core documentation style guide, the main deliverable of a TPF-funded project I began last month (https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7). It, plus a handful of supporting documents and other notes and recommendations, can be found here: https://jmac.org/misc/perldoc/
>>
>> As that web page states, two proposals stem from this work:
>>
>> 1) Perl 5 Porters adopting this style guide as a standards document for Perl’s core documentation, and adding it to Perl’s source distribution as either a man page (in `pod/`) or a porting document (in `Portling/`).
>>
>> 2) Perl 5 Porters establishing a documentation team or manager within p5p, tasked with maintaining and improving Perl’s core documentation, and essentially running it as its own open-source sub-project within the greater Perl project.
>>
>> As a follow-up action, I’d like to make a pull request out of the style guide, but only after giving p5p a chance to review and comment on the work outside of a source-control context. So, please consider me very interested in any questions or comments about this work.
>>
>> I’d also be very happy to further discuss either of the above proposals. To be quite clear, I am interested in accepting an ongoing role regarding documentation management, should one be created.

Three decades and three years ago a new programming language was brought
forth
upon this shore that provided new operators not seen before, such as *=~* to
match regular expressions. In doing so, Perl finally delivered on the
promises
made by Algol 68 that programmer time would, hence forth, be valued more
highly
than computer time. There was almost no competition because all other
programming languages at that time did the reverse: they valued computers
more
highly than people. As a consequence of this unrivaled new capability,
people
flocked to the Perl standard and brought forth a mighty new nation where
programming of the computers by the people for the people would long endure.

Since those heady days, various competitors have arisen, that have, over
time,
eroded the unique proposition of Perl: give me your poor, your tired, your
huddled masses yearning to breathe free and given them many confusing and
inferior alternatives instead.

It is up to us to continue the great work. The world will little note, nor
long
remember what minor changes we make to our *documentation* today. It is for
us to
continue the unfinished work which has been thus far so nobly advanced by
bringing forth new capabilities not yet seen in other realized programming
languages so that Perl will, once again, provide unique programming
paradigms
unmatched by any other language.

I say that we should drive our ship to new lands: follow the lead of Algol
68 and Unicode to finally deliver the capability to users, for users to
define their own new dyadic operators, so that if they wish to, they can
replace the archaic:

push @a, $i

with the modern:

a ? i

via a Perl sub definition:

op ?
{push $_[0]->@*, $_[1]
}

by themselves, for themselves, without having to learn C.

In doing so we will ensure that Perl programmers become even more productive
and that in return neither Perl nor CPAN shall perish from this Earth.

(With apologies to Abraham Lincoln and Emma Lazarus)

On Mon, Oct 26, 2020 at 1:24 PM Felipe Gasper <felipe@felipegasper.com>
wrote:

> I’d also like to take part in ongoing documentation improvements.
>
> -Felipe
>
>
> > On Oct 23, 2020, at 1:44 PM, Scott Baker <scott@perturb.org> wrote:
> >
> > I think this is a good idea. I'd like to be part of modernizing and
> updating Perl's documentation.
> >
> > I think the Perl documentation could use re-work in places to make it
> more "novice-friendly".
> >
> > - Scott
> >
> > On 10/23/20 9:17 AM, Jason McIntosh wrote:
> >> Dear Porters,
> >>
> >> I just completed a draft of a Perl core documentation style guide, the
> main deliverable of a TPF-funded project I began last month (
> https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7).
> It, plus a handful of supporting documents and other notes and
> recommendations, can be found here: https://jmac.org/misc/perldoc/
> >>
> >> As that web page states, two proposals stem from this work:
> >>
> >> 1) Perl 5 Porters adopting this style guide as a standards document for
> Perl’s core documentation, and adding it to Perl’s source distribution as
> either a man page (in `pod/`) or a porting document (in `Portling/`).
> >>
> >> 2) Perl 5 Porters establishing a documentation team or manager within
> p5p, tasked with maintaining and improving Perl’s core documentation, and
> essentially running it as its own open-source sub-project within the
> greater Perl project.
> >>
> >> As a follow-up action, I’d like to make a pull request out of the style
> guide, but only after giving p5p a chance to review and comment on the work
> outside of a source-control context. So, please consider me very interested
> in any questions or comments about this work.
> >>
> >> I’d also be very happy to further discuss either of the above
> proposals. To be quite clear, I am interested in accepting an ongoing role
> regarding documentation management, should one be created.
>


--
Thanks,

Phil <https://metacpan.org/author/PRBRENAN>

Philip R Brenan <https://metacpan.org/author/PRBRENAN>

On Fri, Oct 23, 2020 at 12:17:58PM -0400, Jason McIntosh wrote:
> Dear Porters,
>
> I just completed a draft of a Perl core documentation style guide, the main deliverable of a TPF-funded project I began last month (https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7). It, plus a handful of supporting documents and other notes and recommendations, can be found here: https://jmac.org/misc/perldoc/
>
> As that web page states, two proposals stem from this work:
>
> 1) Perl 5 Porters adopting this style guide as a standards document for Perl’s core documentation, and adding it to Perl’s source distribution as either a man page (in `pod/`) or a porting document (in `Portling/`).
>
> 2) Perl 5 Porters establishing a documentation team or manager within p5p, tasked with maintaining and improving Perl’s core documentation, and essentially running it as its own open-source sub-project within the greater Perl project.
>
> As a follow-up action, I’d like to make a pull request out of the style guide, but only after giving p5p a chance to review and comment on the work outside of a source-control context. So, please consider me very interested in any questions or comments about this work.
>
> I’d also be very happy to further discuss either of the above proposals. To be quite clear, I am interested in accepting an ongoing role regarding documentation management, should one be created.

Making a PR would make it easier to comment on (and passing
porting/podcheck.t might fix some issues, eg. some non-literal lines
are over 72 characters.)

I'm not sure that requiring American English (specifically US
spelling) is a good idea and the document might be too prescriptive in
other ways too (no () after function names was one case for me.)

Tony

On Oct 26, 2020, at 8:00 PM, Tony Cook <tony@develop-help.com> wrote:
>
> Making a PR would make it easier to comment on (and passing
> porting/podcheck.t might fix some issues, eg. some non-literal lines
> are over 72 characters.)

Sure… barring the unexpected, I intend to make a PR before next week. It seemed appropriate to get comment on the overall gist from p5p before requesting to merge a brand-new 6,800-word Pod document into blead, though!

As an until-then route for detailed commentary, a Google Doc version of “perldocstyle” exists here, which anyone can mark up: https://docs.google.com/document/d/1Wlfuk13QDFk3kvBfmI0sqmbrnsnE3rKNJDhw2ROul0w/edit?usp=sharing

> I'm not sure that requiring American English (specifically US
> spelling) is a good idea and the document might be too prescriptive in
> other ways too (no () after function names was one case for me.)

Well, in both of these cases (and many others), the point is just to pick *some* convention and stick with it, within the bounds of Perl’s core documentation. If you like, you may read these proposed standards as “This facet of the docs should be standardized (and here’s one possible way to do it)”.

The standards I did propose come from a mix of seeing how other languages’ style guide do it, getting advice from other documentation writers, and grepping the contents of `pod/` to see which styles were already the most popular within Perl’s present docs. (And, yes, just winging it sometimes.)

I expect that the the doc team-or-manager, assuming that p5p creates such a role, will ultimately be the party to decide these sorts of things. This doc is just a proposed starting point for them.

I'm happy about the Perl documentation improvement project.

Let me mention here the issues I'm having with the official Perl
documentation.

I feel that the current Perl documentation is focused on displaying on Unix
systems.

Meanwhile, in 2020, users will search for documents on the Web.

It has a Title and a Description.

<h1>Perl Tutorial</h1>

<p>
This document is a Perl tutorial
</p>

The current official documentation, unlike this, shows a command-like
documentation name (perlunitut).

https://perldoc.perl.org/perl

I would like to create a table of contents and expressions that are more
easier for beginners to see.

I think the top page is very important to let users know that Perl has been
improved and cleaned.

2020?10?24?(?) 1:26 Jason McIntosh <jmac@jmac.org>:

> Dear Porters,
>
> I just completed a draft of a Perl core documentation style guide, the
> main deliverable of a TPF-funded project I began last month (
> https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7).
> It, plus a handful of supporting documents and other notes and
> recommendations, can be found here: https://jmac.org/misc/perldoc/
>
> As that web page states, two proposals stem from this work:
>
> 1) Perl 5 Porters adopting this style guide as a standards document for
> Perl’s core documentation, and adding it to Perl’s source distribution as
> either a man page (in `pod/`) or a porting document (in `Portling/`).
>
> 2) Perl 5 Porters establishing a documentation team or manager within p5p,
> tasked with maintaining and improving Perl’s core documentation, and
> essentially running it as its own open-source sub-project within the
> greater Perl project.
>
> As a follow-up action, I’d like to make a pull request out of the style
> guide, but only after giving p5p a chance to review and comment on the work
> outside of a source-control context. So, please consider me very interested
> in any questions or comments about this work.
>
> I’d also be very happy to further discuss either of the above proposals.
> To be quite clear, I am interested in accepting an ongoing role regarding
> documentation management, should one be created.

I agree, and in addition to that I would also propose to remove or greatly decrease mention of old versions of Perl.

For example in https://perldoc.perl.org/perlfunc there are still mentions of 5.6, 5.8 perls:

For delays of finer granularity than one second, the Time::HiRes<https://perldoc.perl.org/Time::HiRes> module (from CPAN, and starting from Perl 5.8 part of the standard distribution) provides usleep<https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.

That should be shorter
For delays of finer granularity than one second, the Time::HiRes<https://perldoc.perl.org/Time::HiRes> module provides usleep<https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.

I consider this as a necessary step towards modernization.

Nodejs online documentation sometimes has expandable note to see information about older versions, if needed to be there. But this information should be hidden and only revealed by request.

From: Yuki Kimoto <kimoto.yuki@gmail.com>
Sent: Friday, October 30, 2020 4:29 AM
To: Jason McIntosh
Cc: perl5-porters@perl.org
Subject: Re: RFC: Perl documentation standards


[EXTERNAL EMAIL]
I'm happy about the Perl documentation improvement project.

Let me mention here the issues I'm having with the official Perl documentation.

I feel that the current Perl documentation is focused on displaying on Unix systems.

Meanwhile, in 2020, users will search for documents on the Web.

It has a Title and a Description.

<h1>Perl Tutorial</h1>

<p>
This document is a Perl tutorial
</p>

The current official documentation, unlike this, shows a command-like documentation name (perlunitut).

https://perldoc.perl.org/perl

I would like to create a table of contents and expressions that are more easier for beginners to see.

I think the top page is very important to let users know that Perl has been improved and cleaned.

2020?10?24?(?) 1:26 Jason McIntosh <jmac@jmac.org<mailto:jmac@jmac.org>>:
Dear Porters,

I just completed a draft of a Perl core documentation style guide, the main deliverable of a TPF-funded project I began last month (https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7). It, plus a handful of supporting documents and other notes and recommendations, can be found here: https://jmac.org/misc/perldoc/

As that web page states, two proposals stem from this work:

1) Perl 5 Porters adopting this style guide as a standards document for Perl’s core documentation, and adding it to Perl’s source distribution as either a man page (in `pod/`) or a porting document (in `Portling/`).

2) Perl 5 Porters establishing a documentation team or manager within p5p, tasked with maintaining and improving Perl’s core documentation, and essentially running it as its own open-source sub-project within the greater Perl project.

As a follow-up action, I’d like to make a pull request out of the style guide, but only after giving p5p a chance to review and comment on the work outside of a source-control context. So, please consider me very interested in any questions or comments about this work.

I’d also be very happy to further discuss either of the above proposals. To be quite clear, I am interested in accepting an ongoing role regarding documentation management, should one be created.

This particular example is unnecessary information but there are many cases
where it would be a counter-productive step, as that information is often
there to indicate what versions of Perl that feature is available in, and
speaking from personal and vicarious experience this is a very important
thing to know, for the same reason the perldoc website provides versions of
the documentation for so many versions of Perl.

-Dan

On Fri, Oct 30, 2020 at 2:55 AM Konovalov, Vadim <Vadim.Konovalov@dell.com>
wrote:

> I agree, and in addition to that I would also propose to remove or greatly
> decrease mention of old versions of Perl.
>
>
>
> For example in https://perldoc.perl.org/perlfunc there are still mentions
> of 5.6, 5.8 perls:
>
>
>
> For delays of finer granularity than one second, the Time::HiRes
> <https://perldoc.perl.org/Time::HiRes> module (from CPAN, and starting
> from Perl 5.8 part of the standard distribution) provides usleep
> <https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.
>
>
>
> That should be shorter
>
> For delays of finer granularity than one second, the Time::HiRes
> <https://perldoc.perl.org/Time::HiRes> module provides usleep
> <https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.
>
>
>
> I consider this as a necessary step towards modernization.
>
>
>
> Nodejs online documentation sometimes has expandable note to see
> information about older versions, if needed to be there. But this
> information should be hidden and only revealed by request.
>
>
>
> *From:* Yuki Kimoto <kimoto.yuki@gmail.com>
> *Sent:* Friday, October 30, 2020 4:29 AM
> *To:* Jason McIntosh
> *Cc:* perl5-porters@perl.org
> *Subject:* Re: RFC: Perl documentation standards
>
>
>
> [EXTERNAL EMAIL]
>
> I'm happy about the Perl documentation improvement project.
>
> Let me mention here the issues I'm having with the official Perl
> documentation.
>
> I feel that the current Perl documentation is focused on displaying on
> Unix systems.
>
> Meanwhile, in 2020, users will search for documents on the Web.
>
> It has a Title and a Description.
>
> <h1>Perl Tutorial</h1>
>
> <p>
> This document is a Perl tutorial
> </p>
>
> The current official documentation, unlike this, shows a command-like
> documentation name (perlunitut).
>
> https://perldoc.perl.org/perl
>
> I would like to create a table of contents and expressions that are more
> easier for beginners to see.
>
> I think the top page is very important to let users know that Perl has
> been improved and cleaned.
>
>
>
> 2020?10?24?(?) 1:26 Jason McIntosh <jmac@jmac.org>:
>
> Dear Porters,
>
> I just completed a draft of a Perl core documentation style guide, the
> main deliverable of a TPF-funded project I began last month (
> https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7).
> It, plus a handful of supporting documents and other notes and
> recommendations, can be found here: https://jmac.org/misc/perldoc/
>
> As that web page states, two proposals stem from this work:
>
> 1) Perl 5 Porters adopting this style guide as a standards document for
> Perl’s core documentation, and adding it to Perl’s source distribution as
> either a man page (in `pod/`) or a porting document (in `Portling/`).
>
> 2) Perl 5 Porters establishing a documentation team or manager within p5p,
> tasked with maintaining and improving Perl’s core documentation, and
> essentially running it as its own open-source sub-project within the
> greater Perl project.
>
> As a follow-up action, I’d like to make a pull request out of the style
> guide, but only after giving p5p a chance to review and comment on the work
> outside of a source-control context. So, please consider me very interested
> in any questions or comments about this work.
>
> I’d also be very happy to further discuss either of the above proposals.
> To be quite clear, I am interested in accepting an ongoing role regarding
> documentation management, should one be created.
>
>

But I consider having information about *unsupported* version is counter-productive.

There were many mentions recently about newcomers to Perl.
Overwhelming newcomers with obsoleted versions is counterproductive

Seasoned Perl programmer knows where to find information of 5.8


From: Dan Book <grinnz@gmail.com>
Sent: Friday, October 30, 2020 9:59 AM
To: Konovalov, Vadim
Cc: Yuki Kimoto; Jason McIntosh; perl5-porters@perl.org
Subject: Re: RFC: Perl documentation standards


[EXTERNAL EMAIL]
This particular example is unnecessary information but there are many cases where it would be a counter-productive step, as that information is often there to indicate what versions of Perl that feature is available in, and speaking from personal and vicarious experience this is a very important thing to know, for the same reason the perldoc website provides versions of the documentation for so many versions of Perl.

-Dan

On Fri, Oct 30, 2020 at 2:55 AM Konovalov, Vadim <Vadim.Konovalov@dell.com<mailto:Vadim.Konovalov@dell.com>> wrote:
I agree, and in addition to that I would also propose to remove or greatly decrease mention of old versions of Perl.

For example in https://perldoc.perl.org/perlfunc there are still mentions of 5.6, 5.8 perls:

For delays of finer granularity than one second, the Time::HiRes<https://perldoc.perl.org/Time::HiRes> module (from CPAN, and starting from Perl 5.8 part of the standard distribution) provides usleep<https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.

That should be shorter
For delays of finer granularity than one second, the Time::HiRes<https://perldoc.perl.org/Time::HiRes> module provides usleep<https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.

I consider this as a necessary step towards modernization.

Nodejs online documentation sometimes has expandable note to see information about older versions, if needed to be there. But this information should be hidden and only revealed by request.

From: Yuki Kimoto <kimoto.yuki@gmail.com<mailto:kimoto.yuki@gmail.com>>
Sent: Friday, October 30, 2020 4:29 AM
To: Jason McIntosh
Cc: perl5-porters@perl.org<mailto:perl5-porters@perl.org>
Subject: Re: RFC: Perl documentation standards


[EXTERNAL EMAIL]
I'm happy about the Perl documentation improvement project.

Let me mention here the issues I'm having with the official Perl documentation.

I feel that the current Perl documentation is focused on displaying on Unix systems.

Meanwhile, in 2020, users will search for documents on the Web.

It has a Title and a Description.

<h1>Perl Tutorial</h1>

<p>
This document is a Perl tutorial
</p>

The current official documentation, unlike this, shows a command-like documentation name (perlunitut).

https://perldoc.perl.org/perl

I would like to create a table of contents and expressions that are more easier for beginners to see.

I think the top page is very important to let users know that Perl has been improved and cleaned.

2020?10?24?(?) 1:26 Jason McIntosh <jmac@jmac.org<mailto:jmac@jmac.org>>:
Dear Porters,

I just completed a draft of a Perl core documentation style guide, the main deliverable of a TPF-funded project I began last month (https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7). It, plus a handful of supporting documents and other notes and recommendations, can be found here: https://jmac.org/misc/perldoc/

As that web page states, two proposals stem from this work:

1) Perl 5 Porters adopting this style guide as a standards document for Perl’s core documentation, and adding it to Perl’s source distribution as either a man page (in `pod/`) or a porting document (in `Portling/`).

2) Perl 5 Porters establishing a documentation team or manager within p5p, tasked with maintaining and improving Perl’s core documentation, and essentially running it as its own open-source sub-project within the greater Perl project.

As a follow-up action, I’d like to make a pull request out of the style guide, but only after giving p5p a chance to review and comment on the work outside of a source-control context. So, please consider me very interested in any questions or comments about this work.

I’d also be very happy to further discuss either of the above proposals. To be quite clear, I am interested in accepting an ongoing role regarding documentation management, should one be created.

You are making an assumption that newcomers will be using a new Perl
version, which is far from the majority in my experience. We may want to
encourage it but we cannot change what people use with a magic wand.

-Dan

On Fri, Oct 30, 2020 at 3:12 AM Konovalov, Vadim <Vadim.Konovalov@dell.com>
wrote:

> But I consider having information about **unsupported** version is
> counter-productive.
>
>
>
> There were many mentions recently about newcomers to Perl.
>
> Overwhelming newcomers with obsoleted versions is counterproductive
>
>
>
> Seasoned Perl programmer knows where to find information of 5.8
>
>
>
>
>
> *From:* Dan Book <grinnz@gmail.com>
> *Sent:* Friday, October 30, 2020 9:59 AM
> *To:* Konovalov, Vadim
> *Cc:* Yuki Kimoto; Jason McIntosh; perl5-porters@perl.org
> *Subject:* Re: RFC: Perl documentation standards
>
>
>
> [EXTERNAL EMAIL]
>
> This particular example is unnecessary information but there are many
> cases where it would be a counter-productive step, as that information is
> often there to indicate what versions of Perl that feature is available in,
> and speaking from personal and vicarious experience this is a very
> important thing to know, for the same reason the perldoc website provides
> versions of the documentation for so many versions of Perl.
>
>
>
> -Dan
>
>
>
> On Fri, Oct 30, 2020 at 2:55 AM Konovalov, Vadim <Vadim.Konovalov@dell.com>
> wrote:
>
> I agree, and in addition to that I would also propose to remove or greatly
> decrease mention of old versions of Perl.
>
>
>
> For example in https://perldoc.perl.org/perlfunc there are still mentions
> of 5.6, 5.8 perls:
>
>
>
> For delays of finer granularity than one second, the Time::HiRes
> <https://perldoc.perl.org/Time::HiRes> module (from CPAN, and starting
> from Perl 5.8 part of the standard distribution) provides usleep
> <https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.
>
>
>
> That should be shorter
>
> For delays of finer granularity than one second, the Time::HiRes
> <https://perldoc.perl.org/Time::HiRes> module provides usleep
> <https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.
>
>
>
> I consider this as a necessary step towards modernization.
>
>
>
> Nodejs online documentation sometimes has expandable note to see
> information about older versions, if needed to be there. But this
> information should be hidden and only revealed by request.
>
>
>
> *From:* Yuki Kimoto <kimoto.yuki@gmail.com>
> *Sent:* Friday, October 30, 2020 4:29 AM
> *To:* Jason McIntosh
> *Cc:* perl5-porters@perl.org
> *Subject:* Re: RFC: Perl documentation standards
>
>
>
> [EXTERNAL EMAIL]
>
> I'm happy about the Perl documentation improvement project.
>
> Let me mention here the issues I'm having with the official Perl
> documentation.
>
> I feel that the current Perl documentation is focused on displaying on
> Unix systems.
>
> Meanwhile, in 2020, users will search for documents on the Web.
>
> It has a Title and a Description.
>
> <h1>Perl Tutorial</h1>
>
> <p>
> This document is a Perl tutorial
> </p>
>
> The current official documentation, unlike this, shows a command-like
> documentation name (perlunitut).
>
> https://perldoc.perl.org/perl
>
> I would like to create a table of contents and expressions that are more
> easier for beginners to see.
>
> I think the top page is very important to let users know that Perl has
> been improved and cleaned.
>
>
>
> 2020?10?24?(?) 1:26 Jason McIntosh <jmac@jmac.org>:
>
> Dear Porters,
>
> I just completed a draft of a Perl core documentation style guide, the
> main deliverable of a TPF-funded project I began last month (
> https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7).
> It, plus a handful of supporting documents and other notes and
> recommendations, can be found here: https://jmac.org/misc/perldoc/
>
> As that web page states, two proposals stem from this work:
>
> 1) Perl 5 Porters adopting this style guide as a standards document for
> Perl’s core documentation, and adding it to Perl’s source distribution as
> either a man page (in `pod/`) or a porting document (in `Portling/`).
>
> 2) Perl 5 Porters establishing a documentation team or manager within p5p,
> tasked with maintaining and improving Perl’s core documentation, and
> essentially running it as its own open-source sub-project within the
> greater Perl project.
>
> As a follow-up action, I’d like to make a pull request out of the style
> guide, but only after giving p5p a chance to review and comment on the work
> outside of a source-control context. So, please consider me very interested
> in any questions or comments about this work.
>
> I’d also be very happy to further discuss either of the above proposals.
> To be quite clear, I am interested in accepting an ongoing role regarding
> documentation management, should one be created.
>
>

A newcomer to perl5.8 will happily use “perldoc” that comes with his/her 5.8 installation.
Obviously if they are forced to use 20 y.o. installation – they are surely prepared for such activity!

Otherwise target audience to this modernized documentation should be better defined.
Probably ancient perl novices should be supported with additional care. Create special pod section for them.

But just leaving unsupported versions there is just simply improper.

From: Dan Book <grinnz@gmail.com>
Sent: Friday, October 30, 2020 10:20 AM
To: Konovalov, Vadim
Cc: Yuki Kimoto; Jason McIntosh; perl5-porters@perl.org
Subject: Re: RFC: Perl documentation standards

You are making an assumption that newcomers will be using a new Perl version, which is far from the majority in my experience. We may want to encourage it but we cannot change what people use with a magic wand.

-Dan

On Fri, Oct 30, 2020 at 3:12 AM Konovalov, Vadim <Vadim.Konovalov@dell.com<mailto:Vadim.Konovalov@dell.com>> wrote:
But I consider having information about *unsupported* version is counter-productive.

There were many mentions recently about newcomers to Perl.
Overwhelming newcomers with obsoleted versions is counterproductive

Seasoned Perl programmer knows where to find information of 5.8


From: Dan Book <grinnz@gmail.com<mailto:grinnz@gmail.com>>
Sent: Friday, October 30, 2020 9:59 AM
To: Konovalov, Vadim
Cc: Yuki Kimoto; Jason McIntosh; perl5-porters@perl.org<mailto:perl5-porters@perl.org>
Subject: Re: RFC: Perl documentation standards

This particular example is unnecessary information but there are many cases where it would be a counter-productive step, as that information is often there to indicate what versions of Perl that feature is available in, and speaking from personal and vicarious experience this is a very important thing to know, for the same reason the perldoc website provides versions of the documentation for so many versions of Perl.

-Dan

On Fri, Oct 30, 2020 at 2:55 AM Konovalov, Vadim <Vadim.Konovalov@dell.com<mailto:Vadim.Konovalov@dell.com>> wrote:
I agree, and in addition to that I would also propose to remove or greatly decrease mention of old versions of Perl.

For example in https://perldoc.perl.org/perlfunc there are still mentions of 5.6, 5.8 perls:

For delays of finer granularity than one second, the Time::HiRes<https://perldoc.perl.org/Time::HiRes> module (from CPAN, and starting from Perl 5.8 part of the standard distribution) provides usleep<https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.

That should be shorter
For delays of finer granularity than one second, the Time::HiRes<https://perldoc.perl.org/Time::HiRes> module provides usleep<https://perldoc.perl.org/Time::HiRes#usleep-%28-%24useconds-%29>.

I consider this as a necessary step towards modernization.

Nodejs online documentation sometimes has expandable note to see information about older versions, if needed to be there. But this information should be hidden and only revealed by request.

From: Yuki Kimoto <kimoto.yuki@gmail.com<mailto:kimoto.yuki@gmail.com>>
Sent: Friday, October 30, 2020 4:29 AM
To: Jason McIntosh
Cc: perl5-porters@perl.org<mailto:perl5-porters@perl.org>
Subject: Re: RFC: Perl documentation standards

I'm happy about the Perl documentation improvement project.

Let me mention here the issues I'm having with the official Perl documentation.

I feel that the current Perl documentation is focused on displaying on Unix systems.

Meanwhile, in 2020, users will search for documents on the Web.

It has a Title and a Description.

<h1>Perl Tutorial</h1>

<p>
This document is a Perl tutorial
</p>

The current official documentation, unlike this, shows a command-like documentation name (perlunitut).

https://perldoc.perl.org/perl

I would like to create a table of contents and expressions that are more easier for beginners to see.

I think the top page is very important to let users know that Perl has been improved and cleaned.

2020?10?24?(?) 1:26 Jason McIntosh <jmac@jmac.org<mailto:jmac@jmac.org>>:
Dear Porters,

I just completed a draft of a Perl core documentation style guide, the main deliverable of a TPF-funded project I began last month (https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7). It, plus a handful of supporting documents and other notes and recommendations, can be found here: https://jmac.org/misc/perldoc/

As that web page states, two proposals stem from this work:

1) Perl 5 Porters adopting this style guide as a standards document for Perl’s core documentation, and adding it to Perl’s source distribution as either a man page (in `pod/`) or a porting document (in `Portling/`).

2) Perl 5 Porters establishing a documentation team or manager within p5p, tasked with maintaining and improving Perl’s core documentation, and essentially running it as its own open-source sub-project within the greater Perl project.

As a follow-up action, I’d like to make a pull request out of the style guide, but only after giving p5p a chance to review and comment on the work outside of a source-control context. So, please consider me very interested in any questions or comments about this work.

I’d also be very happy to further discuss either of the above proposals. To be quite clear, I am interested in accepting an ongoing role regarding documentation management, should one be created.

> On 30 Oct 2020, at 08:20, Dan Book <grinnz@gmail.com> wrote:
>
> You are making an assumption that newcomers will be using a new Perl version, which is far from the majority in my experience. We may want to encourage it but we cannot change what people use with a magic wand.

Having people still targeting 5.10 or such does not mean that 5.32 should be the documentation for 5.10 plus additions. On your system ‘perldoc perlwhatever’ will be the version for the perl you’re working on.
And on the new perldoc site: https://perldoc.perl.org/ it is trivial to select the version of perl you’re targeting and get the correct documentation.

—
Michiel

> On Oct 30, 2020, at 2:54 AM, Konovalov, Vadim <Vadim.Konovalov@dell.com> wrote:
>
> I agree, and in addition to that I would also propose to remove or greatly decrease mention of old versions of Perl.
>
> For example in https://perldoc.perl.org/perlfunc there are still mentions of 5.6, 5.8 perls:
>
> For delays of finer granularity than one second, the Time::HiRes module (from CPAN, and starting from Perl 5.8 part of the standard distribution) provides usleep.
>
> That should be shorter
> For delays of finer granularity than one second, the Time::HiRes module provides usleep.
>
> I consider this as a necessary step towards modernization.
>
> Nodejs online documentation sometimes has expandable note to see information about older versions, if needed to be there. But this information should be hidden and only revealed by request.

+1 to this last point.

-F

> On Oct 30, 2020, at 3:53 AM, Michiel Beijen <mb@x14.nl> wrote:
>
>> On 30 Oct 2020, at 08:20, Dan Book <grinnz@gmail.com> wrote:
>>
>> You are making an assumption that newcomers will be using a new Perl version, which is far from the majority in my experience. We may want to encourage it but we cannot change what people use with a magic wand.
>
> Having people still targeting 5.10 or such does not mean that 5.32 should be the documentation for 5.10 plus additions. On your system ‘perldoc perlwhatever’ will be the version for the perl you’re working on.
> And on the new perldoc site: https://perldoc.perl.org/ it is trivial to select the version of perl you’re targeting and get the correct documentation.

There could be a banner at the top or some such that trumpets the fact that:

This documentation describes Perl 5.32. Other versions may not support all features described here. For details about your own Perl version, run `perldoc <whatever>` on your system.

-F

I consider it perfectly normal and reasonable that someone may wish to
write or modify a program or a CPAN module such that it works on all perl
versions between e.g. 5.10.0 and the current perl.

I think it is considerate if the *current* documentation makes a brief
mention of when major new features were introduced. Possibly some of the
existing detail is too verbose and should be reduced to a simple
"(from 5.10.0)." at the end of a section or whatever, but I don't think it
should be removed altogether.

We shouldn't expect coders to have to rummage through multiple versions of
the online docs and perldeltas just to answer simple questions like "when
was fc() introduced?".

--
Never work with children, animals, or actors.

Just my opinion but, when I buy a new blender, I expect that its manual
teaches me how to use the exact model I just bought and not the model
someone released in 1970.

Maybe this RFC could be applied just to Perl 7 instead.

[]'s

On Fri, Oct 30, 2020 at 10:38 AM Dave Mitchell <davem@iabyn.com> wrote:

> I consider it perfectly normal and reasonable that someone may wish to
> write or modify a program or a CPAN module such that it works on all perl
> versions between e.g. 5.10.0 and the current perl.
>
> I think it is considerate if the *current* documentation makes a brief
> mention of when major new features were introduced. Possibly some of the
> existing detail is too verbose and should be reduced to a simple
> "(from 5.10.0)." at the end of a section or whatever, but I don't think it
> should be removed altogether.
>
> We shouldn't expect coders to have to rummage through multiple versions of
> the online docs and perldeltas just to answer simple questions like "when
> was fc() introduced?".
>
> --
> Never work with children, animals, or actors.
>

> From: Dave Mitchell <davem@iabyn.com>

> I consider it perfectly normal and reasonable that someone may
> wish to write or modify a program or a CPAN module such that it works on all
> perl versions between e.g. 5.10.0 and the current perl.

Supporting unsupported version of perl?
At the cost of slowing down modernization of entire perl?

no, I don't consider this as "perfectly normal and reasonable"

> I think it is
> considerate if the *current* documentation makes a brief mention of when major
> new features were introduced. Possibly some of the existing detail is too
> verbose and should be reduced to a simple "(from 5.10.0)." at the end of a
> section or whatever, but I don't think it should be removed altogether.

I wouldn't mind special file gathering such kind of information, which I can just
ignore (and novices will not notice its existence)
but please hide it from my everyday life, not only it makes Perl non-modern, but
also it steals my time and screen space.

> We
> shouldn't expect coders to have to rummage through multiple versions of the
> online docs and perldeltas just to answer simple questions like "when was fc()
> introduced?".

There is a special tool to answer that question
https://metacpan.org/pod/distribution/Perl-MinimumVersion/script/perlver

A simple “from 5.10.0” is entirely reasonable, but more detailed stuff, like the “Before Perl 5.14 …” section of `perldoc -f eval`, should be in a special place, maybe `perlpre514` or something. `perldoc -f eval` would then refer/link to `perlpre514` so that people still using 5.10 or what not can still easily find that information, but people on newer perls will be “rewarded” with more relevant docs.

-F

> On Oct 30, 2020, at 9:56 AM, Blabos de Blebe <blabos@gmail.com> wrote:
>
> Just my opinion but, when I buy a new blender, I expect that its manual teaches me how to use the exact model I just bought and not the model someone released in 1970.
>
> Maybe this RFC could be applied just to Perl 7 instead.
>
> []'s
>
> On Fri, Oct 30, 2020 at 10:38 AM Dave Mitchell <davem@iabyn.com> wrote:
> I consider it perfectly normal and reasonable that someone may wish to
> write or modify a program or a CPAN module such that it works on all perl
> versions between e.g. 5.10.0 and the current perl.
>
> I think it is considerate if the *current* documentation makes a brief
> mention of when major new features were introduced. Possibly some of the
> existing detail is too verbose and should be reduced to a simple
> "(from 5.10.0)." at the end of a section or whatever, but I don't think it
> should be removed altogether.
>
> We shouldn't expect coders to have to rummage through multiple versions of
> the online docs and perldeltas just to answer simple questions like "when
> was fc() introduced?".
>
> --
> Never work with children, animals, or actors.

On Fri, Oct 30, 2020 at 02:04:17PM +0000, Konovalov, Vadim wrote:
> no, I don't consider this as "perfectly normal and reasonable"

Ok, what percentage of actively maintained modules on CPAN do you think
are targeted to run only under 5.30.x and 5.32.x?

And that will in 7 months time drop support for 5.30.x?

--
"Strange women lying in ponds distributing swords is no basis for a system
of government. Supreme executive power derives from a mandate from the
masses, not from some farcical aquatic ceremony."
-- Dennis, "Monty Python and the Holy Grail"

> From: Dave Mitchell <davem@iabyn.com>
> Ok, what percentage of actively
> maintained modules on CPAN do you think are targeted to run only under 5.30.x
> and 5.32.x?

This question isn't proper.
I maintain CPAN module which supports 5.8 versions (Tcl).
I did updated some lines of code to support older versions of Perl.

Still - historical reviews in "perldoc -f someting" makes me impression about
wasting screen space and thus my coding time.

Again - modernization is modernization.
Let us archeological and nostalgic retreat collected in separate file or even folder.

> And that will in 7 months time drop support for 5.30.x?

This is what "official" https://perldoc.perl.org/perlpolicy says - yes.
Should I be ashamed about this?

> On 30 Oct 2020, at 15:24, Dave Mitchell <davem@iabyn.com> wrote:
>
> On Fri, Oct 30, 2020 at 02:04:17PM +0000, Konovalov, Vadim wrote:
>> no, I don't consider this as "perfectly normal and reasonable"
>
> Ok, what percentage of actively maintained modules on CPAN do you think
> are targeted to run only under 5.30.x and 5.32.x?

If my code targets Perl 5.10, I restrict myself to only use 5.10 features. So I’ll use the Perl 5.10 documentation. That’s easily accessible using the dropdown on the perldoc website, or by using the perldoc command in the correct perlenv on my local system.
—
Michiel

These analogies are not useful. Perl documentation is an entirely different
situation and you must realize that most newcomers do not have the
familiarity with the meaning of different versions that you do. Most people
outside the community actually think that 5.10 and 5.30 are similar
versions. Putting small notes where appropriate (and I did say the
presented example was an instance that isn't needed) is a tiny
inconvenience for you that improves the experience of those less
experienced, and those that want to quickly know the requirements of a
feature without checking a hundred different versions of the documentation.

Regardless of how Perl 7 turns out, it will not change that most people do
not use the latest version of Perl, so pretending everyone does because you
want it so is just petty.

-Dan

On Fri, Oct 30, 2020 at 9:57 AM Blabos de Blebe <blabos@gmail.com> wrote:

> Just my opinion but, when I buy a new blender, I expect that its manual
> teaches me how to use the exact model I just bought and not the model
> someone released in 1970.
>
> Maybe this RFC could be applied just to Perl 7 instead.
>
> []'s
>
> On Fri, Oct 30, 2020 at 10:38 AM Dave Mitchell <davem@iabyn.com> wrote:
>
>> I consider it perfectly normal and reasonable that someone may wish to
>> write or modify a program or a CPAN module such that it works on all perl
>> versions between e.g. 5.10.0 and the current perl.
>>
>> I think it is considerate if the *current* documentation makes a brief
>> mention of when major new features were introduced. Possibly some of the
>> existing detail is too verbose and should be reduced to a simple
>> "(from 5.10.0)." at the end of a section or whatever, but I don't think it
>> should be removed altogether.
>>
>> We shouldn't expect coders to have to rummage through multiple versions of
>> the online docs and perldeltas just to answer simple questions like "when
>> was fc() introduced?".
>>
>> --
>> Never work with children, animals, or actors.
>>
>

Supporting wide range of perls 5.10-5.30 makes me think of the person in question as advanced developer.
So we’re going to make inconvenience for novices because of these advanced developers who usually already know versions out of their heads, yet increasing impression about non-modern documentation, which is even unable to even hide versioning information like “nodejs” documentation do.

The “tiny inconvenience” is multiplied by large amount of times that this piece is accessed, thus making it rather big.


From: Dan Book <grinnz@gmail.com>
Sent: Friday, October 30, 2020 6:44 PM
To: Blabos de Blebe
Cc: Perl5 Porters
Subject: Re: RFC: Perl documentation standards

These analogies are not useful. Perl documentation is an entirely different situation and you must realize that most newcomers do not have the familiarity with the meaning of different versions that you do. Most people outside the community actually think that 5.10 and 5.30 are similar versions. Putting small notes where appropriate (and I did say the presented example was an instance that isn't needed) is a tiny inconvenience for you that improves the experience of those less experienced, and those that want to quickly know the requirements of a feature without checking a hundred different versions of the documentation.

Regardless of how Perl 7 turns out, it will not change that most people do not use the latest version of Perl, so pretending everyone does because you want it so is just petty.

-Dan

On Fri, Oct 30, 2020 at 9:57 AM Blabos de Blebe <blabos@gmail.com<mailto:blabos@gmail.com>> wrote:
Just my opinion but, when I buy a new blender, I expect that its manual teaches me how to use the exact model I just bought and not the model someone released in 1970.
Maybe this RFC could be applied just to Perl 7 instead.

[]'s

On Fri, Oct 30, 2020 at 10:38 AM Dave Mitchell <davem@iabyn.com<mailto:davem@iabyn.com>> wrote:
I consider it perfectly normal and reasonable that someone may wish to
write or modify a program or a CPAN module such that it works on all perl
versions between e.g. 5.10.0 and the current perl.

I think it is considerate if the *current* documentation makes a brief
mention of when major new features were introduced. Possibly some of the
existing detail is too verbose and should be reduced to a simple
"(from 5.10.0)." at the end of a section or whatever, but I don't think it
should be removed altogether.

We shouldn't expect coders to have to rummage through multiple versions of
the online docs and perldeltas just to answer simple questions like "when
was fc() introduced?".

--
Never work with children, animals, or actors.

On Fri, 30 Oct 2020 15:01:36 +0000, "Konovalov, Vadim"
<Vadim.Konovalov@dell.com> wrote:

> > From: Dave Mitchell <davem@iabyn.com>
> > Ok, what percentage of actively
> > maintained modules on CPAN do you think are targeted to run only
> > under 5.30.x and 5.32.x?
>
> This question isn't proper.
> I maintain CPAN module which supports 5.8 versions (Tcl).
> I did updated some lines of code to support older versions of Perl.
>
> Still - historical reviews in "perldoc -f someting" makes me
> impression about wasting screen space and thus my coding time.
>
> Again - modernization is modernization.
> Let us archeological and nostalgic retreat collected in separate file
> or even folder.
>
> > And that will in 7 months time drop support for 5.30.x?
>
> This is what "official" https://perldoc.perl.org/perlpolicy says -
> yes. Should I be ashamed about this?

My expectation:

$ perldoc -f xxx

will show me the syntax and description of this function in the perl
version that is used on the system I type this command

That said, I *very* frequently start this command on a system with a
newer perl than the system I target *just* to see what has changed in
this newer version so I am sure I don't fuck up.

I don't see how including information about behavior and changes in
older perl hinders development of modern perl.

How about not referring to older versions in the mainline of the
descriptions, but add a bottom section with something like

=head2 Older versions and changes

=head3 Introduction

Function xxx was introduced in perl release 5.xxx.yyy

=head3 Default arguments

The meaning of C<xxx ()>, calling xxx with no arguments, has changed
meaning in perl-5.xxx.yyy where before the behavior was undefined,
and after it would use C<$_>.

--
H.Merijn Brand https://tux.nl Perl Monger http://amsterdam.pm.org/
using perl5.00307 .. 5.33 porting perl5 on HP-UX, AIX, and Linux
https://useplaintext.email https://www.test-smoke.org
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/