[RFA/doc] New Year Procedure

[RFA/doc] New Year Procedure

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 347 bytes --]

A new chapter to document the list of actions that need to be performed
at the start of each new year.

2005-11-22  Joel Brobecker  <brobecker@adacore.com>

        * gdbint.texinfo (Start of New Year Procedure): New chapter

Tested by doing "make all-doc". I checked the HTML result. I also
did a "make pdf" and checked the result too.

-- 
Joel

[-- Attachment #2: ny.diff --]
[-- Type: text/plain, Size: 1490 bytes --]

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.230
diff -u -p -r1.230 gdbint.texinfo
--- gdbint.texinfo	10 Apr 2005 21:20:27 -0000	1.230
+++ gdbint.texinfo	22 Nov 2005 19:54:22 -0000
@@ -86,6 +86,7 @@ as the mechanisms that adapt @value{GDBN
 * Coding::
 * Porting GDB::
 * Versions and Branches::
+* Start of New Year Procedure::
 * Releasing GDB::
 * Testsuite::
 * Hints::
@@ -5598,6 +5599,32 @@ merge.
 For further information on @sc{cvs}, see
 @uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
  
+@node Start of New Year Procedure
+@chapter Start of New Year Procedure
+
+At the start of each new year, the following actions should be performed:
+
+@itemize @bullet
+@item Rotate the ChangeLog file
+
+The current @file{ChangeLog} file should be renamed into
+@file{ChangeLog-YYYY} where YYYY is the year that has just passed.
+A new @file{ChangeLog} file should be created, and its contents should
+contain a reference to the previous ChangeLog. The following should
+also be preserved at the end of the new ChangeLog:
+@smallexample
+Local Variables:
+mode: change-log
+left-margin: 8
+fill-column: 74
+version-control: never
+End:
+@end smallexample
+@item Update the copyright year in the startup message
+
+Update the copyright year in @file{top.c}:@code{print_gdb_version}.
+@end itemize
+
 @node Releasing GDB
 
 @chapter Releasing @value{GDBN}

Re: [RFA/doc] New Year Procedure

[Eli Zaretskii]

> Date: Tue, 22 Nov 2005 11:56:36 -0800
> From: Joel Brobecker <brobecker@adacore.com>
> 
> A new chapter to document the list of actions that need to be performed
> at the start of each new year.

Thanks.

> 2005-11-22  Joel Brobecker  <brobecker@adacore.com>
> 
>         * gdbint.texinfo (Start of New Year Procedure): New chapter

Please add a period at the end of this line.

> +@node Start of New Year Procedure
> +@chapter Start of New Year Procedure

A @cindex entry would be good here.  Think about yourself a year from
now looking for this chapter: typing "i new year RET" inside an Info
reader will land you here with minimum fuss.

> +@itemize @bullet
> +@item Rotate the ChangeLog file

In an @itemize list, @item should be alone on its line, like this:

  @itemize @bullet
  @item
  Rotate the ChangeLog file

> +@smallexample
> +Local Variables:
> +mode: change-log
> +left-margin: 8
> +fill-column: 74
> +version-control: never
> +End:

Perhaps we should say a few words (e.g., in a @footnote) why this
gobbledygook should be in ChangeLog.  Not everyone is an Emacs
junkie ;-)

> +@end smallexample
> +@item Update the copyright year in the startup message

Same here.  Also, please leave one empty line before @item.

> +Update the copyright year in @file{top.c}:@code{print_gdb_version}.

Doesn't this look ugly?  Because @file produces single quotes, so you
get `top.c':`print_gdb_version' in Info and `top.c':print_gdb_version
in print; both aren't pretty, IMHO.

How about simply spelling it out:

  Update the copyright year in @file{top.c}, function
  @code{print_gdb_version}.

Other than that, this can go in.

Re: [RFA/doc] New Year Procedure

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 258 bytes --]

Hi Eli,

I agree with all of your comments. Here is a new patch with all your
recommendations applied.

2005-11-24  Joel Brobecker  <brobecker@adacore.com>

        * gdbint.texinfo (Start of New Year Procedure): New chapter.

OK to apply?

Thanks,
-- 
Joel

[-- Attachment #2: doc.diff --]
[-- Type: text/plain, Size: 1619 bytes --]

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.230
diff -u -p -r1.230 gdbint.texinfo
--- gdbint.texinfo	10 Apr 2005 21:20:27 -0000	1.230
+++ gdbint.texinfo	24 Nov 2005 23:54:50 -0000
@@ -86,6 +86,7 @@ as the mechanisms that adapt @value{GDBN
 * Coding::
 * Porting GDB::
 * Versions and Branches::
+* Start of New Year Procedure::
 * Releasing GDB::
 * Testsuite::
 * Hints::
@@ -5598,6 +5599,38 @@ merge.
 For further information on @sc{cvs}, see
 @uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
  
+@node Start of New Year Procedure
+@chapter Start of New Year Procedure
+@cindex New Year Procedure
+
+At the start of each new year, the following actions should be performed:
+
+@itemize @bullet
+@item
+Rotate the ChangeLog file
+
+The current @file{ChangeLog} file should be renamed into
+@file{ChangeLog-YYYY} where YYYY is the year that has just passed.
+A new @file{ChangeLog} file should be created, and its contents should
+contain a reference to the previous ChangeLog. The following should
+also be preserved at the end of the new ChangeLog, in order to provide
+the appropriate settings when editing this file with emacs:
+@smallexample
+Local Variables:
+mode: change-log
+left-margin: 8
+fill-column: 74
+version-control: never
+End:
+@end smallexample
+
+@item
+Update the copyright year in the startup message
+
+Update the copyright year in file @file{top.c}, function
+@code{print_gdb_version}.
+@end itemize
+
 @node Releasing GDB
 
 @chapter Releasing @value{GDBN}

Re: [RFA/doc] New Year Procedure

[Eli Zaretskii]

> Date: Thu, 24 Nov 2005 15:57:23 -0800
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
> I agree with all of your comments. Here is a new patch with all your
> recommendations applied.
> 
> 2005-11-24  Joel Brobecker  <brobecker@adacore.com>
> 
>         * gdbint.texinfo (Start of New Year Procedure): New chapter.
> 
> OK to apply?

Yes, but please take care of a few more gotchas first ;-)

> +@cindex New Year Procedure

It is a general convention in GNU documentation that index entries
should use lower-case letters.  So "@cindex new year procedure".

> +contain a reference to the previous ChangeLog. The following should
                                                ^^
Please always leave two blanks after a period that ends a sentence.

> +also be preserved at the end of the new ChangeLog, in order to provide
> +the appropriate settings when editing this file with emacs:
                                                        ^^^^^
"Emacs" would be better here, as it's a proper name.

TIA

Re: [RFA/doc] New Year Procedure

[Joel Brobecker]

> > 2005-11-24  Joel Brobecker  <brobecker@adacore.com>
> > 
> >         * gdbint.texinfo (Start of New Year Procedure): New chapter.
> > 
> > OK to apply?
> 
> Yes, but please take care of a few more gotchas first ;-)

Sure. Corrections applied, and patch checked in. Thanks!

-- 
Joel