[patch] Allow full explanation in change log for certain changes

[Thien-Thi Nguyen]

Rationale: We currently urge rationale/why information to be placed
in the comments, and that should not change.  This change maintains
that spirit, giving guidance for cases when "comments in code" is
impossible.

Notes: 

- I discarded the "unwieldly" argument from the rationale since that
  kind of optimization is handled later (node "Simple Changes").
  Anyway, "impossible" is strong enough to stand by itself.

- Moving "in the past" paragraph back serves two purposes: providing
  a foreshadowing (of sorts) for the "no comment syntax" concept;
  and giving it more "high level / introductory" feel rather than
  the current "oh, BTW" feel (improved flow of concepts).  Further
  improvement along these lines would be to simply omit "In the past",
  and reword to positively enumerate those files that deserve change
  log mention.  (I like such historic notes, personally, however.)

Here is a suitable ChangeLog entry:

2012-06-04  Thien-Thi Nguyen  <address@hidden>

        Allow full explanation in change log for certain changes.
        * doc/standards.texi (Change Log Concepts): Define "title";
        move it into initial paragraph.  Move "In the past,
        ... sake of copyright records" paragraph earlier.
        Restrict disdain for full explanation to changes in code.
        Add paragraph allowing full explanation for files that
        have no comment syntax.

Here is the diff:

 doc/standards.texi |   21 ++++++++++++++-------
 1 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/doc/standards.texi b/doc/standards.texi
index 60a0ea2..9ddd68c 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3541,6 +3541,14 @@ @node Change Log Concepts
 a change log describes either an individual change or the smallest
 batch of changes that belong together, also known as a @dfn{change
 set}.
address@hidden title, change log entry
+For later reference or for summarizing, sometimes it is useful to start the
+entry with a one-line @dfn{title} to describe its overall purpose.
+
+In the past, we recommended not mentioning changes in non-software
+files (manuals, help files, media files, etc.)@: in change logs.
+However, we've been advised that it is a good idea to include them,
+for the sake of copyright records.

 The change log file is normally called @file{ChangeLog} and covers an
 entire directory.  Each directory can have its own change log, or a
@@ -3552,9 +3560,9 @@ @node Change Log Concepts
 to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
 @kbd{C-x v a} (@code{vc-update-change-log}) does the job.

-There's no need to describe the full purpose of the changes or how
-they work together.  However, sometimes it is useful to write one line
-to describe the overall purpose of a change log entry.  If
+For changes to code, there's no need to describe the full purpose of the
+changes or how they work together.
+If
 you think that a change calls for explanation, you're probably right.
 Please do explain it---but please put the full explanation in comments
 in the code, where people will see it whenever they see the code.  For
@@ -3562,10 +3570,9 @@ @node Change Log Concepts
 function, because there should be a comment before the function
 definition to explain what it does.

-In the past, we recommended not mentioning changes in non-software
-files (manuals, help files, media files, etc.)@: in change logs.
-However, we've been advised that it is a good idea to include them,
-for the sake of copyright records.
+For changes to files that do not support comment syntax (e.g., media
+files), it is OK to include the full explanation in the change log file,
+after the title and before the list of individual changes.

 The easiest way to add an entry to @file{ChangeLog} is with the Emacs
 command @kbd{M-x add-change-log-entry}.  An individual change should