@setfilename standards.info
@settitle GNU Coding Standards
@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
-@set lastupdate 20 April 1997
+@set lastupdate 6 May 1997
@c %**end of header
@ifinfo
* Managing Releases:: The Release Process
@end menu
-@node Preface, Intellectual Property, Top, Top
+@node Preface
@chapter About the GNU Coding Standards
The GNU Coding Standards were written by Richard Stallman and other GNU
This release of the GNU Coding Standards was last updated
@value{lastupdate}.
-@node Intellectual Property, Design Advice, Preface, Top
+@node Intellectual Property
@chapter Keeping Free Software Free
This @value{CHAPTER} discusses how you can make sure that GNU software
* Contributions:: Accepting Contributions
@end menu
-@node Reading Non-Free Code, Contributions, Intellectual Property, Intellectual Property
+@node Reading Non-Free Code
@section Referring to Proprietary Programs
Don't in any circumstances refer to Unix source code for or during
to free memory, or use a new GNU facility such as obstacks.
-@node Contributions, , Reading Non-Free Code, Intellectual Property
+@node Contributions
@section Accepting Contributions
If someone else sends you a piece of code to add to the program you are
reached the stage of actually maintaining a program for GNU (whether
released or not), please ask us for a copy.
-@node Design Advice, Program Behavior, Intellectual Property, Top
+@node Design Advice
@chapter General Program Design
This @value{CHAPTER} discusses some of the issues you should take into
* Source Language:: Using languages other than C
@end menu
-@node Compatibility, Using Extensions, Design Advice, Design Advice
+@node Compatibility
@section Compatibility with Other Implementations
With occasional exceptions, utility programs and libraries for GNU
but our first priority is usually to duplicate what Unix already
has.
-@node Using Extensions, ANSI C, Compatibility, Design Advice
+@node Using Extensions
@section Using Non-standard Features
Many GNU facilities that already exist support a number of convenient
the GNU compiler, then no one can compile them without having them
installed already. That would be no good.
-@node ANSI C, Source Language, Using Extensions, Design Advice
+@node ANSI C
@section @sc{ansi} C and pre-@sc{ansi} C
Do not ever use the ``trigraph'' feature of @sc{ansi} C.
If you don't know non-@sc{ansi} C, there's no need to learn it; just
write in @sc{ansi} C.
-@node Source Language, , ANSI C, Design Advice
+@node Source Language
@section Using Languages Other Than C
Using a language other than C is like using a non-standard feature: it
it's not important if the application is inconvenient to install.
@end itemize
-@node Program Behavior, Writing C, Design Advice, Top
+@node Program Behavior
@chapter Program Behavior for All Programs
This @value{CHAPTER} describes how to write robust software. It also
* Memory Usage:: When and how to care about memory needs
@end menu
-@node Semantics, Libraries, Program Behavior, Program Behavior
+@node Semantics
@section Writing Robust Programs
Avoid arbitrary limits on the length or number of @emph{any} data
variable; if that variable is defined, use the specified directory
instead of @file{/tmp}.
-@node Libraries, Errors, Semantics, Program Behavior
+@node Libraries
@section Library Behavior
Try to make library functions reentrant. If they need to do dynamic
Static functions and variables can be used as you like and need not
fit any naming convention.
-@node Errors, User Interfaces, Libraries, Program Behavior
+@node Errors
@section Formatting Error Messages
Error messages from compilers should look like this:
usage messages, should start with a capital letter. But they should not
end with a period.
-@node User Interfaces, Option Table, Errors, Program Behavior
+@node User Interfaces
@section Standards for Command Line Interfaces
Please don't make the behavior of a utility depend on the name used
@end example
@end table
-@node Option Table, Memory Usage, User Interfaces, Program Behavior
+@node Option Table
@section Table of Long Options
Here is a table of long options used by GNU programs. It is surely
@samp{-z} in @code{gprof}.
@end table
-@node Memory Usage, , Option Table, Program Behavior
+@node Memory Usage
@section Memory Usage
If it typically uses just a few meg of memory, don't bother making any
If your program creates complicated data structures, just make them in
core and give a fatal error if @code{malloc} returns zero.
-@node Writing C, Documentation, Program Behavior, Top
+@node Writing C
@chapter Making The Best Use of C
This @value{CHAPTER} provides advice on how best to use the C language
* Mmap:: How you can safely use @code{mmap}.
@end menu
-@node Formatting, Comments, Writing C, Writing C
+@node Formatting
@section Formatting Your Source Code
It is important to put the open-brace that starts the body of a C
page. The formfeeds should appear alone on lines by themselves.
-@node Comments, Syntactic Conventions, Formatting, Writing C
+@node Comments
@section Commenting Your Work
Every program should start with a comment saying briefly what it is for.
@end example
-@node Syntactic Conventions, Names, Comments, Writing C
+@node Syntactic Conventions
@section Clean Use of C Constructs
Please explicitly declare all arguments to functions.
casts to @code{void}. Zero without a cast is perfectly fine as a null
pointer constant, except when calling a varargs function.
-@node Names, System Portability, Syntactic Conventions, Writing C
+@node Names
@section Naming Variables and Functions
The names of global variables and functions in a program serve as
name conflicts if the files were loaded onto an MS-DOS file
system---something you may or may not care about.
-@node System Portability, CPU Portability, Names, Writing C
+@node System Portability
@section Portability between System Types
In the Unix world, ``portability'' refers to porting to different Unix
available. However, if you use Mach features, you'll probably have
trouble debugging your program today.
-@node CPU Portability, System Functions, System Portability, Writing C
+@node CPU Portability
@section Portability between @sc{cpu}s
Even GNU systems will differ because of differences among @sc{cpu}
well as an address in one word---it is ok to do so, but you'll have to
make explicit provisions to handle different word sizes.
-@node System Functions, Internationalization, CPU Portability, Writing C
+@node System Functions
@section Calling System Functions
C implementations differ substantially. @sc{ansi} C reduces but does not
macros defined in systems where the corresponding functions exist.
One way to get them properly defined is to use Autoconf.
-@node Internationalization, Mmap, System Functions, Writing C
+@node Internationalization
@section Internationalization
GNU has a library called GNU gettext that makes it easy to translate the
: "# Implicit rule search has not been done.\n");
@end example
-@node Mmap, , Internationalization, Writing C
+@node Mmap
@section Mmap
Don't assume that @code{mmap} either works on all files or fails
@code{mmap}, but some do not. It is important to make programs handle
all these kinds of files.
-@node Documentation, Managing Releases, Writing C, Top
+@node Documentation
@chapter Documenting Programs
@menu
from other manuals.
@end menu
-@node GNU Manuals, Manual Structure Details, Documentation, Documentation
+@node GNU Manuals
@section GNU Manuals
The preferred way to document part of the GNU system is to write a
computer program. Please use ``invalid'' for this, and reserve the term
``illegal'' for violations of law.
-@node Manual Structure Details, NEWS File, GNU Manuals, Documentation
+@node Manual Structure Details
@section Manual Structure Details
The title page of the manual should state the version of the programs or
If one manual describes several programs, it should have such a node for
each program described.
-@node NEWS File, Change Logs, Manual Structure Details, Documentation
+@node NEWS File
@section The NEWS File
In addition to its manual, the package should have a file named
into a file named @file{ONEWS} and put a note at the end referring the
user to that file.
-@node Change Logs, Man Pages, NEWS File, Documentation
+@node Change Logs
@section Change Logs
Keep a change log to describe all the changes made to program source
* Conditional Changes::
@end menu
-@node Change Log Concepts, Style of Change Logs, Change Logs, Change Logs
+@node Change Log Concepts
@subsection Change Log Concepts
You can think of the change log as a conceptual ``undo list'' which
of the changed functions, variables or whatever, followed by a colon.
Then describe the changes you made to that function or variable.
-@node Style of Change Logs, Simple Changes, Change Log Concepts, Change Logs
+@node Style of Change Logs
@subsection Style of Change Logs
Here are some examples of change log entries:
then don't put blank lines between them. Then you can omit the file
name and the asterisk when successive entries are in the same file.
-@node Simple Changes, Conditional Changes, Style of Change Logs, Change Logs
+@node Simple Changes
@subsection Simple Changes
Certain simple kinds of changes don't need much detail in the change
the history of the erroneous passage; it is enough to compare what the
documentation says with the way the program actually works.
-@node Conditional Changes, , Simple Changes, Change Logs
+@node Conditional Changes
@subsection Conditional Changes
C programs often contain compile-time @code{#if} conditionals. Many
(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
@end example
-@node Man Pages, Reading other Manuals, Change Logs, Documentation
+@node Man Pages
@section Man Pages
In the GNU project, man pages are secondary. It is not necessary or
is more authoritative. The note should say how to access the Texinfo
documentation.
-@node Reading other Manuals, , Man Pages, Documentation
+@node Reading other Manuals
@section Reading other Manuals
There may be non-free books or documentation files that describe the
documentation. Copying from free documentation may be ok; please check
with the FSF about the individual case.
-@node Managing Releases, , Documentation, Top
+@node Managing Releases
@chapter The Release Process
Making a release is more than just bundling up your source files in a
@menu
* Configuration:: How Configuration Should Work
+* Makefile Conventions:: Makefile Conventions
* Releases:: Making Releases
@end menu
-@node Configuration, Releases, Managing Releases, Managing Releases
+@node Configuration
@section How Configuration Should Work
Each GNU distribution should come with a shell script named
@include make-stds.texi
@raisesections
-@node Releases, , Configuration, Managing Releases
+@node Releases
@section Making Releases
Package the distribution of Foo version 69.96 in a gzipped tar file
@setfilename standards.info
@settitle GNU Coding Standards
@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
-@set lastupdate 20 April 1997
+@set lastupdate 6 May 1997
@c %**end of header
@ifinfo
* Managing Releases:: The Release Process
@end menu
-@node Preface, Intellectual Property, Top, Top
+@node Preface
@chapter About the GNU Coding Standards
The GNU Coding Standards were written by Richard Stallman and other GNU
This release of the GNU Coding Standards was last updated
@value{lastupdate}.
-@node Intellectual Property, Design Advice, Preface, Top
+@node Intellectual Property
@chapter Keeping Free Software Free
This @value{CHAPTER} discusses how you can make sure that GNU software
* Contributions:: Accepting Contributions
@end menu
-@node Reading Non-Free Code, Contributions, Intellectual Property, Intellectual Property
+@node Reading Non-Free Code
@section Referring to Proprietary Programs
Don't in any circumstances refer to Unix source code for or during
to free memory, or use a new GNU facility such as obstacks.
-@node Contributions, , Reading Non-Free Code, Intellectual Property
+@node Contributions
@section Accepting Contributions
If someone else sends you a piece of code to add to the program you are
reached the stage of actually maintaining a program for GNU (whether
released or not), please ask us for a copy.
-@node Design Advice, Program Behavior, Intellectual Property, Top
+@node Design Advice
@chapter General Program Design
This @value{CHAPTER} discusses some of the issues you should take into
* Source Language:: Using languages other than C
@end menu
-@node Compatibility, Using Extensions, Design Advice, Design Advice
+@node Compatibility
@section Compatibility with Other Implementations
With occasional exceptions, utility programs and libraries for GNU
but our first priority is usually to duplicate what Unix already
has.
-@node Using Extensions, ANSI C, Compatibility, Design Advice
+@node Using Extensions
@section Using Non-standard Features
Many GNU facilities that already exist support a number of convenient
the GNU compiler, then no one can compile them without having them
installed already. That would be no good.
-@node ANSI C, Source Language, Using Extensions, Design Advice
+@node ANSI C
@section @sc{ansi} C and pre-@sc{ansi} C
Do not ever use the ``trigraph'' feature of @sc{ansi} C.
If you don't know non-@sc{ansi} C, there's no need to learn it; just
write in @sc{ansi} C.
-@node Source Language, , ANSI C, Design Advice
+@node Source Language
@section Using Languages Other Than C
Using a language other than C is like using a non-standard feature: it
it's not important if the application is inconvenient to install.
@end itemize
-@node Program Behavior, Writing C, Design Advice, Top
+@node Program Behavior
@chapter Program Behavior for All Programs
This @value{CHAPTER} describes how to write robust software. It also
* Memory Usage:: When and how to care about memory needs
@end menu
-@node Semantics, Libraries, Program Behavior, Program Behavior
+@node Semantics
@section Writing Robust Programs
Avoid arbitrary limits on the length or number of @emph{any} data
variable; if that variable is defined, use the specified directory
instead of @file{/tmp}.
-@node Libraries, Errors, Semantics, Program Behavior
+@node Libraries
@section Library Behavior
Try to make library functions reentrant. If they need to do dynamic
Static functions and variables can be used as you like and need not
fit any naming convention.
-@node Errors, User Interfaces, Libraries, Program Behavior
+@node Errors
@section Formatting Error Messages
Error messages from compilers should look like this:
usage messages, should start with a capital letter. But they should not
end with a period.
-@node User Interfaces, Option Table, Errors, Program Behavior
+@node User Interfaces
@section Standards for Command Line Interfaces
Please don't make the behavior of a utility depend on the name used
@end example
@end table
-@node Option Table, Memory Usage, User Interfaces, Program Behavior
+@node Option Table
@section Table of Long Options
Here is a table of long options used by GNU programs. It is surely
@samp{-z} in @code{gprof}.
@end table
-@node Memory Usage, , Option Table, Program Behavior
+@node Memory Usage
@section Memory Usage
If it typically uses just a few meg of memory, don't bother making any
If your program creates complicated data structures, just make them in
core and give a fatal error if @code{malloc} returns zero.
-@node Writing C, Documentation, Program Behavior, Top
+@node Writing C
@chapter Making The Best Use of C
This @value{CHAPTER} provides advice on how best to use the C language
* Mmap:: How you can safely use @code{mmap}.
@end menu
-@node Formatting, Comments, Writing C, Writing C
+@node Formatting
@section Formatting Your Source Code
It is important to put the open-brace that starts the body of a C
page. The formfeeds should appear alone on lines by themselves.
-@node Comments, Syntactic Conventions, Formatting, Writing C
+@node Comments
@section Commenting Your Work
Every program should start with a comment saying briefly what it is for.
@end example
-@node Syntactic Conventions, Names, Comments, Writing C
+@node Syntactic Conventions
@section Clean Use of C Constructs
Please explicitly declare all arguments to functions.
casts to @code{void}. Zero without a cast is perfectly fine as a null
pointer constant, except when calling a varargs function.
-@node Names, System Portability, Syntactic Conventions, Writing C
+@node Names
@section Naming Variables and Functions
The names of global variables and functions in a program serve as
name conflicts if the files were loaded onto an MS-DOS file
system---something you may or may not care about.
-@node System Portability, CPU Portability, Names, Writing C
+@node System Portability
@section Portability between System Types
In the Unix world, ``portability'' refers to porting to different Unix
available. However, if you use Mach features, you'll probably have
trouble debugging your program today.
-@node CPU Portability, System Functions, System Portability, Writing C
+@node CPU Portability
@section Portability between @sc{cpu}s
Even GNU systems will differ because of differences among @sc{cpu}
well as an address in one word---it is ok to do so, but you'll have to
make explicit provisions to handle different word sizes.
-@node System Functions, Internationalization, CPU Portability, Writing C
+@node System Functions
@section Calling System Functions
C implementations differ substantially. @sc{ansi} C reduces but does not
macros defined in systems where the corresponding functions exist.
One way to get them properly defined is to use Autoconf.
-@node Internationalization, Mmap, System Functions, Writing C
+@node Internationalization
@section Internationalization
GNU has a library called GNU gettext that makes it easy to translate the
: "# Implicit rule search has not been done.\n");
@end example
-@node Mmap, , Internationalization, Writing C
+@node Mmap
@section Mmap
Don't assume that @code{mmap} either works on all files or fails
@code{mmap}, but some do not. It is important to make programs handle
all these kinds of files.
-@node Documentation, Managing Releases, Writing C, Top
+@node Documentation
@chapter Documenting Programs
@menu
from other manuals.
@end menu
-@node GNU Manuals, Manual Structure Details, Documentation, Documentation
+@node GNU Manuals
@section GNU Manuals
The preferred way to document part of the GNU system is to write a
computer program. Please use ``invalid'' for this, and reserve the term
``illegal'' for violations of law.
-@node Manual Structure Details, NEWS File, GNU Manuals, Documentation
+@node Manual Structure Details
@section Manual Structure Details
The title page of the manual should state the version of the programs or
If one manual describes several programs, it should have such a node for
each program described.
-@node NEWS File, Change Logs, Manual Structure Details, Documentation
+@node NEWS File
@section The NEWS File
In addition to its manual, the package should have a file named
into a file named @file{ONEWS} and put a note at the end referring the
user to that file.
-@node Change Logs, Man Pages, NEWS File, Documentation
+@node Change Logs
@section Change Logs
Keep a change log to describe all the changes made to program source
* Conditional Changes::
@end menu
-@node Change Log Concepts, Style of Change Logs, Change Logs, Change Logs
+@node Change Log Concepts
@subsection Change Log Concepts
You can think of the change log as a conceptual ``undo list'' which
of the changed functions, variables or whatever, followed by a colon.
Then describe the changes you made to that function or variable.
-@node Style of Change Logs, Simple Changes, Change Log Concepts, Change Logs
+@node Style of Change Logs
@subsection Style of Change Logs
Here are some examples of change log entries:
then don't put blank lines between them. Then you can omit the file
name and the asterisk when successive entries are in the same file.
-@node Simple Changes, Conditional Changes, Style of Change Logs, Change Logs
+@node Simple Changes
@subsection Simple Changes
Certain simple kinds of changes don't need much detail in the change
the history of the erroneous passage; it is enough to compare what the
documentation says with the way the program actually works.
-@node Conditional Changes, , Simple Changes, Change Logs
+@node Conditional Changes
@subsection Conditional Changes
C programs often contain compile-time @code{#if} conditionals. Many
(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
@end example
-@node Man Pages, Reading other Manuals, Change Logs, Documentation
+@node Man Pages
@section Man Pages
In the GNU project, man pages are secondary. It is not necessary or
is more authoritative. The note should say how to access the Texinfo
documentation.
-@node Reading other Manuals, , Man Pages, Documentation
+@node Reading other Manuals
@section Reading other Manuals
There may be non-free books or documentation files that describe the
documentation. Copying from free documentation may be ok; please check
with the FSF about the individual case.
-@node Managing Releases, , Documentation, Top
+@node Managing Releases
@chapter The Release Process
Making a release is more than just bundling up your source files in a
@menu
* Configuration:: How Configuration Should Work
+* Makefile Conventions:: Makefile Conventions
* Releases:: Making Releases
@end menu
-@node Configuration, Releases, Managing Releases, Managing Releases
+@node Configuration
@section How Configuration Should Work
Each GNU distribution should come with a shell script named
@include make-stds.texi
@raisesections
-@node Releases, , Configuration, Managing Releases
+@node Releases
@section Making Releases
Package the distribution of Foo version 69.96 in a gzipped tar file
projects / thirdparty / autoconf.git / commitdiff
