diff --git a/standards.texi b/standards.texi index d808af0b56..c685dee9ca 100644 --- a/standards.texi +++ b/standards.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c %**start of header -@setfilename standards.text +@setfilename standards.info @settitle GNU Coding Standards @c %**end of header @@ -34,7 +34,7 @@ by the Free Software Foundation. @sp 10 @titlefont{GNU Coding Standards} @author{Richard Stallman} -@author{last updated 1 Jul 1992} +@author{last updated 16 Jul 1992} @c Note date also appears below. @page @@ -60,7 +60,7 @@ by Free Software Foundation. @node Top, Reading Non-Free Code, (dir), (dir) @top Version -Last updated 1 Jul 1992. +Last updated 16 Jul 1992. @c Note date also appears above. @end ifinfo @@ -202,6 +202,12 @@ comment with the function in the source to explain what it does. However, sometimes it is useful to write one line to describe the overall purpose of a large batch of changes. +You can think of the change log as a conceptual ``undo list'' which +explains how earlier versions were different from the current version. +People can see the current version; they don't need the change log +to tell them what is in it. What they want from a change log is a +clear explanation of how the earlier version differed. + When you change the calling sequence of a function in a simple fashion, and you change all the callers of the function, there is no need to make individual entries for all the callers. Just write in @@ -1252,12 +1258,20 @@ fit any naming convention. @chapter Portability As It Applies to GNU Much of what is called ``portability'' in the Unix world refers to -porting to different Unix versions. This is not relevant to GNU -software, because its purpose is to run on top of one and only -one kernel, the GNU kernel, compiled with one and only one C -compiler, the GNU C compiler. The amount and kinds of variation -among GNU systems on different cpu's will be like the variation -among Berkeley 4.3 systems on different cpu's. +porting to different Unix versions. This is a secondary consideration +for GNU software, because its primary purpose is to run on top of one +and only one kernel, the GNU kernel, compiled with one and only one C +compiler, the GNU C compiler. The amount and kinds of variation among +GNU systems on different cpu's will be like the variation among Berkeley +4.3 systems on different cpu's. + +All users today run GNU software on non-GNU systems. So supporting a +variety of non-GNU systems is desirable; simply not paramount. +The easiest way to achieve portability to a reasonable range of systems +is to use Autoconf. It's unlikely that your program needs to know more +information about the host machine than Autoconf can provide, simply +because most of the programs that need such knowledge have already been +written. It is difficult to be sure exactly what facilities the GNU kernel will provide, since it isn't finished yet. Therefore, assume you can @@ -1348,10 +1362,9 @@ option usage information. Please use Texinfo for documenting GNU programs. See the Texinfo manual, either the hardcopy or the version in the GNU Emacs Info -sub-system (@kbd{C-h i}). - -See existing GNU texinfo files (e.g. those under the @file{man/} -directory in the GNU Emacs Distribution) for examples. +subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g. those +under the @file{man/} directory in the GNU Emacs Distribution) for +examples. The title page of the manual should state the version of the program which the manual applies to. The Top node of the manual should also @@ -1366,6 +1379,12 @@ concepts a user will have before reaching that point in the manual. Address the goals that a user will have in mind, and explain how to accomplish them. +In addition to its manual, the package should have a file named +@file{NEWS} which contains a list of user-visible changes worth +mentioning. In each new release, add items to the front of the file, +and identify the version they pertain to. Don't discard old items. +This way, a user upgrading from any previous version can see what +is new. @node Releases @chapter Making Releases