/[autoconf]/autoconf/doc/standards.texi
ViewVC logotype

Diff of /autoconf/doc/standards.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.62 by akim, Fri Nov 2 16:38:16 2001 UTC revision 1.63 by eggert, Tue Dec 3 07:58:02 2002 UTC
# Line 3  Line 3 
3  @setfilename standards.info  @setfilename standards.info
4  @settitle GNU Coding Standards  @settitle GNU Coding Standards
5  @c This date is automagically updated when you save this file:  @c This date is automagically updated when you save this file:
6  @set lastupdate October 19, 2001  @set lastupdate November 23, 2002
7  @c %**end of header  @c %**end of header
8    
9  @ifinfo  @dircategory GNU organization
10  @format  @direntry
 START-INFO-DIR-ENTRY  
11  * Standards: (standards).        GNU coding standards.  * Standards: (standards).        GNU coding standards.
12  END-INFO-DIR-ENTRY  @end direntry
 @end format  
 @end ifinfo  
13    
14  @c @setchapternewpage odd  @c @setchapternewpage odd
15  @setchapternewpage off  @setchapternewpage off
# Line 32  END-INFO-DIR-ENTRY Line 29  END-INFO-DIR-ENTRY
29  @set CHAPTER node  @set CHAPTER node
30  @end ifinfo  @end ifinfo
31    
32  @ifinfo  @copying
33  GNU Coding Standards  The GNU coding standards, last updated @value{lastupdate}.
34  Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.  
35    Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
36    2001, 2002 Free Software Foundation, Inc.
37    
38  Permission is granted to copy, distribute and/or modify this document  Permission is granted to copy, distribute and/or modify this document
39  under the terms of the GNU Free Documentation License, Version 1.1  under the terms of the GNU Free Documentation License, Version 1.1
# Line 43  with no Invariant Sections, with no Line 42  with no Invariant Sections, with no
42  Front-Cover Texts, and with no Back-Cover Texts.  Front-Cover Texts, and with no Back-Cover Texts.
43  A copy of the license is included in the section entitled ``GNU  A copy of the license is included in the section entitled ``GNU
44  Free Documentation License''.  Free Documentation License''.
45  @end ifinfo  @end copying
46    
47  @titlepage  @titlepage
48  @title GNU Coding Standards  @title GNU Coding Standards
49  @author Richard Stallman, et al.  @author Richard Stallman, et al.
50  @author last updated @value{lastupdate}  @author last updated @value{lastupdate}
51  @page  @page
   
52  @vskip 0pt plus 1filll  @vskip 0pt plus 1filll
53  Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.  @insertcopying
   
 Permission is granted to copy, distribute and/or modify this document  
 under the terms of the GNU Free Documentation License, Version 1.1  
 or any later version published by the Free Software Foundation;  
 with no Invariant Sections, with no  
 Front-Cover Texts, and with no Back-Cover Texts.  
 A copy of the license is included in the section entitled ``GNU  
 Free Documentation License''.  
54  @end titlepage  @end titlepage
55    
56  @ifinfo  @contents
57    
58    @ifnottex
59  @node Top, Preface, (dir), (dir)  @node Top, Preface, (dir), (dir)
60  @top Version  @top Version
61    
62  Last updated @value{lastupdate}.  @insertcopying
63  @end ifinfo  @end ifnottex
64    
65  @menu  @menu
66  * Preface::                     About the GNU Coding Standards  * Preface::                     About the GNU Coding Standards
# Line 101  This release of the GNU Coding Standards Line 93  This release of the GNU Coding Standards
93  @cindex where to obtain @code{standards.texi}  @cindex where to obtain @code{standards.texi}
94  @cindex downloading this manual  @cindex downloading this manual
95  If you did not obtain this file directly from the GNU project and  If you did not obtain this file directly from the GNU project and
96  recently, please check for a newer version.  You can ftp the GNU  recently, please check for a newer version.  You can get the GNU
97  Coding Standards from any GNU FTP host in the directory  Coding Standards from the GNU World Wide Web server host in several
98  @file{/pub/gnu/standards/}.  The GNU Coding Standards are available  different formats: @uref{http://www.gnu.org/prep/standards.text},
99  there in several different formats: @file{standards.text},  @uref{http://www.gnu.org/prep/standards.info}, and
100  @file{standards.info}, and @file{standards.dvi}, as well as the  @uref{http://www.gnu.org/prep/standards.dvi}, as well as the
101  Texinfo ``source'' which is divided in two files:  Texinfo ``source'' which is divided in two files:
102  @file{standards.texi} and @file{make-stds.texi}.  The GNU Coding  @uref{http://www.gnu.org/prep/standards.texi} and
103  Standards are also available on the GNU World Wide Web server:  @uref{http://www.gnu.org/prep/make-stds.texi}.  The GNU Coding
104    Standards are also available in HTML format starting at
105  @uref{http://www.gnu.org/prep/standards_toc.html}.  @uref{http://www.gnu.org/prep/standards_toc.html}.
106    
107  Corrections or suggestions for this document should be sent to  Corrections or suggestions for this document should be sent to
# Line 129  be self-consistent---try to stick to the Line 122  be self-consistent---try to stick to the
122  to document them as much as possible.  That way, your program will be  to document them as much as possible.  That way, your program will be
123  more maintainable by others.  more maintainable by others.
124    
125    The GNU Hello program serves as an example of how to follow the GNU
126    coding standards for a trivial program which prints @samp{Hello,
127    world!}.  @uref{http://www.gnu.org/software/hello/hello.html}.
128    
129  @node Legal Issues  @node Legal Issues
130  @chapter Keeping Free Software Free  @chapter Keeping Free Software Free
131  @cindex legal aspects  @cindex legal aspects
# Line 679  Error messages from compilers should loo Line 676  Error messages from compilers should loo
676  @end example  @end example
677    
678  @noindent  @noindent
679  If you want to mention the column number, use this format:  If you want to mention the column number, use one of these formats:
680    
681  @example  @example
682  @var{source-file-name}:@var{lineno}:@var{column}: @var{message}  @var{source-file-name}:@var{lineno}:@var{column}: @var{message}
683    @var{source-file-name}:@var{lineno}.@var{column}: @var{message}  
684    
685  @end example  @end example
686    
687  @noindent  @noindent
# Line 692  of these conventions are chosen for comp Line 691  of these conventions are chosen for comp
691  numbers assuming that space and all ASCII printing characters have  numbers assuming that space and all ASCII printing characters have
692  equal width, and assuming tab stops every 8 columns.  equal width, and assuming tab stops every 8 columns.
693    
694    The error message can also give both the starting and ending positions
695    of the erroneous text.  There are several formats so that you can
696    avoid redundant information such as a duplicate line number.
697    Here are the possible formats:
698    
699    @example
700    @var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
701    @var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
702    @var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
703    @end example
704    
705    @noindent
706    When an error is spread over several files, you can use this format:
707    
708    @example
709    @var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
710    @end example
711    
712  Error messages from other noninteractive programs should look like this:  Error messages from other noninteractive programs should look like this:
713    
714  @example  @example
# Line 1573  Used in GDB. Line 1590  Used in GDB.
1590  @item no-sort  @item no-sort
1591  @samp{-p} in @code{nm}.  @samp{-p} in @code{nm}.
1592    
1593    @item no-splash
1594    Don't print a startup splash screen.
1595    
1596  @item no-split  @item no-split
1597  Used in @code{makeinfo}.  Used in @code{makeinfo}.
1598    
# Line 3000  together, we can make the whole subject Line 3020  together, we can make the whole subject
3020    
3021  The manual which discusses a program should certainly document all of  The manual which discusses a program should certainly document all of
3022  the program's command-line options and all of its commands.  It should  the program's command-line options and all of its commands.  It should
3023  give examples of their use.  But don't organize the manual as a list of  give examples of their use.  But don't organize the manual as a list
3024  features.  Instead, organize it logically, by subtopics.  Address the  of features.  Instead, organize it logically, by subtopics.  Address
3025  questions that a user will ask when thinking about the job that the  the questions that a user will ask when thinking about the job that
3026  program does.  the program does.  Don't just tell the reader what each feature can
3027    do---say what jobs it is good for, and show how to use it for those
3028    jobs.  Explain what is recommended usage, and what kinds of usage
3029    users should avoid.
3030    
3031  In general, a GNU manual should serve both as tutorial and reference.  In general, a GNU manual should serve both as tutorial and reference.
3032  It should be set up for convenient access to each topic through Info,  It should be set up for convenient access to each topic through Info,
# Line 3041  exceptions.)  Also, Unix man pages use a Line 3064  exceptions.)  Also, Unix man pages use a
3064  different from what we use in GNU manuals.  different from what we use in GNU manuals.
3065    
3066  Please include an email address in the manual for where to report  Please include an email address in the manual for where to report
3067  bugs @emph{in the manual}.  bugs @emph{in the text of the manual}.
3068    
3069  Please do not use the term ``pathname'' that is used in Unix  Please do not use the term ``pathname'' that is used in Unix
3070  documentation; use ``file name'' (two words) instead.  We use the term  documentation; use ``file name'' (two words) instead.  We use the term
3071  ``path'' only for search paths, which are lists of directory names.  ``path'' only for search paths, which are lists of directory names.
3072    
3073  Please do not use the term ``illegal'' to refer to erroneous input to a  Please do not use the term ``illegal'' to refer to erroneous input to
3074  computer program.  Please use ``invalid'' for this, and reserve the term  a computer program.  Please use ``invalid'' for this, and reserve the
3075  ``illegal'' for activities punishable by law.  term ``illegal'' for activities prohibited by law.
3076    
3077  @node Doc Strings and Manuals  @node Doc Strings and Manuals
3078  @section Doc Strings and Manuals  @section Doc Strings and Manuals
# Line 3486  this: Line 3509  this:
3509  @var{cpu}-@var{company}-@var{system}  @var{cpu}-@var{company}-@var{system}
3510  @end example  @end example
3511    
3512  For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.  For example, an Athlon-based GNU/Linux system might be
3513    @samp{i686-pc-linux-gnu}.
3514    
3515  The @code{configure} script needs to be able to decode all plausible  The @code{configure} script needs to be able to decode all plausible
3516  alternatives for how to describe a machine.  Thus, @samp{sun3-sunos4.1}  alternatives for how to describe a machine.  Thus,
3517  would be a valid alias.  For many programs, @samp{vax-dec-ultrix} would  @samp{athlon-pc-gnu/linux} would be a valid alias.
3518  be an alias for @samp{vax-dec-bsd}, simply because the differences  There is a shell script called
3519  between Ultrix and @sc{bsd} are rarely noticeable, but a few programs  @uref{ftp://ftp.gnu.org/gnu/config/config.sub, @file{config.sub}}
3520  might need to distinguish them.  that you can use
 @c Real 4.4BSD now runs on some Suns.  
   
 There is a shell script called @file{config.sub} that you can use  
3521  as a subroutine to validate system types and canonicalize aliases.  as a subroutine to validate system types and canonicalize aliases.
3522    
3523    The @code{configure} script should also take the option
3524    @option{--build=@var{buildtype}}, which should be equivalent to a
3525    plain @var{buildtype} argument.  For example, @samp{configure
3526    --build=i686-pc-linux-gnu} is equivalent to @samp{configure
3527    i686-pc-linux-gnu}.  When the build type is not specified by an option
3528    or argument, the @code{configure} script should normally guess it
3529    using the shell script
3530    @uref{ftp://ftp.gnu.org/gnu/config/config.guess, @file{config.guess}}.
3531    
3532  @cindex optional features, configure-time  @cindex optional features, configure-time
3533  Other options are permitted to specify in more detail the software  Other options are permitted to specify in more detail the software
3534  or hardware present on the machine, and include or exclude optional  or hardware present on the machine, and include or exclude optional
# Line 3558  The @code{configure} script should norma Line 3588  The @code{configure} script should norma
3588  system as both the host and the target, thus producing a program which  system as both the host and the target, thus producing a program which
3589  works for the same type of machine that it runs on.  works for the same type of machine that it runs on.
3590    
3591    To compile a program to run on a host type that differs from the build
3592    type, use the configure option @option{--host=@var{hosttype}}, where
3593    @var{hosttype} uses the same syntax as @var{buildtype}.  The host type
3594    normally defaults to the build type.
3595    
3596  To configure a cross-compiler, cross-assembler, or what have you, you  To configure a cross-compiler, cross-assembler, or what have you, you
3597  should specify a target different from the host, using the configure  should specify a target different from the host, using the configure
3598  option @samp{--target=@var{targettype}}.  The syntax for  option @samp{--target=@var{targettype}}.  The syntax for
# Line 3565  option @samp{--target=@var{targettype}}. Line 3600  option @samp{--target=@var{targettype}}.
3600  look like this:  look like this:
3601    
3602  @example  @example
3603  ./configure @var{hosttype} --target=@var{targettype}  ./configure --host=@var{hosttype} --target=@var{targettype}
3604  @end example  @end example
3605    
3606    The target type normally defaults to the host type.
3607  Programs for which cross-operation is not meaningful need not accept the  Programs for which cross-operation is not meaningful need not accept the
3608  @samp{--target} option, because configuring an entire operating system for  @samp{--target} option, because configuring an entire operating system for
3609  cross-operation is not a meaningful operation.  cross-operation is not a meaningful operation.
3610    
 Bootstrapping a cross-compiler requires compiling it on a machine other  
 than the host it will run on.  Compilation packages accept a  
 configuration option @samp{--build=@var{buildtype}} for specifying the  
 configuration on which you will compile them, but the configure script  
 should normally guess the build machine type (using  
 @file{config.guess}), so this option is probably not necessary.  The  
 host and target types normally default from the build type, so in  
 bootstrapping a cross-compiler you must specify them both explicitly.  
   
3611  Some programs have ways of configuring themselves automatically.  If  Some programs have ways of configuring themselves automatically.  If
3612  your program is set up to do this, your @code{configure} script can simply  your program is set up to do this, your @code{configure} script can simply
3613  ignore most of its arguments.  ignore most of its arguments.
# Line 3681  other files to get. Line 3708  other files to get.
3708  @cindex references to non-free material  @cindex references to non-free material
3709    
3710  A GNU program should not recommend use of any non-free program.  We  A GNU program should not recommend use of any non-free program.  We
3711  can't stop some people from writing proprietary programs, or stop other  can't stop some people from writing proprietary programs, or stop
3712  people from using them.  But we can and should avoid helping to  other people from using them, but we can and should refuse to
3713  advertise them to new customers.  advertise them to new potential customers.  Proprietary software is a
3714    social and ethical problem, and the point of GNU is to solve that
3715  Sometimes it is important to mention how to build your package on top of  problem.
3716  some non-free operating system or other non-free base package.  In such  
3717  cases, please mention the name of the non-free package or system in the  The GNU definition of free software is found in
3718  briefest possible way.  Don't include any references for where to find  @url{http://www.gnu.org/philosophy/free-sw.html}, with a list of
3719  more information about the proprietary program.  The goal should be that  important licenses and whether they qualify as free in
3720  people already using the proprietary program will get the advice they  @url{http://www.gnu.org/licenses/license-list.html}.  The terms
3721  need about how to use your free program, while people who don't already  ``free'' and ``non-free'', used in this document, refer to that
3722  use the proprietary program will not see anything to encourage them to  definition.  If it is not clear whether a license qualifies as free
3723  take an interest in it.  under this definition, please ask the GNU Project by writing to
3724    @email{licensing@@gnu.org}.  We will answer, and if the license is an
3725  Likewise, a GNU package should not refer the user to any non-free  important one, we will add it to the list.
3726  documentation for free software.  The need for free documentation to go  
3727  with free software is now a major focus of the GNU project; to show that  When a non-free program or system is well known, you can mention it in
3728  we are serious about the need for free documentation, we must not  passing---that is harmless, since users who might want to use it
3729  undermine our position by recommending use of documentation that isn't  probably already know about it.  For instance, it is fine to explain
3730  free.  how to build your package on top of some widely used non-free
3731    operating system, or how to use it together with some widely used
3732    non-free program.
3733    
3734    However, you should give only the necessary information to help those
3735    who already use the non-free program to use your program with
3736    it---don't give, or refer to, any further information about the
3737    proprietary program, and don't imply that the proprietary program
3738    enhances your program, or that its existence is in any way a good
3739    thing.  The goal should be that people already using the proprietary
3740    program will get the advice they need about how to use your free
3741    program with it, while people who don't already use the proprietary
3742    program will not see anything to lead them to take an interest in it.
3743    
3744    If a non-free program or system is obscure in your program's domain,
3745    your program should not mention or support it at all, since doing so
3746    would tend to popularize the non-free program more than it popularizes
3747    your program.  (You cannot hope to find many additional users among
3748    the users of Foobar if the users of Foobar are few.)
3749    
3750    Sometimes a program is free software in itself but depends on a
3751    non-free platform in order to run.  For instance, many Java programs
3752    depend on Sun's Java implementation, and won't run on the GNU Java
3753    Compiler (which does not yet have all the features) or won't run with
3754    the GNU Java libraries.  To recommend that program is inherently to
3755    recommend the non-free platform as well; if you should not do the
3756    latter, then don't do the former.
3757    
3758    A GNU package should not refer the user to any non-free documentation
3759    for free software.  Free documentation that can be included in free
3760    operating systems is essential for completing the GNU system, or any
3761    free operating system, so it is a major focus of the GNU Project; to
3762    recommend use of documentation that we are not allowed to use in GNU
3763    would weaken the impetus for the community to produce documentation
3764    that we can include.  So GNU packages should never recommend non-free
3765    documentation.
3766    
3767    By contrast, it is ok to refer to journal articles and textbooks in
3768    the comments of a program for explanation of how it functions, even
3769    though they be non-free.  This is because we don't include such things
3770    in the GNU system even if we are allowed to--they are outside the
3771    scope of an operating system project.
3772    
3773    Referring to a web site that describes or recommends a non-free
3774    program is in effect promoting that software, so please do not make
3775    links (or mention by name) web sites that contain such material.  This
3776    policy is relevant particulary for the web pages for a GNU package.
3777    
3778    Following links from nearly any web site can lead to non-free
3779    software; this is an inescapable aspect of the nature of the web, and
3780    in itself is no objection to linking to a site.  As long as the site
3781    does not itself recommend a non-free program, there is no need be
3782    concerned about the sites it links to for other reasons.
3783    
3784    Thus, for example, you should not make a link to AT&T's web site,
3785    because that recommends AT&T's non-free software packages; you should
3786    not make a link to a site that links to AT&T's site saying it is a
3787    place to get a non-free program; but if a site you want to link to
3788    refers to AT&T's web site in some other context (such as long-distance
3789    telephone service), that is not a problem.
3790    
3791  @node Copying This Manual  @node Copying This Manual
3792  @appendix Copying This Manual  @appendix Copying This Manual
# Line 3715  free. Line 3801  free.
3801  @unnumbered Index  @unnumbered Index
3802  @printindex cp  @printindex cp
3803    
 @contents  
   
3804  @bye  @bye
3805  @c Local variables:  
3806  @c eval: (add-hook 'write-file-hooks 'time-stamp)  Local variables:
3807  @c time-stamp-start: "@set lastupdate "  eval: (add-hook 'write-file-hooks 'time-stamp)
3808  @c time-stamp-end: "$"  time-stamp-start: "@set lastupdate "
3809  @c time-stamp-format: "%:b %:d, %:y"  time-stamp-end: "$"
3810  @c compile-command: "make just-standards"  time-stamp-format: "%:b %:d, %:y"
3811  @c End:  compile-command: "make just-standards"
3812    End:

Legend:
Removed from v.1.62  
changed lines
  Added in v.1.63

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26