A restructured perlvar

I've been working on a restructured perlvar and I think I've mostly got it right, but at the moment I'm almost wishing that I never have to see it again. Have a look for yourself. It's in the perl git repo in the briandfoy/perlvar branch (if you're looking at the github mirror, realize it's several hours behind).

The new version notes when each variable appeared in the Perl 5 series of releases if it wasn't there at the start.

I still have to ensure that nothing breaks the perldoc -v stuff. I've tried it on several variables without problems but I don't know if some of the restructuring affected the odd variable.

I expect to merge this for the next development release, so I have a couple works to sort out whatever is left.

12 Comments

Improving perl's documentation is a rather under-appreciated task to do, but often at least as necessary as updating its code.

Lots of kudos to you!

=item ${^WIN32_SLOPPY_STAT}
X<sitecustomize> X<sitecustomize.pl>
looks a bit suspicious (line 830 of 'pod/perlvar.pod')

Thank you! This is a wonderful improvement. There has been a lot about marketing Perl in the blogosphere in the last year, and this is one of the best things I've seen. A great example of making easy things easy (knowing if a feature is available) and hard things possible (knowing from the start what versions will not be supported so it can be accurately documented and listed in the prerequisites). Great idea!

It's just different from other header lines... but I guess it is valid (I didn't and don't know what X<...> means).

You have (or had) an error around line 1522: the information about $\ got inserted into middle of description of $| variable.

=item HANDLE->autoflush(EXPR)
=item $OUTPUT_AUTOFLUSH
=item Handle->output_record_separator EXPR
=item $OUTPUT_RECORD_SEPARATOR
=item $ORS
=item $\
X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>

The output record separator for the print operator. If defined, this value is printed after the last of print's arguments. Default is C<undef>.

Mnemonic: you set C<$\> instead of adding "\n" at the end of the print. Also, it's just like C<$/>, but it's what you get "back" from Perl.

=item $|
X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>

Yes, it is fixed now.


Yet another suspect thing, at beginning of "Variables related to formats" section, line 1571: The special variables for formats are a subset of those for filehandles so they have... and here it ends. So they have what?

line 1701:

perl sets C<$!> is set to

Either perl sets C<$!>, or C<$!> is set to, not both :-)

Wells Fargo has agreed to restructure my mortgage but with a prepayment penalty and does not state the terms of the prepayment penalty.
[spam link removed]

Leave a comment

About brian d foy

user-pic I'm the author of Mastering Perl, and the co-author of Learning Perl (6th Edition), Intermediate Perl, Programming Perl (4th Edition) and Effective Perl Programming (2nd Edition).