develooper Front page | perl.perl5.porters | Postings from April 2010

Re: RFC: Perl manual pages -- update to follow the perlstyle.podguidelines

Thread Previous | Thread Next
Jesse Vincent
April 2, 2010 10:25
Re: RFC: Perl manual pages -- update to follow the perlstyle.podguidelines
Message ID:

On Fri, Apr 02, 2010 at 05:15:42PM +0000, ?var Arnfj?r? Bjarmason wrote:
> On Fri, Apr 2, 2010 at 16:55, Jari Aalto <> wrote:
> > I noticed that many of the manual pages are inconsistent with the
> > perlstyle.pod guidelines. While this may seem like a minor quibble, I
> > personally think the quality of documentation is visible from the
> > writing and adhering to the style conventions.
> I'd just like to say that it's very useful that someone is checking
> out this aspect of our documentation. All of the fixes you propose all
> look good. The examples in our documentation should reflect best
> practices, they don't right now.

I, too, am absolutely thrilled to see this getting your attention and
review.  As has already become apparent, there is some disagreement about
what "best practices" are.  It's important to strike a balance between
improving documentation to better match best practice and rigidly making
ever example fit a particular house style.

> > I could send the patches for each pages in a separate threads?
> I don't know how Jesse would like to get them but if it was me I'd
> find it easier to merge it from a branch somewhere. Do you have a Git
> repository somewhere with these fixes?

I really, really dislike remote git branches for things that might ever
possibly want to be discussed or reviewed before commit.   A pointer to
a remote git repository means that porters need to take a positive
action in order to see a patch. That's...bad. "git am" means that
applying patches from mail is pretty trivial.

Patches submitted to perlbug are much easier to not lose or lose track
of. perlbug will take care of forwarding them to p5p for you, too.


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About