This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Show diagnostic link format in perldelta template
[perl5.git] / Porting / perldelta_template.pod
index 56f2f50..896a904 100644 (file)
@@ -96,7 +96,8 @@ XXX
 
 =item *
 
-XXX
+    [Verbatim block to avoid creating a bogus link]
+    L<XXX> has been upgraded from version 0.69 to version 0.70.
 
 =back
 
@@ -115,19 +116,13 @@ XXX
 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
 
-[ Within each section, list entries as a =item entry ]
-
 =head2 New Documentation
 
 XXX Changes which create B<new> files in F<pod/> go here.
 
-=over 4
-
-=item L<XXX>
-
-XXX
+=head3 L<XXX>
 
-=back
+XXX Description of the purpose of the new file here
 
 =head2 Changes to Existing Documentation
 
@@ -135,11 +130,13 @@ XXX Changes which significantly change existing files in F<pod/> go here.
 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
 section.
 
+=head3 L<XXX>
+
 =over 4
 
-=item L<XXX>
+=item *
 
-XXX
+XXX Description of the change here
 
 =back
 
@@ -152,17 +149,35 @@ diagnostic messages, see L<perldiag>.
 XXX New or changed warnings emitted by the core's C<C> code go here. Also
 include any changes in L<perldiag> that reconcile it to the C<C> code.
 
-[ Within each section, list entries as a =item entry ]
+[ Within each section, list entries as a =item entry that links to perldiag,
+  e.g.
+
+  =item *
+
+  L<Invalid version object|perldiag/"Invalid version object">
+]
 
 =head2 New Diagnostics
 
 XXX Newly added diagnostic messages go here
 
+=head3 New Errors
+
 =over 4
 
 =item *
 
-XXX
+XXX L<message|perldiag/"message">
+
+=back
+
+=head3 New Warnings
+
+=over 4
+
+=item *
+
+XXX L<message|perldiag/"message">
 
 =back
 
@@ -174,7 +189,7 @@ XXX Changes (i.e. rewording) of diagnostic messages go here
 
 =item *
 
-XXX
+XXX Describe change here
 
 =back
 
@@ -183,12 +198,15 @@ XXX
 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
 here. Most of these are built within the directories F<utils> and F<x2p>.
 
-[ List utility changes as a =item entry.  Use L<XXX> with program names to get
-proper documentation linking. ]
+[ List utility changes as a =head3 entry for each utility and =item
+entries for each change
+Use L<XXX> with program names to get proper documentation linking. ]
+
+=head3 L<XXX>
 
 =over 4
 
-=item L<XXX>
+=item *
 
 XXX
 
@@ -284,7 +302,7 @@ XXX Changes which affect the interface available to C<XS> code go here.
 Other significant internal changes for future core maintainers should
 be noted as well.
 
-[ List each test improvement as a =item entry ]
+[ List each change as a =item entry ]
 
 =over 4
 
@@ -345,7 +363,7 @@ recently posted to the comp.lang.perl.misc newsgroup and the perl
 bug database at http://rt.perl.org/perlbug/ .  There may also be
 information at http://www.perl.org/ , the Perl Home Page.
 
-If you believe you have an unreported bug, please run the B<perlbug>
+If you believe you have an unreported bug, please run the L<perlbug>
 program included with your release.  Be sure to trim your bug down
 to a tiny but sufficient test case.  Your bug report, along with the
 output of C<perl -V>, will be sent off to perlbug@perl.org to be