Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Named subsections in perlref #16829

Closed
p5pRT opened this issue Jan 29, 2019 · 12 comments
Closed

Named subsections in perlref #16829

p5pRT opened this issue Jan 29, 2019 · 12 comments

Comments

@p5pRT
Copy link

p5pRT commented Jan 29, 2019

Migrated from rt.perl.org#133805 (status was 'open')

Searchable as RT133805$

@p5pRT
Copy link
Author

p5pRT commented Jan 29, 2019

From @Grinnz

The perlref documentation contains two numbered lists, which are really
sequences of documentation on distinct subjects or components, and so it is
reasonable to look for or link to these subsections directly. To facilitate
this, the to-be-attached patch will change the ordered lists into named
headings, with two effects as viewed on https://perldoc.pl/perlref and
https://metacpan.org/pod/perlref.

1. Changing the subsections to proper headings adds them to the table of
contents, making them more discoverable, and the sections more easily
linkable by a recognizable name. The table of contents is quite small
currently so I don't believe this will cause undue clutter.

2. The second list (under heading "Using References") is not currently
linkable at all, as it gets rendered differently, presumably out of the
requirement of the following set of paragraphs that are not part of the
list. As part of this patch, the following paragraphs are placed under a
new "Miscellanous Usage" heading.

-Dan

(Perl)

@p5pRT
Copy link
Author

p5pRT commented Jan 29, 2019

From @Grinnz

Patch is attached.

@p5pRT
Copy link
Author

p5pRT commented Jan 29, 2019

From @Grinnz

perlref_subsections.patch
diff --git a/pod/perlref.pod b/pod/perlref.pod
index 4982b65c8d..2c4cedfe64 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -56,9 +56,7 @@ X<reference, creation> X<referencing>
 
 References can be created in several ways.
 
-=over 4
-
-=item 1.
+=head3 Backslash Operator
 X<\> X<backslash>
 
 By using the backslash operator on a variable, subroutine, or value.
@@ -80,7 +78,7 @@ reference to a typeglob, which is actually a complete symbol table entry.
 But see the explanation of the C<*foo{THING}> syntax below.  However,
 you can still use type globs and globrefs as though they were IO handles.
 
-=item 2.
+=head3 Square Brackets
 X<array, anonymous> X<[> X<[]> X<square bracket>
 X<bracket, square> X<arrayref> X<array reference> X<reference, array>
 
@@ -107,7 +105,7 @@ of C<@foo>, not a reference to C<@foo> itself.  Likewise for C<%foo>,
 except that the key references are to copies (since the keys are just
 strings rather than full-fledged scalars).
 
-=item 3.
+=head3 Curly Brackets
 X<hash, anonymous> X<{> X<{}> X<curly bracket>
 X<bracket, curly> X<brace> X<hashref> X<hash reference> X<reference, hash>
 
@@ -150,7 +148,7 @@ On the other hand, if you want the other meaning, you can do this:
 The leading C<+{> and C<{;> always serve to disambiguate
 the expression to mean either the HASH reference, or the BLOCK.
 
-=item 4.
+=head3 Anonymous Subroutines
 X<subroutine, anonymous> X<subroutine, reference> X<reference, subroutine>
 X<scope, lexical> X<closure> X<lexical> X<lexical scope>
 
@@ -208,7 +206,7 @@ This applies only to lexical variables, by the way.  Dynamic variables
 continue to work as they have always worked.  Closure is not something
 that most Perl programmers need trouble themselves about to begin with.
 
-=item 5.
+=head3 Constructors
 X<constructor> X<new>
 
 References are often returned by special subroutines called constructors.  Perl
@@ -234,14 +232,14 @@ better to use the direct method invocation approach:
     $menubar = $main->Frame(-relief              => "raised",
                             -borderwidth         => 2)
 
-=item 6.
+=head3 Autovivification
 X<autovivification>
 
 References of the appropriate type can spring into existence if you
 dereference them in a context that assumes they exist.  Because we haven't
 talked about dereferencing yet, we can't show you any examples yet.
 
-=item 7.
+=head3 Typeglob Slots
 X<*foo{THING}> X<*>
 
 A reference can be created by using a special syntax, lovingly known as
@@ -307,8 +305,6 @@ below, there's no risk of that happening.
         return scalar <$fh>;
     }
 
-=back
-
 =head2 Using References
 X<reference, use> X<dereferencing> X<dereference>
 
@@ -316,9 +312,7 @@ That's it for creating references.  By now you're probably dying to
 know how to use references to get back to your long-lost data.  There
 are several basic methods.
 
-=over 4
-
-=item 1.
+=head3 Simple Scalar
 
 Anywhere you'd put an identifier (or chain of identifiers) as part
 of a variable or subroutine name, you can replace the identifier with
@@ -341,7 +335,7 @@ However, a "simple scalar" includes an identifier that itself uses method
     $refrefref = \\\"howdy";
     print $$$$refrefref;
 
-=item 2.
+=head3 Block
 
 Anywhere you'd put an identifier (or chain of identifiers) as part of a
 variable or subroutine name, you can replace the identifier with a
@@ -377,7 +371,7 @@ Case 2 is also deceptive in that you're accessing a variable
 called %hashref, not dereferencing through $hashref to the hash
 it's presumably referencing.  That would be case 3.
 
-=item 3.
+=head3 Arrow Notation
 
 Subroutine calls and lookups of individual array elements arise often
 enough that it gets cumbersome to use method 2.  As a form of
@@ -414,7 +408,7 @@ multidimensional arrays just like C's:
 Well, okay, not entirely like C's arrays, actually.  C doesn't know how
 to grow its arrays on demand.  Perl does.
 
-=item 4.
+=head3 Objects
 
 If a reference happens to be a reference to an object, then there are
 probably methods to access the things referred to, and you should probably
@@ -424,7 +418,7 @@ encapsulation without a very good reason.  Perl does not enforce
 encapsulation.  We are not totalitarians here.  We do expect some basic
 civility though.
 
-=back
+=head3 Miscellaneous Usage
 
 Using a string or number as a reference produces a symbolic reference,
 as explained above.  Using a reference as a number produces an

@p5pRT
Copy link
Author

p5pRT commented Oct 13, 2019

From @jkeenan

On Tue, 29 Jan 2019 02​:25​:05 GMT, grinnz@​gmail.com wrote​:

Patch is attached.

I created a local branch and tried to apply your patch using 'git am'. The 'am' did not succeed.

#####
$ git am < ~/learn/perl/p5p/133805-perlref_subsections.patch
Applying​:
fatal​: empty ident name (for <>) not allowed
#####

Can you investigate?

Thank you very much.
--
James E Keenan (jkeenan@​cpan.org)

@p5pRT
Copy link
Author

p5pRT commented Oct 13, 2019

The RT System itself - Status changed from 'new' to 'open'

@p5pRT
Copy link
Author

p5pRT commented Oct 13, 2019

From @Grinnz

On Sun, 13 Oct 2019 11​:23​:10 -0700, jkeenan wrote​:

On Tue, 29 Jan 2019 02​:25​:05 GMT, grinnz@​gmail.com wrote​:

Patch is attached.

I created a local branch and tried to apply your patch using 'git am'.
The 'am' did not succeed.

#####
$ git am < ~/learn/perl/p5p/133805-perlref_subsections.patch
Applying​:
fatal​: empty ident name (for <>) not allowed
#####

Can you investigate?

Thank you very much.

As described by https://stackoverflow.com/a/41833403/5848200 this is because it's a bare patch and not a commit. I will recreate it using format-patch.

-Dan

@p5pRT
Copy link
Author

p5pRT commented Oct 13, 2019

From @Grinnz

On Sun, 13 Oct 2019 11​:27​:29 -0700, grinnz@​gmail.com wrote​:

On Sun, 13 Oct 2019 11​:23​:10 -0700, jkeenan wrote​:

On Tue, 29 Jan 2019 02​:25​:05 GMT, grinnz@​gmail.com wrote​:

Patch is attached.

I created a local branch and tried to apply your patch using 'git
am'.
The 'am' did not succeed.

#####
$ git am < ~/learn/perl/p5p/133805-perlref_subsections.patch
Applying​:
fatal​: empty ident name (for <>) not allowed
#####

Can you investigate?

Thank you very much.

As described by https://stackoverflow.com/a/41833403/5848200 this is
because it's a bare patch and not a commit. I will recreate it using
format-patch.

-Dan

Attached

@p5pRT
Copy link
Author

p5pRT commented Oct 13, 2019

From @Grinnz

0001-perlref-subsections.patch
From 93f19913ec341433c079fcedc91333fe4caf44e1 Mon Sep 17 00:00:00 2001
From: Dan Book <grinnz@grinnz.com>
Date: Mon, 28 Jan 2019 21:14:48 -0500
Subject: [PATCH] Assign names to subsections in perlref to improve linkability
 and discoverability

---
 pod/perlref.pod | 30 ++++++++++++------------------
 1 file changed, 12 insertions(+), 18 deletions(-)

diff --git a/pod/perlref.pod b/pod/perlref.pod
index 4982b65c8d..2c4cedfe64 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -56,9 +56,7 @@ X<reference, creation> X<referencing>
 
 References can be created in several ways.
 
-=over 4
-
-=item 1.
+=head3 Backslash Operator
 X<\> X<backslash>
 
 By using the backslash operator on a variable, subroutine, or value.
@@ -80,7 +78,7 @@ reference to a typeglob, which is actually a complete symbol table entry.
 But see the explanation of the C<*foo{THING}> syntax below.  However,
 you can still use type globs and globrefs as though they were IO handles.
 
-=item 2.
+=head3 Square Brackets
 X<array, anonymous> X<[> X<[]> X<square bracket>
 X<bracket, square> X<arrayref> X<array reference> X<reference, array>
 
@@ -107,7 +105,7 @@ of C<@foo>, not a reference to C<@foo> itself.  Likewise for C<%foo>,
 except that the key references are to copies (since the keys are just
 strings rather than full-fledged scalars).
 
-=item 3.
+=head3 Curly Brackets
 X<hash, anonymous> X<{> X<{}> X<curly bracket>
 X<bracket, curly> X<brace> X<hashref> X<hash reference> X<reference, hash>
 
@@ -150,7 +148,7 @@ On the other hand, if you want the other meaning, you can do this:
 The leading C<+{> and C<{;> always serve to disambiguate
 the expression to mean either the HASH reference, or the BLOCK.
 
-=item 4.
+=head3 Anonymous Subroutines
 X<subroutine, anonymous> X<subroutine, reference> X<reference, subroutine>
 X<scope, lexical> X<closure> X<lexical> X<lexical scope>
 
@@ -208,7 +206,7 @@ This applies only to lexical variables, by the way.  Dynamic variables
 continue to work as they have always worked.  Closure is not something
 that most Perl programmers need trouble themselves about to begin with.
 
-=item 5.
+=head3 Constructors
 X<constructor> X<new>
 
 References are often returned by special subroutines called constructors.  Perl
@@ -234,14 +232,14 @@ better to use the direct method invocation approach:
     $menubar = $main->Frame(-relief              => "raised",
                             -borderwidth         => 2)
 
-=item 6.
+=head3 Autovivification
 X<autovivification>
 
 References of the appropriate type can spring into existence if you
 dereference them in a context that assumes they exist.  Because we haven't
 talked about dereferencing yet, we can't show you any examples yet.
 
-=item 7.
+=head3 Typeglob Slots
 X<*foo{THING}> X<*>
 
 A reference can be created by using a special syntax, lovingly known as
@@ -307,8 +305,6 @@ below, there's no risk of that happening.
         return scalar <$fh>;
     }
 
-=back
-
 =head2 Using References
 X<reference, use> X<dereferencing> X<dereference>
 
@@ -316,9 +312,7 @@ That's it for creating references.  By now you're probably dying to
 know how to use references to get back to your long-lost data.  There
 are several basic methods.
 
-=over 4
-
-=item 1.
+=head3 Simple Scalar
 
 Anywhere you'd put an identifier (or chain of identifiers) as part
 of a variable or subroutine name, you can replace the identifier with
@@ -341,7 +335,7 @@ However, a "simple scalar" includes an identifier that itself uses method
     $refrefref = \\\"howdy";
     print $$$$refrefref;
 
-=item 2.
+=head3 Block
 
 Anywhere you'd put an identifier (or chain of identifiers) as part of a
 variable or subroutine name, you can replace the identifier with a
@@ -377,7 +371,7 @@ Case 2 is also deceptive in that you're accessing a variable
 called %hashref, not dereferencing through $hashref to the hash
 it's presumably referencing.  That would be case 3.
 
-=item 3.
+=head3 Arrow Notation
 
 Subroutine calls and lookups of individual array elements arise often
 enough that it gets cumbersome to use method 2.  As a form of
@@ -414,7 +408,7 @@ multidimensional arrays just like C's:
 Well, okay, not entirely like C's arrays, actually.  C doesn't know how
 to grow its arrays on demand.  Perl does.
 
-=item 4.
+=head3 Objects
 
 If a reference happens to be a reference to an object, then there are
 probably methods to access the things referred to, and you should probably
@@ -424,7 +418,7 @@ encapsulation without a very good reason.  Perl does not enforce
 encapsulation.  We are not totalitarians here.  We do expect some basic
 civility though.
 
-=back
+=head3 Miscellaneous Usage
 
 Using a string or number as a reference produces a symbolic reference,
 as explained above.  Using a reference as a number produces an
-- 
2.20.1

@p5pRT
Copy link
Author

p5pRT commented Oct 13, 2019

From @jkeenan

On Sun, 13 Oct 2019 18​:31​:39 GMT, grinnz@​gmail.com wrote​:

On Sun, 13 Oct 2019 11​:27​:29 -0700, grinnz@​gmail.com wrote​:

On Sun, 13 Oct 2019 11​:23​:10 -0700, jkeenan wrote​:

On Tue, 29 Jan 2019 02​:25​:05 GMT, grinnz@​gmail.com wrote​:

Patch is attached.

I created a local branch and tried to apply your patch using 'git
am'.
The 'am' did not succeed.

#####
$ git am < ~/learn/perl/p5p/133805-perlref_subsections.patch
Applying​:
fatal​: empty ident name (for <>) not allowed
#####

Can you investigate?

Thank you very much.

As described by https://stackoverflow.com/a/41833403/5848200 this is
because it's a bare patch and not a commit. I will recreate it using
format-patch.

-Dan

Attached

Thanks. I'll try this again this evening.

--
James E Keenan (jkeenan@​cpan.org)

@p5pRT
Copy link
Author

p5pRT commented Oct 14, 2019

From @jkeenan

On Sun, 13 Oct 2019 18​:31​:39 GMT, grinnz@​gmail.com wrote​:

On Sun, 13 Oct 2019 11​:27​:29 -0700, grinnz@​gmail.com wrote​:

On Sun, 13 Oct 2019 11​:23​:10 -0700, jkeenan wrote​:

On Tue, 29 Jan 2019 02​:25​:05 GMT, grinnz@​gmail.com wrote​:

Patch is attached.

I created a local branch and tried to apply your patch using 'git
am'.
The 'am' did not succeed.

#####
$ git am < ~/learn/perl/p5p/133805-perlref_subsections.patch
Applying​:
fatal​: empty ident name (for <>) not allowed
#####

Can you investigate?

Thank you very much.

As described by https://stackoverflow.com/a/41833403/5848200 this is
because it's a bare patch and not a commit. I will recreate it using
format-patch.

-Dan

Attached

+1 for me on this reformatting.

--
James E Keenan (jkeenan@​cpan.org)

@toddr
Copy link
Member

toddr commented Oct 21, 2019

@Grinnz can we have a PR pls?

@toddr
Copy link
Member

toddr commented Oct 24, 2019

I assume the PR being merged means we're good to close?

@toddr toddr closed this as completed Oct 24, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants