perl: link between related or revised features

diff --git a/perl.inc.pl b/perl.inc.pl
index 6ab2fdf232639952d7f3bb6676a3ec94e6f7f6c4..faf530eb1bf213d013668e670badde7612e5f74c 100644 (file)
--- a/perl.inc.pl
+++ b/perl.inc.pl
@@ -29,13 +29,13 @@ use utf8;
 
        v5.6 => {
                new => [
-                       ['<code>use warnings</code>', 'pragma to enable warnings in lexical scope'],
-                       ['<code>use utf8</code>', 'experimental unicode semantics <small>(completed in v5.8)</small>', {experimental => 0, stable => v5.8}],
+                       ['<code>use warnings</code>', 'pragma to enable warnings in lexical scope', {name => 'warnings'}],
+                       ['<code>use utf8</code>', 'experimental unicode semantics <small>(completed in <a href="#utf8_data">v5.8</a>)</small>', {name => 'utf8', experimental => 0, stable => v5.8}],
                        ['<code>use charnames</code>', 'string escape <code>\N{}</code> to insert named character'],
                        ['<code>our</code>', 'declare global variables'],
                        ['<code>v1.2.3</code>', q"represent strings as vector of ordinals, useful in version numbers (<code>printf '%vd'</code> to display)"],
                        ['<code>0b0</code>', q"binary numbers in literals, <code>printf '%b'</code>, and <code>oct</code>"],
-                       ['<code>sub :lvalue</code>', 'subroutine attribute to return a modifiable value', {experimental => 0, stable => v5.20}],
+                       ['<code>sub :lvalue</code>', 'subroutine attribute to return a modifiable value', {name => 'sub_lvalue', experimental => 0, stable => v5.20}],
 #                      ['<code>sub :locked :method</code>', 'syntax to declare subroutine attributes'], # can be inferred from :lvalue support
                        ['<code>open my $fh, $mode, $expr</code>', 'file handles in scoped scalars, third argument for unambiguous file name'],
                        [q"<code>pack 'q'</code>", '64-bit integer support (also large files &gt;2GiB)', {experimental => 0, stable => v5.8.1}],
@@ -58,8 +58,8 @@ use utf8;
 
        v5.8 => {
                new => [
-                       [q"<code>no utf8</code>", 'full unicode support, <code>utf8</code> pragma only for script encoding'],
-                       [q"<code>binmode $fh, ':perlio'</code>", 'file handle behaviour altered by PerlIO layers'],
+                       [q"<code>no utf8</code>", 'full unicode support, <code>utf8</code> pragma only for script encoding', {name => 'utf8_data'}],
+                       [q"<code>binmode $fh, ':perlio'</code>", 'file handle behaviour altered by PerlIO layers', {name => 'perlio'}],
                        [q"<code>open $fh, '-|', @cmd</code>", 'open list to fork a command without spawning a shell'],
                        [q"<code>open $fh, '>', \$var</code>", 'perl scalars as virtual files'],
                        [q"<code>printf '%1$s', @args</code>", 'syntax to use parameters out of order'],
@@ -88,7 +88,7 @@ use utf8;
                        ['<code>//</code>', 'defined-or operator'],
                        ['<code>~~</code>', 'smart-match operator to compare different data types <small>(updated in v5.10.1)</small>', {experimental => 'smartmatch'}],
                        ['<code>say</code>', 'print with newline, equivalent to <code>print @_, "\n"</code>', {feature => 'say'}],
-                       ['<code>given</code>', 'switch statement to smart-match with <code>when</code>/<code>default</code>', {feature => 'switch', experimental => 'smartmatch'}],
+                       ['<code>given</code>', 'switch statement to smart-match with <code>when</code>/<code>default</code>', {name => 'switch', feature => 'switch', experimental => 'smartmatch'}],
                        ['<code>/(?&lt;name>)/</code>', 'named capture buffers into <code>%+</code>'],
                        ['<code>/(?1)/</code>', 'recursive regular expression patterns'],
                        ['<code>/(?|)/</code>', 'resets capture numbering for each contained branch'],
@@ -97,7 +97,7 @@ use utf8;
                        ['<code>/p</code>', 'optionally preserve <code>${^MATCH}</code> variables (avoiding <code>$&</code> penalty until COW in v5.20)'],
                        ['<code>/\v/, /\h/</code>', 'vertical and horizontal whitespace escapes (<code>\V</code> <code>\H</code> to invert); also <code>/\R/</code> for newlines'],
                        ['<code>my $_</code>', 'lexically scoped version of the default variable', {experimental => 'lexical_topic', dropped => v5.23.4}],
-                       ['<code>state</code>', 'persistent <code>my</code> variables', {feature => 'state'}],
+                       ['<code>state</code>', 'persistent <code>my</code> variables (scalars only until <a href="#state_ext">5.28</a>)', {feature => 'state'}],
                ],
                release => '2007-12-18',
                distro => {
@@ -122,6 +122,7 @@ use utf8;
                        ['<code>… when</code>', '<code>when</code> is now allowed to be used as a statement modifier'],
                        [q"<code>use overload 'qr'</code>", 'customisable conversion to regular expressions'],
                        ['<code>/\N/</code>', 'inverse \n to match any character except newline regardless of <code>/s</code>', {experimental => 0, stable => v5.18}],
+                       ['<code>each $ref</code> e.a.', 'array and hash container functions accept references', {experimental => 'autoderef', dropped => v5.23.1}],
                ],
                release => '2010-04-12',
                unicode => '5.2',
@@ -141,7 +142,6 @@ use utf8;
                        ['<code>/dalu</code>', 'regexp modifiers to restrict character classes: either <strong>d</strong>efault, <strong>a</strong>scii, <strong>l</strong>ocale, or <strong>u</strong>nicode semantics.'],
                        [q"<code>use re '/flags'</code>", 'customise default modifiers'],
                        ['<code>/(?^)/</code>', 'construct to reset to default modifiers'],
-                       ['<code>each $ref</code> e.a.', 'array and hash container functions accept references', {experimental => 'postderef', dropped => v5.23.1}],
                        ['<code>FH->method</code>', 'filehandle method calls load IO::File on demand (eg. <code>STDOUT->flush</code>)'],
                        ['<code>\o{}</code>', 'escape sequence for octal values beyond \777'],
                ],
@@ -263,7 +263,7 @@ use utf8;
                        ['<code>delete %hash{…}</code>', 'hash slices can be deleted with key+value pairs'],
                        ['<code>/(*…)/</code>', 'alphabetic synonyms for assertions, e.g. <code>(*atomic:…)</code> for <code>(?&gt;…)</code> and <code>(*nlb:…)</code> for <code>(?&lt;!…)</code>', {experimental => 'alpha_assertions', stable => v5.31.6}],
                        ['<code>/(*script_run:)/</code>', 'enforces all characters to be from the same script', {experimental => 'script_run', stable => v5.31.6}],
-                       ['<code>state @a</code>', 'persistent lexical array or hash variables'],
+                       ['<code>state @a</code>', 'persistent lexical array or hash variables (in addition to <a href="#state">scalars</a>)', {name => 'state_ext'}],
                        ['perl<code> -i -pe die</code>', 'safe in-place editing: files are replaced only after successful completion'],
                        ['<code>${^SAFE_LOCALES}</code>', 'locales are thread-safe on supported systems, indicated by this variable'],
                ],
@@ -281,8 +281,8 @@ use utf8;
                new => [
                        ['<code>/(?<=var+)</code>', 'variable length lookbehind assertions', {experimental => 'vlb', stable => v5.36}],
                        ['<code>m(\p{nv=/.*/})</code>', 'match unicode properties by regular expressions', {experimental => 'uniprop_wildcards'}],
-                       ['<code><s>my $state if 0</s></code>', 'workaround for <code>state</code> (deprecated since v5.10!) is now prohibited'],
-                       [q"<code>qr'\N'</code>", 'Delimiters must be graphemes; unescaped { illegal; \N in single quotes'],
+                       ['<code><s>my $state if 0</s></code>', 'workaround for <code><a href="#state">state</a></code> (deprecated since v5.10!) is now prohibited'],
+                       [q"<code>qr'\N'</code>", 'Delimiters must be graphemes; unescaped <code>{</code> illegal; <code>\N</code> in single quotes'],
                ],
                unicode => '12.1',
                release => '2019-05-22',
@@ -295,7 +295,7 @@ use utf8;
                new => [
                        ['<code>isa</code>', 'infix operator to check class instance', {feature => 'isa', experimental => 'isa', stable => v5.36}],
                        ['<code>$min &lt; $_ &lt;= $max</code>', 'chained comparison repeats inner part as <code>$min &lt; $_ and $_ &lt;= $max</code>'],
-                       ['<code>/\p{Name=$var}/</code>', 'match Unicode Name property like \N{} but with interpolation and subpatterns'],
+                       ['<code>/\p{Name=$var}/</code>', 'match Unicode Name property like <code>\N{}</code> but with interpolation and subpatterns'],
                        [q"<code>open F, '+&gt;&gt;', undef</code>", 'respect append mode on temporary files with mixed access'],
                        ["<code>no feature 'indirect'</code>", 'disable indirect object notation such as <code>new Class</code> instead of <code>Class-&gt;new</code>'],
                        ['streamzip', 'program distributed with core IO::Compress::Base to compress stdin into a zip container'],
@@ -333,13 +333,13 @@ use utf8;
                new => [
                        ['<code>use v5.36</code>', "use <code>warnings</code>; use feature qw'<code>signatures isa</code>'; no feature qw'<code>indirect multidimensional switch</code>'"],
                        ['<code>use builtin</code>', 'namespace for interpreter functions, such as <code>weaken</code> and <code>blessed</code> from <code>Scalar::Util</code>, <code>ceil</code>/<code>floor</code> from <code>POSIX</code>, and <code>trim</code> like <code>String::Util</code>', {experimental => 'builtin'}],
-                       ['<code>is_bool(!0)</code>', 'distinguish scalar variable types (by <code>builtin</code> functions) for data interoperability'],
+                       ['<code>is_bool(!0)</code>', 'distinguish scalar variable types (by <code>builtin</code> functions) for data interoperability', {name => 'is_bool'}],
                        ['<code>for my ($k, $v) (%hash)</code>', 'iterate over multiple values at a time (including <code>builtin::indexed</code> for arrays)', {experimental => 'for_list', feature => 'for_list'}],
                        ['<code>defer {}</code>', 'queue code to be executed when going out of scope', {feature => 'defer', experimental => 'defer'}],
-                       ['<code>try {} finally {}</code>', 'run code at the end of a <code>try</code> construct regardless of failure', {feature => 'try', experimental => 'try'}],
+                       ['<code>try {} finally {}</code>', 'run code at the end of a <code><a href="#try">try</a></code> construct regardless of failure', {name => 'finally', feature => 'try', experimental => 'try'}],
                        ['<code>q«…»</code>', 'unicode delimiters for quoting operators', {experimental => 'extra_paired_delimiters'}],
-                       ['<code>sub ($var) {!<s>pop</s>}</code>', 'signatured subs are stable, but mixing with the arguments array <code>@_</code> remains experimental', {feature => 'signatures', experimental => 'args_array_with_signatures'}],
-                       ['<code>$SIG{FPE}</code>', 'floating-point exceptions no longer deferred but delivered immediately like other signals'],
+                       ['<code>sub ($var) {!<s>pop</s>}</code>', '<a href="#signatures">signature</a>d subs are stable, but mixing with the arguments array <code>@_</code> remains experimental', {feature => 'signatures', experimental => 'args_array_with_signatures'}],
+                       ['<code>$SIG{FPE}</code>', 'floating-point exceptions no longer deferred but delivered immediately like other signals', {name => 'sig_fpe'}],
                        ['perl<code> -g</code>', 'disable input record separator (slurp mode), alias for <code>-0777</code>'],
                ],
                unicode => '14.0',

diff --git a/perl.plp b/perl.plp
index c36f5e8cf75c0ba9eda2112ed5d121797270fb85..02d034869ae7f7ee89c0c9aa8cc3ae30f014df75 100644 (file)
--- a/perl.plp
+++ b/perl.plp
@@ -100,15 +100,18 @@ for my $vernum (reverse sort keys %{$info}) {
                        if ($attr->{experimental}) {
                                $title = sprintf '<span title="experimental::%s">%s</span>',
                                        $attr->{experimental}, $title;
+                               $attr->{name} //= $attr->{experimental};
                        }
                        if ($attr->{feature}) {
                                my $prefix = sprintf '<span title="%s">feature</span>',
                                        $attr->{feature};
                                $title = join ', ', $prefix, $title // ();
+                               $attr->{name} //= $attr->{feature};
                        }
-                       $desc .= sprintf ' <em class="ex">(%s)</em>', $title;
+                       $desc .= sprintf ' <em class="ex">(%s)</em>', $title if $title;
                }
-               say sprintf '<dt>%s<dd>%s', $topic, $desc || '<br/>';
+               my $ref = defined $attr->{name} && sprintf ' id="%s"', $attr->{name};
+               say sprintf '<dt%s>%s<dd>%s', $ref, $topic, $desc || '<br/>';
        }
        say sprintf '<dt>Unicode</dt><dd>v%s', $_ for $verrow->{unicode} || ();
        say '</dl>';