Mercurial > hg > octave-lyh > gnulib-hg
changeset 4958:93b3f9c4c71e
add maintain/standards docs
| author | Karl Berry <karl@freefriends.org> |
|---|---|
| date | Tue, 24 Feb 2004 01:05:44 +0000 |
| parents | 89cdc486bc48 |
| children | 7d0c18444fda |
| files | config/ChangeLog config/srclist.txt config/srclistvars.sh doc/ChangeLog doc/maintain.texi doc/make-stds.texi doc/standards.texi |
| diffstat | 7 files changed, 6400 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/config/ChangeLog +++ b/config/ChangeLog @@ -1,3 +1,8 @@ +2004-02-23 Karl Berry <karl@gnu.org> + + * srclistvars.sh (GNUORG) [karl]: redefine. + * srclist.txt: add maintain/standards documents. + 2004-02-16 Karl Berry <karl@gnu.org> * mkinstalldirs, install-sh: update from automake.
--- a/config/srclist.txt +++ b/config/srclist.txt @@ -1,4 +1,4 @@ -# $Id: srclist.txt,v 1.32 2004-01-18 14:54:16 karl Exp $ +# $Id: srclist.txt,v 1.33 2004-02-24 01:05:44 karl Exp $ # Files for which we are not the source. See ./srclistvars.sh for the # variable definitions. @@ -18,6 +18,10 @@ $GNUWWWLICENSES/fdl.texi doc $GNUWWWLICENSES/gpl.texi doc $GNUWWWLICENSES/lgpl.texi doc +# +$GNUORG/maintain.texi doc +$GNUORG/standards.texi doc +$GNUORG/make-stds.texi doc $GETTEXT/gettext-runtime/libasprintf/asnprintf.c lib gpl $GETTEXT/gettext-runtime/libasprintf/asprintf.c lib gpl
--- a/config/srclistvars.sh +++ b/config/srclistvars.sh @@ -1,4 +1,4 @@ -# $Id: srclistvars.sh,v 1.13 2004-01-20 13:59:25 karl Exp $ +# $Id: srclistvars.sh,v 1.14 2004-02-24 01:05:44 karl Exp $ # Variables for srclist-update and srclist.txt. # Will change for each user. @@ -22,6 +22,7 @@ : ${GNUBIN=/usr/local/gnu/bin} : ${GNUCONFIG=$HOME/gnu/src/config} : ${GNULIBSRC=$HOME/gnu/src/gnulib} + : ${GNUORG=$HOME/gnu/gnuorg} : ${GNUWWWLICENSES=$HOME/gnu/www/www/licenses} : ${LIBCSRC=$HOME/gnu/src/libc} : ${TEXINFOSRC=/u/texinfo/src}
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2004-02-23 Karl Berry <karl@gnu.org> + + * maintain.texi, standards.texi, make-stds.texi: new files + (from fencepost.gnu.org:/gd/gnuorg). + 2004-01-18 Karl Berry <karl@gnu.org> * gpl.texi, lgpl.texi: new files.
new file mode 100644 --- /dev/null +++ b/doc/maintain.texi @@ -0,0 +1,1536 @@ +\input texinfo.tex @c -*-texinfo-*- +@c %**start of header +@setfilename maintain.info +@settitle Information For Maintainers of GNU Software +@c For double-sided printing, uncomment: +@c @setchapternewpage odd +@c This date is automagically updated when you save this file: +@set lastupdate February 6, 2004 +@c %**end of header + +@dircategory GNU organization +@direntry +* Maintaining: (maintain). Maintaining GNU software. +@end direntry + +@setchapternewpage off + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex vr cp + +@copying +Information for maintainers of GNU software, last updated @value{lastupdate}. + +Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +2001, 2002, 2003, 2004 Free Software Foundation, Inc. + +@quotation +Permission is granted to make and distribute verbatim copies +of this entire document without royalty provided the +copyright notice and this permission notice are preserved. +@end quotation +@end copying + +@titlepage +@title Information For Maintainers of GNU Software +@author Richard Stallman +@author last updated @value{lastupdate} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Version + +@insertcopying +@end ifnottex + +@menu +* Preface:: +* Stepping Down:: +* Recruiting Developers:: +* Legal Matters:: +* Clean Ups:: +* Platforms:: +* Mail:: +* Old Versions:: +* Distributions:: +* Web Pages:: +* Ethical and Philosophical Consideration:: +* Terminology:: +* Hosting:: +* Free Software Directory:: +* Using the Proofreaders List:: +* Index:: +@end menu + +@node Preface +@chapter About This Document + +This file contains guidelines and advice for someone who is the +maintainer of a GNU program on behalf of the GNU Project. Everyone is +entitled to change and redistribute GNU software; you need not pay +attention to this file to get permission. But if you want to maintain a +version for widespread distribution, we suggest you follow these +guidelines; if you would like to be a GNU maintainer, then it is +essential to follow these guidelines. + +Please send corrections or suggestions for this document to +@email{maintainers@@gnu.org}. If you make a suggestion, please include +a suggested new wording for it, to help us consider the suggestion +efficiently. We prefer a context diff to the @file{maintain.texi} file, +but if you don't have that file, you can make a context diff for some +other version of this document, or propose it in any way that makes it +clear. + +This document uses the gender-neutral third-person pronouns ``person'', +``per'', ``pers'' and ``perself'' which were promoted, and perhaps +invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are +used just like ``she'', ``her'', ``hers'' and ``herself'', except that +they apply equally to males and females. For example, ``Person placed +per new program under the GNU GPL, to let the public benefit from per +work, and to enable per to feel person has done the right thing.'' + +The directory @file{/gd/gnuorg} is found on the GNU file server, +currently @code{fencepost.gnu.org}; if you are the maintainer of a GNU +package, you should have an account there. Contact +@email{accounts@@gnu.org} if you don't have one. (You can also ask +for accounts for people who help you a large amount in working on the +package.) @file{/gd/gnuorg/maintain.tar.gz} is a tar file containing +all of these files in that directory which are mentioned in this file; +it is updated daily. + +This release of the GNU Maintenance Instructions was last updated +@value{lastupdate}. + +@node Stepping Down +@chapter Stepping Down + +With good fortune, you will continue maintaining your package for many +decades. But sometimes for various reasons maintainers decide to step +down. + +If you're the official maintainer of a GNU package and you decide to +step down, please inform the GNU Project (@email{maintainers@@gnu.org}). +We need to know that the package no longer has a maintainer, so we can +look for and appoint a new maintainer. + +If you have an idea for who should take over, please tell +@email{maintainers@@gnu.org} your suggestion. The appointment of a new +maintainer needs the GNU Project's confirmation, but your judgment that +a person is capable of doing the job will carry a lot of weight. + +As your final act as maintainer, it would be helpful to set up the +package under @code{savannah.gnu.org} (@pxref{Old Versions}). This will +make it much easier for the new maintainer to pick up where you left off +and will ensure that the CVS tree is not misplaced if it takes us a +while to find a new maintainer. + +@node Recruiting Developers +@chapter Recruiting Developers + +Unless your package is a fairly small, you probably won't do all the +work on it yourself. Most maintainers recruit other developers to help. + +Sometimes people will offer to help. Some of them will be capable, +while others will not. It's up to you to determine who provides useful +help, and encourage those people to participate more. + +Some of the people who offer to help will support the GNU Project, while +others may be interested for other reasons. Some will support the goals +of the Free Software Movement, but some may not. They are all welcome +to help with the work---we don't ask people's views or motivations +before they contribute to GNU packages. + +As a consequence, you cannot expect all contributors to support the GNU +Project, or to have a concern for its policies and standards. So part +of your job as maintainer is to exercise your authority on these points +when they arise. No matter how much of the work other people do, you +are in charge of what goes in the release. When a crucial point arises, +you should calmly state your decision and stick to it. + +Sometimes a package has several co-maintainers who share the role of +maintainer. Unlike developers who help, co-maintainers have actually +been appointed jointly as the maintainers of the package, and they carry +out the maintainer's functions together. If you would like to propose +some of your developers as co-maintainers, please contact +@email{maintainers@@gnu.org}. + +@node Legal Matters +@chapter Legal Matters +@cindex legal matters + +This chapter describes procedures you should follow for legal reasons +as you maintain the program, to avoid legal difficulties. + +@menu +* Copyright Papers:: +* Legally Significant:: +* Recording Contributors:: +* Copyright Notices:: +* License Notices:: +* External Libraries:: +@end menu + +@node Copyright Papers +@section Copyright Papers +@cindex copyright papers + +If you maintain an FSF-copyrighted package +certain legal procedures when incorporating legally significant +changes written by other people. This ensures that the FSF has the +legal right to distribute the package, and the standing to defend its +GPL-covered status in court if necessary. + +@strong{Before} incorporating significant changes, make sure that the +person who wrote the changes has signed copyright papers and that the +Free Software Foundation has received and signed them. We may also need +a disclaimer from the person's employer. + +@cindex data base of GNU copyright assignments +To check whether papers have been received, look in +@file{/gd/gnuorg/copyright.list}. If you can't look there directly, +@email{fsf-records@@gnu.org} can check for you. Our clerk can also +check for papers that are waiting to be entered and inform you when +expected papers arrive. + +@cindex @file{/gd/gnuorg} directory +@c This paragraph intentionally duplicates information given +@c near the beginning of the file--to make sure people don't miss it. +The directory @file{/gd/gnuorg} is found on the GNU machines; if you are +the maintainer of a GNU package, you should have an account on them. +Contact @email{accounts@@gnu.org} if you don't have one. (You can also +ask for accounts for people who help you a large amount in working on +the package.) + +In order for the contributor to know person should sign papers, you need +to ask for the necessary papers. If you don't know per well, and you +don't know that person is used to our ways of handling copyright papers, +then it might be a good idea to raise the subject with a message like +this: + +@quotation +Would you be willing to assign the copyright to the Free Software +Foundation, so that we could install it in @var{program}? +@end quotation + +@noindent +or + +@quotation +Would you be willing to sign a copyright disclaimer to put this change +in the public domain, so that we can install it in @var{program}? +@end quotation + +If the contributor wants more information, you can send per +@file{/gd/gnuorg/conditions.text}, which explains per options (assign +vs.@: disclaim) and their consequences. + +Once the conversation is under way and the contributor is ready for +more details, you should send one of the templates that are found in +@file{/gd/gnuorg/Copyright}. This section explains which templates +you should use in which circumstances. @strong{Please don't use any +of the templates except for those listed here, and please don't change +the wording.} + +Once the conversation is under way, you can send the contributor the +precise wording and instructions by email. Before you do this, make +sure to get the current version of the template you will use! We change +these templates occasionally---don't keep using an old version. + +For large changes, ask the contributor for an assignment. Send per a +copy of the file @file{request-assign.changes}. (Like all the +@samp{request-} files, it is in @file{/gd/gnuorg/Copyright}.) + +For medium to small changes, request a disclaimer by sending per the +file @file{request-disclaim.changes}. + +If the contributor is likely to keep making changes, person might want +to sign an assignment for all per future changes to the program. So it +is useful to offer per that alternative. If person wants to do it that +way, send per the @file{request-assign.future}. + +When you send a @file{request-} file, you don't need to fill in anything +before sending it. Just send the file verbatim to the contributor. The +file gives per instructions for how to ask the FSF to mail per the +papers to sign. The @file{request-} file also raises the issue of +getting a copyright disclaimer from the contributor's employer. + +For less common cases, we have template files you should send to the +contributor. Be sure to fill in the name of the person and the name +of the program in these templates, where it says @samp{NAME OF PERSON} +and @samp{NAME OF PROGRAM}, before sending; otherwise person might +sign without noticing them, and the papers would be useless. Note +that in some templates there is more than one place to put the name of +the program or the name of the person; be sure to change all of them. +All the templates raise the issue of an employer's disclaimer as well. + +@cindex legal papers for changes in manuals +You do not need to ask for separate papers for a manual that is +distributed only in the software package it describes. But if we +sometimes distribute the manual separately (for instance, if we publish +it as a book), then we need separate legal papers for changes in the +manual. For smaller changes, use +@file{disclaim.changes.manual}; for larger ones, use +@file{assign.changes.manual}. To cover both past and future +changes to a manual, you can use @file{assign.future.manual}. +For a translation of a manual, use @file{assign.translate.manual}. + +If a contributor is reluctant to sign an assignment for a large change, +and is willing to sign a disclaimer instead, that is acceptable, so you +should offer this alternative if it helps you reach agreement. We +prefer an assignment for a larger change, so that we can enforce the GNU +GPL for the new text, but a disclaimer is enough to let us use the text. + +If you maintain a collection of programs, occasionally someone will +contribute an entire separate program or manual that should be added to +the collection. Then you can use the files +@file{request-assign.program}, @file{disclaim.program}, +@file{assign.manual}, and @file{disclaim.manual}. We very much prefer +an assignment for a new separate program or manual, unless it is quite +small, but a disclaimer is acceptable if the contributor insists on +handling the matter that way. + +If a contributor wants the FSF to publish only a pseudonym, that is +ok. The contributor should say this, and state the desired pseudonym, +when answering the @file{request-} form. The actual legal papers will +use the real name, but the FSF will publish only the pseudonym. When +using one of the other forms, fill in the real name but ask the +contributor to discuss the use of a pseudonym with +@email{assign@@gnu.org} before sending back the signed form. + +@strong{Although there are other templates besides the ones listed here, +they are for special circumstances; please do not use them without +getting advice from @email{assign@@gnu.org}.} + +If you are not sure what to do, then please ask @email{assign@@gnu.org} for +advice; if the contributor asks you questions about the meaning and +consequences of the legal papers, and you don't know the answers, you +can forward them to @email{assign@@gnu.org} and we will answer. + +@strong{Please do not try changing the wording of a template yourself. +If you think a change is needed, please talk with @email{assign@@gnu.org}, +and we will work with a lawyer to decide what to do.} + +@node Legally Significant +@section Legally Significant Changes + +If a person contributes more than around 15 lines of code and/or text +that is legally significant for copyright purposes, which means we +need copyright papers for it as described above. + +A change of just a few lines (less than 15 or so) is not legally +significant for copyright. A regular series of repeated changes, such +as renaming a symbol, is not legally significant even if the symbol +has to be renamed in many places. Keep in mind, however, that a +series of minor changes by the same person can add up to a significant +contribution. What counts is the total contribution of the person; it +is irrelevant which parts of it were contributed when. + +Copyright does not cover ideas. If someone contributes ideas but no +text, these ideas may be morally significant as contributions, and +worth giving credit for, but they are not significant for copyright +purposes. Likewise, bug reports do not count for copyright purposes. + +When giving credit to people whose contributions are not legally +significant for copyright purposes, be careful to make that fact +clear. The credit should clearly say they did not contribute +significant code or text. + +When people's contributions are not legally significant because they +did not write code, do this by stating clearly what their contribution +was. For instance, you could write this: + +@example +/* + * Ideas by: + * Richard Mlynarik <mly@@adoc.xerox.com> (1997) + * Masatake Yamato <masata-y@@is.aist-nara.ac.jp> (1999) + */ +@end example + +@noindent +@code{Ideas by:} makes it clear that Mlynarik and Yamato here +contributed only ideas, not code. Without the @code{Ideas by:} note, +several years from now we would find it hard to be sure whether they +had contributed code, and we might have to track them down and ask +them. + +When you record a small patch in a change log file, first search for +previous changes by the same person, and see if his past +contributions, plus the new one, add up to something legally +significant. If so, you should get copyright papers for all his +changes before you install the new change. + +If that is not so, you can install the small patch. Write @samp{(tiny +change)} after the patch author's name, like this: + +@example +2002-11-04 Robert Fenk <Robert.Fenk@@gmx.de> (tiny change) +@end example + +@node Recording Contributors +@section Recording Contributors +@cindex recording contributors + +@strong{Keep correct records of which portions were written by whom.} +This is very important. These records should say which files +parts of files, were written by each person, and which files or +portions were revised by each person. This should include +installation scripts as well as manuals and documentation +files---everything. + +These records don't need to be as detailed as a change log. They +don't need to distinguish work done at different times, only different +people. They don't need describe changes in more detail than which +files or parts of a file were changed. And they don't need to say +anything about the function or purpose of a file or change--the +Register of Copyrights doesn't care what the text does, just who wrote +or contributed to which parts. + +The list should also mention if certain files distributed in the same +package are really a separate program. + +Only the contributions that are legally significant for copyright +purposes (@pxref{Legally Significant}) need to be listed. Small +contributions, ideas, etc., can be omitted. + +For example, this would describe an early version of GAS: + +@display +Dean Elsner first version of all files except gdb-lines.c and m68k.c. +Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c, + plus extensive changes in messages.c, input-file.c, write.c + and revisions elsewhere. + +Note: GAS is distributed with the files obstack.c and obstack.h, but +they are considered a separate package, not part of GAS proper. +@end display + +@cindex @file{AUTHORS} file +Please keep these records in a file named @file{AUTHORS} in the source +directory for the program itself. + +@node Copyright Notices +@section Copyright Notices +@cindex copyright notices in program files + +You should maintain a legally valid copyright notice and a license +notice in each nontrivial file in the package. (Any file more than ten +lines long is nontrivial for this purpose.) This includes header files +and interface definitions +building or running the program, documentation files, and any supporting +files. If a file has been explicitly placed in the public domain, then +instead of a copyright notice, it should have a notice saying explicitly +that it is in the public domain. + +Even image files and sound files should contain copyright notices and +license notices, if they can. Some formats do not have room for textual +annotations; for these files, state the copyright and copying +permissions in a README file in the same directory. + +Change log files should have a copyright notice and license notice at +the end, since new material is added at the beginning but the end +remains the end. + +When a file is automatically generated from some other file in the +distribution, it is useful to copy the copyright notice and permission +notice of the file it is generated from, if you can. Alternatively, put +a notice at the beginning saying which file it is generated from. + +A copyright notice looks like this: + +@example +Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder} +@end example + +The @var{copyright-holder} may be the Free Software Foundation, Inc., or +someone else; you should know who is the copyright holder for your +package. + +Replace the @samp{(C)} with a C-in-a-circle symbol if it is available. +For example, use @samp{@@copyright@{@}} in a Texinfo file. However, +stick with parenthesized @samp{C} unless you know that C-in-a-circle +will work. For example, a program's standard @option{--version} +message should use parenthesized @samp{C} by default, though message +translations may use C-in-a-circle in locales where that symbol is +known to work. + +The list of year numbers should include each year in which you finished +preparing a version which was actually released, and which was an +ancestor of the current version. + +Please reread the paragraph above, slowly and carefully. It is +important to understand that rule precisely, much as you would +understand a complicated C statement in order to hand-simulate it. + +This list is @emph{not} a list of years in which versions were +@emph{released}. It is a list of years in which versions, later +released, were @emph{completed}. So if you finish a version on Dec 31, +1994 and release it on Jan 1, 1995, this version requires the inclusion +of 1994, but doesn't require the inclusion of 1995. + +Do not abbreviate the year list using a range; for instance, do not +write @samp{1996--1998}; instead, write @samp{1996, 1997, 1998}. + +The versions that matter, for purposes of this list, are versions that +were ancestors of the current version. So if you made a temporary +branch in maintenance, and worked on branches A and B in parallel, then +each branch would have its own list of years, which is based on the +versions released in that branch. A version in branch A need not be +reflected in the list of years for branch B, and vice versa. + +However, if you copy code from branch A into branch B, the years for +branch A (or at least, for the parts that you copied into branch B) do +need to appear in the list in branch B, because now they are ancestors +of branch B. + +This rule is complicated. If we were in charge of copyright law, we +would probably change this (as well as many other aspects). + +For an FSF-copyrighted package, if you have followed the procedures to +obtain legal papers, each file should have just one copyright holder: +the Free Software Foundation, Inc. So the copyright notice should give +that name. + +But if contributors are not all assigning their copyrights to a single +copyright holder, it can easily happen that one file has several +copyright holders. Each contributor of nontrivial amounts is a +copyright holder. + +In that case, you should always include a copyright notice in the name +of main copyright holder of the file. You can also include copyright +notices for other copyright holders as well, and this is a good idea for +those who have contributed a large amount and for those who specifically +ask for notices in their names. But you don't have to include a notice +for everyone who contributed to the file, and that would be rather +inconvenient. + +@node License Notices +@section License Notices +@cindex license notices in program files + +Every nontrivial file needs a license notice as well as the copyright +notice. (Without a license notice giving permission to copy and change +the file +would make the file non-free.) + +The package itself should contain a full copy of GPL (conventionally in +a file named @file{COPYING}) and the GNU Free Documentation License +(included within your documentation). If the package contains any files +distributed under the Lesser GPL, it should contain a full copy of that +as well (conventionally in a file named @file{COPYING.LIB}). + +You can get the official versions of these files from three places. +You can use whichever is the most convenient for you. + +@itemize @bullet +@item +@uref{http://www.gnu.org/licenses/}. + +@item +The directory @file{/gd/gnuorg} on the host +@code{fencepost.gnu.org}. (You can ask @email{accounts@@gnu.org} +for an account there if you don't have one). + +@item +The @code{gnulib} project on @code{savannah.gnu.org}, which you +can access via anonymous CVS. See +@uref{http://savannah.gnu.org/projects/gnulib}. + +@end itemize + +The official Texinfo sources for the licenses are also available in +those same places, so you can include them in your documentation. A +GFDL-covered manual must include the GFDL in this way. @xref{GNU Sample +Texts,,,texinfo,Texinfo}, for a full example in a Texinfo manual. + +Typically the license notice for program files (including build scripts, +configure files and makefiles) should cite the GPL, like this: + +@quotation +This file is part of GNU @var{program} + +GNU @var{program} is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU @var{program} is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with @var{program}; see the file COPYING. If not, write to +the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +Boston, MA 02111-1307, USA. +@end quotation + +But in a small program which is just a few files, you can use +this instead: + +@quotation +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. +@end quotation + +Documentation files should have license notices also. Manuals should +use the GNU Free Documentation License. Here is an example of the +license notice to use after the copyright notice. Please adjust the +list of invariant sections as appropriate for your manual. (If there +are none, then say ``with no invariant sections''.) @xref{GNU Sample +Texts,,,texinfo,Texinfo}, for a full example in a Texinfo manual. + +@smallexample +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 the +Invariant Sections being "GNU General Public License", with the +Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts +as in (a) below. A copy of the license is included in the section +entitled "GNU Free Documentation License". + +(a) The FSF's Back-Cover Text is: ``You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom.'' + +@end smallexample + +If the FSF does not publish this manual on paper, then omit the last +sentence in (b) that talks about copies from GNU Press. If the FSF is +not the copyright holder, then replace @samp{FSF} with the appropriate +name. + +See @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice +about how to use the GNU FDL. + +If the manual is over 400 pages, or if the FSF thinks it might be a good +choice for publishing on paper, then please include our standard +invariant section which explains the importance of free documentation. +Write to @email{assign@@gnu.org} to get a copy of this section. + +Note that when you distribute several manuals together in one software +package, their on-line forms can share a single copy of the GFDL (see +section 6). However, the printed (@samp{.dvi}) forms should each +contain a copy of the GFDL, unless they are set up to be printed +and published only together. Therefore, it is usually simplest to +include the GFDL in each manual. + +Small supporting files, short manuals (under 300 lines long) and rough +documentation (README files, INSTALL files, etc) can use a simple +all-permissive license like this one: + +@smallexample +Copying and distribution of this file, with or without modification, +are permitted in any medium without royalty provided the copyright +notice and this notice are preserved. +@end smallexample + +If you would like help with license issues or with using the GFDL, +please contact @email{licensing@@gnu.org}. + +@node External Libraries +@section External Libraries + +When maintaining an FSF-copyrighted GNU package, you may occasionally +want to use a general-purpose free software module which offers a +useful functionality, as a ``library'' facility (though the module is +not always packaged technically as a library). + +In a case like this, it would be unreasonable to ask the author of that +module to assign the copyright to the FSF. After all, person did not +write it specifically as a contribution to your package, so it would be +impertinent to ask per, out of the blue, ``Please give the FSF your +copyright.'' + +So the thing to do in this case is to make your program use the module, +but not consider it a part of your program. There are two reasonable +methods of doing this: + +@enumerate +@item +Assume the module is already installed on the system, and use it when +linking your program. This is only reasonable if the module really has +the form of a library. + +@item +Include the module in your package, putting the source in a separate +subdirectory whose @file{README} file says, ``This is not part of the +GNU FOO program, but is used with GNU FOO.'' Then set up your makefiles +to build this module and link it into the executable. + +For this method, it is not necessary to treat the module as a library +and make a @samp{.a} file from it. You can link with the @samp{.o} +files directly in the usual manner. +@end enumerate + +Both of these methods create an irregularity, and our lawyers have told +us to minimize the amount of such irregularity. So consider using these +methods only for general-purpose modules that were written for other +programs and released separately for general use. For anything that was +written as a contribution to your package, please get papers signed. + +@node Clean Ups +@chapter Cleaning Up Changes +@cindex contributions, accepting +@cindex quality of changes suggested by others + +Don't feel obligated to include every change that someone asks you to +include. You must judge which changes are improvements---partly based +on what you think the users will like, and partly based on your own +judgment of what is better. If you think a change is not good, you +should reject it. + +If someone sends you changes which are useful, but written in an ugly +way or hard to understand and maintain in the future, don't hesitate to +ask per to clean up their changes before you merge them. Since the +amount of work we can do is limited, the more we convince others to help +us work efficiently, the faster GNU will advance. + +If the contributor will not or can not make the changes clean enough, +then it is legitimate to say ``I can't install this in its present form; +I can only do so if you clean it up.'' Invite per to distribute per +changes another way, or to find other people to make them clean enough +for you to install and maintain. + +The only reason to do these cleanups yourself is if (1) it is easy, less +work than telling the author what to clean up, or (2) the change is an +important one, important enough to be worth the work of cleaning it up. + +The GNU Coding Standards are a good thing to send people when you ask +them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding +Standards}). The Emacs Lisp manual contains an appendix that gives +coding standards for Emacs Lisp programs; it is good to urge authors to +read it (@pxref{Tips, , Tips and Standards, elisp, The GNU Emacs Lisp +Reference Manual}). + +@node Platforms +@chapter Platforms to Support + +Most GNU packages run on a wide range of platforms. These platforms are +not equally important. + +The most important platforms for a GNU package to support are GNU and +GNU/Linux. Developing the GNU operating system is the whole point of +the GNU Project; a GNU package exists to make the whole GNU system more +powerful. So please keep that goal in mind and let it shape your work. +For instance, every new feature you add should work on GNU, and +GNU/Linux if possible too. If a new feature only runs on GNU and +GNU/Linux, it could still be acceptable. However, a feature that runs +only on other systems and not on GNU or GNU/Linux makes no sense in a +GNU package. + +You will naturally want to keep the program running on all the platforms +it supports. But you personally will not have access to most of these +platforms--so how should you do it? + +Don't worry about trying to get access to all of these platforms. Even +if you did have access to all the platforms, it would be inefficient for +you to test the program on each platform yourself. Instead, you should +test the program on a few platforms, including GNU or GNU/Linux, and let +the users test it on the other platforms. You can do this through a +pretest phase before the real release; when there is no reason to expect +problems, in a package that is mostly portable, you can just make a +release and let the users tell you if anything unportable was +introduced. + +It is important to test the program personally on GNU or GNU/Linux, +because these are the most important platforms for a GNU package. If +you don't have access to one of these platforms, please ask +@email{maintainers@@gnu.org} to help you out. + +Supporting other platforms is optional---we do it when that seems like a +good idea, but we don't consider it obligatory. If the users don't take +care of a certain platform, you may have to desupport it unless and +until users come forward to help. Conversely, if a user offers changes +to support an additional platform, you will probably want to install +them, but you don't have to. If you feel the changes are complex and +ugly, if you think that they will increase the burden of future +maintenance, you can and should reject them. This includes both free +platforms such as NetBSD or FreeBSD and non-free platforms such as +Windows. + +@node Mail +@chapter Dealing With Mail +@cindex bug reports + +@cindex email, for receiving bug reports +@cindex mailing list for bug reports +Once a program is in use, you will get bug reports for it. Most GNU +programs have their own special lists for sending bug reports. The +advertised bug-reporting email address should always be +@samp{bug-@var{program}@@gnu.org}, to help show users that the program +is a GNU package, but it is ok to set up that list to forward to another +site for further forwarding. The package distribution should state the +name of the bug-reporting list in a prominent place, and ask users to +help us by reporting bugs there. + +We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is +used for all GNU programs that don't have their own specific lists. But +nowadays we want to give each program its own bug-reporting list and +move away from using @email{bug-gnu-utils}. + +If you are the maintainer of a GNU package, you should have an account +on the GNU servers; contact @email{accounts@@gnu.org} if you don't have +one. (You can also ask for accounts for people who help you a large +amount in working on the package.) With this account, you can edit +@file{/com/mailer/aliases} to create a new unmanaged list or add +yourself to an existing unmanaged list. A comment near the beginning of +that file explains how to create a Mailman-managed mailing list. + +But if you don't want to learn how to do those things, you can +alternatively ask @email{alias-file@@gnu.org} to add you to the +bug-reporting list for your program. To set up a new list, contact +@email{new-mailing-list@@gnu.org}. You can subscribe to a list managed +by Mailman by sending mail to the corresponding @samp{-request} address. + +@cindex responding to bug reports +When you receive bug reports, keep in mind that bug reports are crucial +for your work. If you don't know about problems, you cannot fix them. +So always thank each person who sends a bug report. + +You don't have an obligation to give more response than that, though. +The main purpose of bug reports is to help you contribute to the +community by improving the next version of the program. Many of the +people who report bugs don't realize this---they think that the point is +for you to help them individually. Some will ask you to focus on that +@emph{instead of} on making the program better. If you comply with +their wishes, you will have been distracted from the job of maintaining +the program. + +For example, people sometimes report a bug in a vague (and therefore +useless) way, and when you ask for more information, they say, ``I just +wanted to see if you already knew the solution'' (in which case the bug +report would do nothing to help improve the program). When this +happens, you should explain to them the real purpose of bug reports. (A +canned explanation will make this more efficient.) + +When people ask you to put your time into helping them use the program, +it may seem ``helpful'' to do what they ask. But it is much @emph{less} +helpful than improving the program, which is the maintainer's real job. + +By all means help individual users when you feel like it, if you feel +you have the time available. But be careful to limit the amount of time +you spend doing this---don't let it eat away the time you need to +maintain the program! Know how to say no; when you are pressed for +time, just ``thanks for the bug report---I will fix it'' is enough +response. + +Some GNU packages, such as Emacs and GCC, come with advice about how to +make bug reports useful. If you want to copy and adapt that, it could +be a very useful thing to do. + +@node Old Versions +@chapter Recording Old Versions +@cindex version control + +It is very important to keep backup files of all source files of GNU. +You can do this using RCS, CVS or PRCS if you like. The easiest way to +use RCS or CVS is via the Version Control library in Emacs; +@ref{Concepts of VC, , Concepts of Version Control, emacs, The GNU Emacs +Manual}. + +The history of previous revisions and log entries is very important for +future maintainers of the package, so even if you do not make it +publicly accessible, be careful not to put anything in the repository or +change log that you would not want to hand over to another maintainer +some day. + +The GNU Project provides a CVS server that GNU software packages can +use: @code{subversions.gnu.org}. (The name refers to the multiple +versions and their subversions that are stored in a CVS repository.) +You don't have to use this repository, but if you plan to allow public +read-only access to your development sources, it is convenient for +people to be able to find various GNU packages in a central place. The +CVS Server is managed by @email{cvs-hackers@@gnu.org}. + +The GNU project also provides additional developer resources on +@code{subversions.gnu.org} through its @code{savannah.gnu.org} +interface. All GNU maintainers are encouraged to take advantage of +these facilities, as @code{savannah} can serve to foster a sense of +community among all GNU developers and help in keeping up with project +management. + +@node Distributions +@chapter Distributions + +It is important to follow the GNU conventions when making GNU software +distributions. + +@menu +* Distribution tar Files:: +* Distribution Patches:: +* Distribution on ftp.gnu.org:: +* Test Releases:: +* Automated FTP Uploads:: +* Announcements:: +@end menu + +@node Distribution tar Files +@section Distribution tar Files +@cindex distribution, tar files + +The tar file for version @var{m}.@var{n} of program @code{foo} should be +named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a +subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not +unpack into files in the current directory, because this is inconvenient +if the user happens to unpack into a directory with other files in it. + +Here is how the @file{Makefile} for Bison creates the tar file. +This method is good for other programs. + +@example +dist: bison.info + echo bison-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname + -rm -rf `cat .fname` + mkdir `cat .fname` + dst=`cat .fname`; for f in $(DISTFILES); do \ + ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \ + cp -p $(srcdir)/$$f $$dst/$$f ; @} \ + done + tar --gzip -chf `cat .fname`.tar.gz `cat .fname` + -rm -rf `cat .fname` .fname +@end example + +Source files that are symbolic links to other file systems cannot be +installed in the temporary directory using @code{ln}, so use @code{cp} +if @code{ln} fails. + +@pindex automake +Using Automake is a good way to take care of writing the @code{dist} +target. + +@node Distribution Patches +@section Distribution Patches +@cindex patches, against previous releases + +If the program is large, it is useful to make a set of diffs for each +release, against the previous important release. + +At the front of the set of diffs, put a short explanation of which +version this is for and which previous version it is relative to. +Also explain what else people need to do to update the sources +properly (for example, delete or rename certain files before +installing the diffs). + +The purpose of having diffs is that they are small. To keep them +small, exclude files that the user can easily update. For example, +exclude info files, DVI files, tags tables, output files of Bison or +Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up +to the installer to recompile the patched sources. + +When you make the diffs, each version should be in a directory suitably +named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way, +it will be very clear from the diffs themselves which version is which. + +@pindex diff +@pindex patch +@cindex time stamp in diffs +If you use GNU @code{diff} to make the patch, use the options +@samp{-rc2P}. That will put any new files into the output as ``entirely +different.'' Also, the patch's context diff headers should have dates +and times in Universal Time using traditional Unix format, so that patch +recipients can use GNU @code{patch}'s @samp{-Z} option. For example, +you could use the following Bourne shell command to create the patch: + +@example +LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \ +gzip -9 >gcc-2.3.2-2.3.3.patch.gz +@end example + +If the distribution has subdirectories in it, then the diffs probably +include some files in the subdirectories. To help users install such +patches reliably, give them precise directions for how to run patch. +For example, say this: + +@display +To apply these patches, cd to the main directory of the program +and then use `patch -p1'. `-p1' avoids guesswork in choosing +which subdirectory to find each file in. +@end display + +It's wise to test your patch by applying it to a copy of the old +version, and checking that the result exactly matches the new version. + +@node Distribution on ftp.gnu.org +@section Distribution on @code{ftp.gnu.org} +@cindex GNU ftp site +@cindex @code{ftp.gnu.org}, the GNU ftp site + +GNU packages are distributed through directory @file{/gnu} on +@code{ftp.gnu.org}. Each package should have a subdirectory +named after the package, and all the distribution files for the package +should go in that subdirectory. + +@c If you have an interest in seeing the monthly download logs from the FTP +@c site at @code{ftp.gnu.org} for your program, that is something that +@c @email{ftp-upload@@gnu.org} can set up for you. Please contact them if +@c you are interested. + +@xref{Automated FTP Uploads}, for procedural details of putting new +versions on @code{ftp.gnu.org}. + +@node Test Releases +@section Test Releases +@cindex test releases +@cindex beta releases +@cindex pretest releases + +@cindex @code{alpha.gnu.org}, ftp site for test releases +When you release a greatly changed new major version of a program, you +might want to do so as a pretest. This means that you make a tar file, +but send it only to a group of volunteers that you have recruited. (Use +a suitable GNU mailing list/newsgroup to recruit them.) + +We normally use the FTP server @code{alpha.gnu.org} for pretests and +prerelease versions. @xref{Automated FTP Uploads}, for procedural details +of putting new versions on @code{alpha.gnu.org}. + +Once a program gets to be widely used and people expect it to work +solidly, it is a good idea to do pretest releases before each ``real'' +release. + +There are two ways of handling version numbers for pretest versions. +One method is to treat them as versions preceding the release you are going +to make. + +In this method, if you are about to release version 4.6 but you want +to do a pretest first, call it 4.5.90. If you need a second pretest, +call it 4.5.91, and so on. If you are really unlucky and ten pretests +are not enough, after 4.5.99 you could advance to 4.5.990 and so on. +(You could also use 4.5.100, but 990 has the advantage of sorting in +the right order.) + +The other method is to attach a date to the release number that is +coming. For a pretest for version 4.6, made on Dec 10, 2002, this +would be 4.6.20021210. A second pretest made the same day could be +4.6.20021210.1. + +For development snapshots that are not formal pretests, using just +the date without the version numbers is ok too. + +One thing that you should never do is to release a pretest with the same +version number as the planned real release. Many people will look only +at the version number (in the tar file name, in the directory name that +it unpacks into, or wherever they can find it) to determine whether a +tar file is the latest version. People might look at the test release +in this way and mistake it for the real release. Therefore, always +change the number when you release changed code. + + +@node Automated FTP Uploads +@section Automated FTP Uploads + +@cindex ftp uploads, automated +In order to upload new releases to @code{ftp.gnu.org} or +@code{alpha.gnu.org}, you first need to register the necessary +information. Then, you can perform uploads yourself, with no +intervention needed by the system administrators. + +@menu +* Automated Upload Registration:: +* Automated Upload Procedure:: +@end menu + + +@node Automated Upload Registration +@subsection Automated Upload Registration + +@cindex registration +@cindex uploads, registration for + +To register your information to perform automated uploads, send a +message, preferably GPG-signed, to @email{ftp-upload@@gnu.org} with +the following: + +@enumerate +@item +Name of package(s) that you are the maintainer for, and your +preferred email address. + +@item +An ASCII armored copy of your GnuPG key, as an attachment. +(@samp{gpg --export -a YOUR_KEY_ID >mykey.asc} should give you this.) + +@item +A list of names and preferred email addresses of other individuals you +authorize to make releases for which packages, if any (in the case that you +don't make all releases yourself). + +@item +ASCII armored copies of GnuPG keys for any individuals listed in (3). +@end enumerate + +The administrators will acknowledge your message when they have added +the proper GPG keys as authorized to upload files for the +corresponding packages. + + +@node Automated Upload Procedure +@subsection Automated Upload Procedure + +@cindex uploads + +Once you have registered your information, as described in the +previous section, you will be able to do unattended ftp uploads using +the following procedure. + +For each upload destined for @code{ftp.gnu.org} or +@code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be +uploaded via ftp to the host @code{ftp-upload.gnu.org}. + +@enumerate +@item +File to distributed (e.g., @file{foo.tar.gz}). + +@item +Detached GPG binary signature for (1), made using @samp{gpg -b} +(for example, @file{foo.tar.gz.sig}). + +@item +A clearsigned @dfn{directive file}, made using @samp{gpg --clearsign} +(for example, @file{foo.tar.gz.directive.asc}). + +@end enumerate + +Upload the triplet via anonymous ftp to @code{ftp-upload.gnu.org}. If +the upload is destined for @code{ftp.gnu.org}, then place the triplet +in the @file{/incoming/ftp} directory. If the upload is destined for +@code{alpha.gnu.org}, then place the triplet in the +@file{/incoming/alpha} directory. + +Uploads are processed every five minutes. Uploads that are in +progress when the upload processing script is running are handled +properly, so do not worry about the timing of your upload. + +The directive file should contain one line, excluding the clearsigned +data GPG that inserts, which specifies the final destination directory +where items (1) and (2) to be placed. + +For example, the @file{foo.tar.gz.directive} file might contain the +single line: + +@example +directory: bar/v1 +@end example + +This directory line indicates that @file{foo.tar.gz} and +@file{foo.tar.gz.sig} are part of package @code{bar}. If you were to +upload the triplet to @file{/incoming/ftp}, and the system can +positively authenticate the signatures, then the files +@file{foo.tar.gz} and @file{foo.tar.gz.sig} will be placed in the +directory @file{gnu/bar/v1} of the @code{ftp.gnu.org} site. + +The directive file can be used to create currently non-existent +directory trees, as long as they are under the package directory for +your package (in the example above, that is @code{bar}). + +Your designated upload email addresses (@pxref{Automated Upload +Registration}) are sent a message if there are any problems processing +an upload for your package. + +If you have difficulties processing an upload, email +@email{ftp-upload@@gnu.org}. + + +@node Announcements +@section Announcing Releases + +When you have a new release, please make an announcement. You can +maintain your own mailing list for announcements if you like, or you can +use the moderated general GNU announcements list, +@email{info-gnu@@gnu.org}. + +If you use your own list, you can decide as you see fit what events are +worth announcing. If you use @email{info-gnu@@gnu.org}, please do not +announce pretest releases, only real releases. But real releases do +include releases made just to fix bugs. + +@node Web Pages +@chapter Web Pages +@cindex web pages + +Please write pages about your package for installation on +@code{www.gnu.org}. The pages should follow our usual standards for web +pages (see @url{http://www.gnu.org/server}); we chose them in order to +support a wide variety of browsers, to focus on information rather than +flashy eye candy, and to keep the site simple and uniform. + +The simplest way to maintain the web pages for your project is to +register the project on @code{savannah.gnu.org}. Then you can edit +the pages using CVS. You can keep the source files there too, but if +you want to use @code{savannah.gnu.org} only for the web pages, simply +register a ``web-only'' project. + +If you don't want to use that method, please talk with +@email{webmasters@@gnu.org} about other possible methods. For +instance, you can mail them pages to install, if necessary. But that +is more work for them, so please use CVS if you can. + +Some GNU packages have just simple web pages, but the more information +you provide, the better. So please write as much as you usefully can, +and put all of it on @code{www.gnu.org}. However, pages that access +databases (including mail logs and bug tracking) are an exception; set +them up on whatever site is convenient for you, and make the pages on +@code{www.gnu.org} link to that site. + +Web pages for GNU packages should not include GIF images, since the GNU +project avoids GIFs due to patent problems. @xref{Ethical and +Philosophical Consideration}. + +The web pages for the package should include its manuals, in HTML, +DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source). (All +of these can be generated automatically from the Texinfo source using +Makeinfo and other programs.) When there is only one manual, put it +in a subdirectory called @file{manual}; the file +@file{manual/index.html} should have a link to the manual in each of +its forms. + +If the package has more than one manual, put each one in a +subdirectory of @file{manual}, set up @file{index.html} in each +subdirectory to link to that manual in all its forms, and make +@file{manual/index.html} link to each manual through its subdirectory. + +See the section below for details on a script to make the job of +creating all these different formats and index pages easier. + +We would like to include links to all these manuals in the page +@url{http://www.gnu.org/manual}. Just send mail to +@code{webmasters@@gnu.org} telling them the name of your package and +asking them to edit @url{http://www.gnu.org/manual}, and they will do +so based on the contents of your @file{manual} directory. + +@menu +* Invoking gendocs.sh:: +@end menu + +@node Invoking gendocs.sh +@section Invoking @command{gendocs.sh} +@pindex gendocs.sh +@cindex generating documentation output + +The script @command{gendocs.sh} eases the task of generating the +Texinfo documentation output for your web pages +section above. It has a companion template file, used as the basis +for the html index pages. Both are available from the Texinfo CVS +sources: +@format +@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh} +@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template} +@end format + +Invoke the script like this, in the directory containing the Texinfo +source: +@example +gendocs.sh @var{yourmanual} "GNU @var{yourmanual} manual" +@end example + +@noindent where @var{yourmanual} is the short name for your package. +The script processes the file @file{@var{yourmanual}.texinfo} (or +@file{.texi} or @file{.txi}). For example: + +@example +cd .../emacs/man +# download gendocs.sh and gendocs_template +gendocs.sh emacs "GNU Emacs manual" +@end example + +@command{gendocs.sh} creates a subdirectory @file{manual/} containing +the manual generated in all the standard output formats: Info, HTML, +DVI, and so on, as well as the Texinfo source. You then need to move +all those files, retaining the subdirectories, into the web pages for +your package. + +You can specify the option @option{-o @var{outdir}} to override the +name @file{manual}. Any previous contents of @var{outdir} will be deleted. + +The second argument, with the description, is included as part of the +HTML @code{<title>} of the overall @file{manual/index.html} file. It +should include the name of the package being documented, as shown. +@file{manual/index.html} is created by substitution from the file +@file{gendocs_template}. (Feel free to modify the generic template +for your own purposes.) + +If you have several manuals, you'll need to run this script several +times with different arguments, specifying a different output +directory with @option{-o} each time, and moving all the output to +your web page. Then write (by hand) an overall index.html with links +to them all. For example: +@example +cd .../texinfo/doc +gendocs.sh -o texinfo texinfo "GNU Texinfo manual" +gendocs.sh -o info info "GNU Info manual" +gendocs.sh -o info-stnd info-stnd "GNU info-stnd manual" +@end example + +You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI}, +and @env{DVIPS} to control the programs that get executed, and +@env{GENDOCS_TEMPLATE_DIR} to control where the +@file{gendocs_template} file is found. + +Please email bug reports, enhancement requests, or other +correspondence to @email{bug-texinfo@@gnu.org}. + + +@node Ethical and Philosophical Consideration +@chapter Ethical and Philosophical Consideration +@cindex ethics +@cindex philosophy + +The GNU project takes a strong stand for software freedom. Many times, +this means you'll need to avoid certain technologies when such +technologies conflict with our ethics of software freedom. + +Software patents threaten the advancement of free software and freedom +to program. For our safety (which includes yours), we try to avoid +using algorithms and techniques that we know are patented in the US or +elsewhere, unless the patent looks so absurd that we doubt it will be +enforced, or we have a suitable patent license allowing release of free +software. + +Beyond that, sometimes the GNU project takes a strong stand against a +particular patented technology in order to encourage everyone to reject +it. + +For example, the GIF file format is covered by the LZW software patent +in the USA. A patent holder has threatened lawsuits against not only +developers of software to produce GIFs, but even web sites that +contain them. + +For this reason, you should not include GIFs in the web pages for your +package, nor in the distribution of the package itself. It is ok for +a GNU package to support displaying GIFs which will come into play if +a user asks it to operate on one. However, it is essential to provide +equal or better support for the competing PNG and JPG +formats---otherwise, the GNU package would be @emph{pressuring} users +to use GIF format, and that it must not do. More about our stand on +GIF is available at @uref{http://www.gnu.org/philosophy/gif.html}. + +Software patents are not the only matter for ethical concern. A GNU +package should not recommend use of any non-free program, nor should it +require a non-free program (such as a non-free compiler or IDE) to +build. Thus, a GNU package cannot be written in a programming language +that does not have a free software implementation. Now that GNU/Linux +systems are widely available, all GNU packages should function +completely with the GNU/Linux system and not require any non-free +software to build or function. + +A GNU package should not refer the user to any non-free documentation +for free software. The need for free documentation to come with free +software is now a major focus of the GNU project; to show that we are +serious about the need for free documentation, we must not contradict +our position by recommending use of documentation that isn't free. + +Finally, new issues concerning the ethics of software freedom come up +frequently. We ask that GNU maintainers, at least on matters that +pertain specifically to their package, stand with the rest of the GNU +project when such issues come up. + +@node Terminology +@chapter Terminology Issues +@cindex terminology + +This chapter explains a couple of issues of terminology which are +important for correcting two widespread and important misunderstandings +about GNU. + +@menu +* Free Software and Open Source:: +* GNU and Linux:: +@end menu + +@node Free Software and Open Source +@section Free Software and Open Source +@cindex free software +@cindex open source +@cindex movements, Free Software and Open Source + +The terms ``free software'' and ``open source'' are the slogans of two +different movements which differ in their basic philosophy. The Free +Software Movement is idealistic, and raises issues of freedom, ethics, +principle and what makes for a good society. The Open Source Movement, +founded in 1998, studiously avoids such questions. For more explanation, +see @url{http://www.gnu.org/philosophy/free-software-for-freedom.html}. + +The GNU Project is aligned with the Free Software Movement. This +doesn't mean that all GNU contributors and maintainers have to agree; +your views on these issues are up to you, and you're entitled to express +them when speaking for yourself. + +However, due to the much greater publicity that the Open Source Movement +receives, the GNU Project needs to overcome a widespread mistaken +impression that GNU is @emph{and always was} an activity of the Open +Source Movement. For this reason, please use the term ``free +software,'' rather than ``open source,'' in GNU software releases, GNU +documentation, and announcements and articles that you publish in your +role as the maintainer of a GNU package. A reference to the URL given +above, to explain the difference, is a useful thing to include as well. + +@node GNU and Linux +@section GNU and Linux +@cindex Linux +@cindex GNU/Linux + +The GNU Project was formed to develop a free Unix-like operating system, +GNU. The existence of this system is our major accomplishment. +However, the widely used version of the GNU system, in which Linux is +used as the kernel, is often called simply ``Linux''. As a result, most +users don't know about the GNU Project's major accomplishment---or more +precisely, they know about it, but don't realize it is the GNU Project's +accomplishment and reason for existence. Even people who believe they +know the real history often believe that the goal of GNU was to develop +``tools'' or ``utilities.'' + +To correct this confusion, we have made a years-long effort to +distinguish between Linux, the kernel that Linus Torvalds wrote, and +GNU/Linux, the operating system that is the combination of GNU and +Linux. The resulting increased awareness of what the GNU Project has +already done helps every activity of the GNU Project recruit more +support and contributors. + +Please make this distinction consistently in GNU software releases, GNU +documentation, and announcements and articles that you publish in your +role as the maintainer of a GNU package. If you want to explain the +terminology and its reasons, you can refer to the URL +@url{http://www.gnu.org/gnu/linux-and-gnu.html}. + +Do contrast the GNU system properly speaking to GNU/Linux, you can +call it ``GNU/Hurd'' or ``the GNU/Hurd system.'' However, when that +contrast is not specifically the focus, please call it just ``GNU'' or +``the GNU system.'' + +When referring to the collection of servers that is the higher level +of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd.'' +Note that this uses a space, not a slash. + +@node Hosting +@chapter Hosting +@cindex CVS repository +@cindex repository +@cindex FTP site +@cindex hosting + +We would like to recommend using @code{subversions.gnu.org} as the CVS +repository for your package, and using @code{ftp.gnu.org} as the +standard FTP site. It is ok to use other machines if you wish. If you +use a company's machine to hold the repository for your program, or as +its ftp site, please put this statement in a prominent place on the +site, so as to prevent people from getting the wrong idea about the +relationship between the package and the company: + +@smallexample +The programs <list of them> hosted here are free software packages +of the GNU Project, not products of <company name>. We call them +"free software" because you are free to copy and redistribute them, +following the rules stated in the license of each package. For more +information, see http://www.gnu.org/philosophy/free-sw.html. + +If you are looking for service or support for GNU software, see +http://www.gnu.org/help/gethelp.html for suggestions of where to ask. + +If you would like to contribute to the development of one of these +packages, contact the package maintainer or the bug-reporting address +of the package (which should be listed in the package itself), or look +on www.gnu.org for more information on how to contribute. +@end smallexample + +@node Free Software Directory +@chapter Free Software Directory +@cindex Free Software Directory + +The Free Software Directory aims to be a complete list of free software +packages, within certain criteria. Every GNU package should be listed +there, so please contact @email{bug-directory@@gnu.org} to ask for +information on how to write an entry for your package. + +@node Using the Proofreaders List +@chapter Using the Proofreaders List +@cindex proofreading + +If you want help finding errors in documentation, +or help improving the quality of writing, +or if you are not a native speaker of English +and want help producing good English documentation, +you can use the GNU proofreaders mailing list: +@email{proofreaders@@gnu.org}. + +But be careful when you use the list, +because there are over 200 people on it. +If you simply ask everyone on the list to read your work, +there will probably be tremendous duplication of effort +by the proofreaders, +and you will probably get the same errors reported 100 times. +This must be avoided. + +Also, the people on the list do not want to get +a large amount of mail from it. +So do not ever ask people on the list to send mail to the list! + +Here are a few methods that seem reasonable to use: + +@itemize @bullet +@item +For something small, mail it to the list, +and ask people to pick a random number from 1 to 20, +and read it if the number comes out as 10. +This way, assuming 50% response, some 5 people will read the piece. + +@item +For a larger work, divide your work into around 20 equal-sized parts, +tell people where to get it, +and ask each person to pick randomly which part to read. + +Be sure to specify the random choice procedure; +otherwise people will probably use a mental procedure +that is not really random, +such as "pick a part near the middle", +and you will not get even coverage. + +You can either divide up the work physically, into 20 separate files, +or describe a virtual division, such as by sections +(if your work has approximately 20 sections). +If you do the latter, be sure to be precise about it---for example, +do you want the material before the first section heading +to count as a section, or not? + +@item +For a job needing special skills, send an explanation of it, +and ask people to send you mail if they volunteer for the job. +When you get enough volunteers, send another message to the list saying +"I have enough volunteers, no more please." +@end itemize + +@node Index +@unnumbered Index +@printindex cp + +@bye + +Local variables: +eval: (add-hook 'write-file-hooks 'time-stamp) +time-stamp-start: "@set lastupdate " +time-stamp-start: "@set lastupdate " +time-stamp-end: "$" +time-stamp-format: "%:b %:d, %:y" +compile-command: "make just-maintain" +End:
new file mode 100644 --- /dev/null +++ b/doc/make-stds.texi @@ -0,0 +1,979 @@ +@comment This file is included by both standards.texi and make.texinfo. +@comment It was broken out of standards.texi on 1/6/93 by roland. + +@node Makefile Conventions +@chapter Makefile Conventions +@comment standards.texi does not print an index, but make.texinfo does. +@cindex makefile, conventions for +@cindex conventions for makefiles +@cindex standards for makefiles + +@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free +@c Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.1 +@c or any later version published by the Free Software Foundation; +@c with no Invariant Sections, with no +@c Front-Cover Texts, and with no Back-Cover Texts. +@c A copy of the license is included in the section entitled ``GNU +@c Free Documentation License''. + +This +@ifinfo +node +@end ifinfo +@iftex +@ifset CODESTD +section +@end ifset +@ifclear CODESTD +chapter +@end ifclear +@end iftex +describes conventions for writing the Makefiles for GNU programs. +Using Automake will help you write a Makefile that follows these +conventions. + +@menu +* Makefile Basics:: General Conventions for Makefiles +* Utilities in Makefiles:: Utilities in Makefiles +* Command Variables:: Variables for Specifying Commands +* Directory Variables:: Variables for Installation Directories +* Standard Targets:: Standard Targets for Users +* Install Command Categories:: Three categories of commands in the `install' + rule: normal, pre-install and post-install. +@end menu + +@node Makefile Basics +@section General Conventions for Makefiles + +Every Makefile should contain this line: + +@example +SHELL = /bin/sh +@end example + +@noindent +to avoid trouble on systems where the @code{SHELL} variable might be +inherited from the environment. (This is never a problem with GNU +@code{make}.) + +Different @code{make} programs have incompatible suffix lists and +implicit rules, and this sometimes creates confusion or misbehavior. So +it is a good idea to set the suffix list explicitly using only the +suffixes you need in the particular Makefile, like this: + +@example +.SUFFIXES: +.SUFFIXES: .c .o +@end example + +@noindent +The first line clears out the suffix list, the second introduces all +suffixes which may be subject to implicit rules in this Makefile. + +Don't assume that @file{.} is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses @file{./} if the program is built as +part of the make or @file{$(srcdir)/} if the file is an unchanging part +of the source code. Without one of these prefixes, the current search +path is used. + +The distinction between @file{./} (the @dfn{build directory}) and +@file{$(srcdir)/} (the @dfn{source directory}) is important because +users can build in a separate directory using the @samp{--srcdir} option +to @file{configure}. A rule of the form: + +@smallexample +foo.1 : foo.man sedscript + sed -e sedscript foo.man > foo.1 +@end smallexample + +@noindent +will fail when the build directory is not the source directory, because +@file{foo.man} and @file{sedscript} are in the source directory. + +When using GNU @code{make}, relying on @samp{VPATH} to find the source +file will work in the case where there is a single dependency file, +since the @code{make} automatic variable @samp{$<} will represent the +source file wherever it is. (Many versions of @code{make} set @samp{$<} +only in implicit rules.) A Makefile target like + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o +@end smallexample + +@noindent +should instead be written as + +@smallexample +foo.o : bar.c + $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ +@end smallexample + +@noindent +in order to allow @samp{VPATH} to work correctly. When the target has +multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest +way to make the rule work well. For example, the target above for +@file{foo.1} is best written as: + +@smallexample +foo.1 : foo.man sedscript + sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ +@end smallexample + +GNU distributions usually contain some files which are not source +files---for example, Info files, and the output from Autoconf, Automake, +Bison or Flex. Since these files normally appear in the source +directory, they should always appear in the source directory, not in the +build directory. So Makefile rules to update them should put the +updated files in the source directory. + +However, if a file does not appear in the distribution, then the +Makefile should not put it in the source directory, because building a +program in ordinary circumstances should not modify the source directory +in any way. + +Try to make the build and installation targets, at least (and all their +subtargets) work correctly with a parallel @code{make}. + +@node Utilities in Makefiles +@section Utilities in Makefiles + +Write the Makefile commands (and any shell scripts, such as +@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any +special features of @code{ksh} or @code{bash}. + +The @code{configure} script and the Makefile rules for building and +installation should not use any utilities directly except these: + +@c dd find +@c gunzip gzip md5sum +@c mkfifo mknod tee uname + +@example +cat cmp cp diff echo egrep expr false grep install-info +ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true +@end example + +The compression program @code{gzip} can be used in the @code{dist} rule. + +Stick to the generally supported options for these programs. For +example, don't use @samp{mkdir -p}, convenient as it may be, because +most systems don't support it. + +It is a good idea to avoid creating symbolic links in makefiles, since a +few systems don't support them. + +The Makefile rules for building and installation can also use compilers +and related programs, but should do so via @code{make} variables so that the +user can substitute alternatives. Here are some of the programs we +mean: + +@example +ar bison cc flex install ld ldconfig lex +make makeinfo ranlib texi2dvi yacc +@end example + +Use the following @code{make} variables to run those programs: + +@example +$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) +$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) +@end example + +When you use @code{ranlib} or @code{ldconfig}, you should make sure +nothing bad happens if the system does not have the program in question. +Arrange to ignore an error from that command, and print a message before +the command to tell the user that failure of this command does not mean +a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with +this.) + +If you use symbolic links, you should implement a fallback for systems +that don't have symbolic links. + +Additional utilities that can be used via Make variables are: + +@example +chgrp chmod chown mknod +@end example + +It is ok to use other utilities in Makefile portions (or scripts) +intended only for particular systems where you know those utilities +exist. + +@node Command Variables +@section Variables for Specifying Commands + +Makefiles should provide variables for overriding certain commands, options, +and so on. + +In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named @code{BISON} whose default +value is set with @samp{BISON = bison}, and refer to it with +@code{$(BISON)} whenever you need to use Bison. + +File management utilities such as @code{ln}, @code{rm}, @code{mv}, and +so on, need not be referred to through variables in this way, since users +don't need to replace them with other programs. + +Each program-name variable should come with an options variable that is +used to supply options to the program. Append @samp{FLAGS} to the +program-name variable name to get the options variable name---for +example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C +compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are +exceptions to this rule, but we keep them because they are standard.) +Use @code{CPPFLAGS} in any compilation command that runs the +preprocessor, and use @code{LDFLAGS} in any compilation command that +does linking as well as in any direct use of @code{ld}. + +If there are C compiler options that @emph{must} be used for proper +compilation of certain files, do not include them in @code{CFLAGS}. +Users expect to be able to specify @code{CFLAGS} freely themselves. +Instead, arrange to pass the necessary options to the C compiler +independently of @code{CFLAGS}, by writing them explicitly in the +compilation commands or by defining an implicit rule, like this: + +@smallexample +CFLAGS = -g +ALL_CFLAGS = -I. $(CFLAGS) +.c.o: + $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< +@end smallexample + +Do include the @samp{-g} option in @code{CFLAGS}, because that is not +@emph{required} for proper compilation. You can consider it a default +that is only recommended. If the package is set up so that it is +compiled with GCC by default, then you might as well include @samp{-O} +in the default value of @code{CFLAGS} as well. + +Put @code{CFLAGS} last in the compilation command, after other variables +containing compiler options, so the user can use @code{CFLAGS} to +override the others. + +@code{CFLAGS} should be used in every invocation of the C compiler, +both those which do compilation and those which do linking. + +Every Makefile should define the variable @code{INSTALL}, which is the +basic command for installing a file into the system. + +Every Makefile should also define the variables @code{INSTALL_PROGRAM} +and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should +be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be +@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the +commands for actual installation, for executables and nonexecutables +respectively. Use these variables as follows: + +@example +$(INSTALL_PROGRAM) foo $(bindir)/foo +$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a +@end example + +Optionally, you may prepend the value of @code{DESTDIR} to the target +filename. Doing this allows the installer to create a snapshot of the +installation to be copied onto the real target filesystem later. Do not +set the value of @code{DESTDIR} in your Makefile, and do not include it +in any installed files. With support for @code{DESTDIR}, the above +examples become: + +@example +$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo +$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a +@end example + +@noindent +Always use a file name, not a directory name, as the second argument of +the installation commands. Use a separate command for each file to be +installed. + +@node Directory Variables +@section Variables for Installation Directories + +Installation directories should always be named by variables, so it is +easy to install in a nonstandard place. The standard names for these +variables are described below. They are based on a standard filesystem +layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4, +and other modern operating systems. + +These two variables set the root for the installation. All the other +installation directories should be subdirectories of one of these two, +and nothing should be directly installed into these two directories. + +@table @code +@item prefix +@vindex prefix +A prefix used in constructing the default values of the variables listed +below. The default value of @code{prefix} should be @file{/usr/local}. +When building the complete GNU system, the prefix will be empty and +@file{/usr} will be a symbolic link to @file{/}. +(If you are using Autoconf, write it as @samp{@@prefix@@}.) + +Running @samp{make install} with a different value of @code{prefix} from +the one used to build the program should @emph{not} recompile the +program. + +@item exec_prefix +@vindex exec_prefix +A prefix used in constructing the default values of some of the +variables listed below. The default value of @code{exec_prefix} should +be @code{$(prefix)}. +(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) + +Generally, @code{$(exec_prefix)} is used for directories that contain +machine-specific files (such as executables and subroutine libraries), +while @code{$(prefix)} is used directly for other directories. + +Running @samp{make install} with a different value of @code{exec_prefix} +from the one used to build the program should @emph{not} recompile the +program. +@end table + +Executable programs are installed in one of the following directories. + +@table @code +@item bindir +@vindex bindir +The directory for installing executable programs that users can run. +This should normally be @file{/usr/local/bin}, but write it as +@file{$(exec_prefix)/bin}. +(If you are using Autoconf, write it as @samp{@@bindir@@}.) + +@item sbindir +@vindex sbindir +The directory for installing executable programs that can be run from +the shell, but are only generally useful to system administrators. This +should normally be @file{/usr/local/sbin}, but write it as +@file{$(exec_prefix)/sbin}. +(If you are using Autoconf, write it as @samp{@@sbindir@@}.) + +@item libexecdir +@vindex libexecdir +@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 +The directory for installing executable programs to be run by other +programs rather than by users. This directory should normally be +@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. +(If you are using Autoconf, write it as @samp{@@libexecdir@@}.) +@end table + +Data files used by the program during its execution are divided into +categories in two ways. + +@itemize @bullet +@item +Some files are normally modified by programs; others are never normally +modified (though users may edit some of these). + +@item +Some files are architecture-independent and can be shared by all +machines at a site; some are architecture-dependent and can be shared +only by machines of the same kind and operating system; others may never +be shared between two machines. +@end itemize + +This makes for six different possibilities. However, we want to +discourage the use of architecture-dependent files, aside from object +files and libraries. It is much cleaner to make other data files +architecture-independent, and it is generally not hard. + +Here are the variables Makefiles should use to specify directories +to put these various kinds of files in: + +@table @samp +@item datarootdir +The root of the directory tree for read-only architecture-independent +data files. This should normally be @file{/usr/local/share}, but +write it as @file{$(prefix)/share}. @samp{datadir}'s default value is +based on this variable; so are @samp{infodir}, @samp{mandir}, and others. + +@item datadir +The directory for installing ideosyncratic read-only +architecture-independent data files for this program. This is usually +the same place as @samp{datarootdir}, but we use the two separate +variables so that you can move these ideosyncratic files without +altering the location for Info files, man pages, etc. + +The default definition of @samp{datadir} should be +@file{$(datarootdir)}. (If you are using Autoconf, write it as +@samp{@@datadir@@}.) + +@item sysconfdir +The directory for installing read-only data files that pertain to a +single machine--that is to say, files for configuring a host. Mailer +and network configuration files, @file{/etc/passwd}, and so forth belong +here. All the files in this directory should be ordinary ASCII text +files. This directory should normally be @file{/usr/local/etc}, but +write it as @file{$(prefix)/etc}. +(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) + +Do not install executables here in this directory (they probably belong +in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install +files that are modified in the normal course of their use (programs +whose purpose is to change the configuration of the system excluded). +Those probably belong in @file{$(localstatedir)}. + +@item sharedstatedir +The directory for installing architecture-independent data files which +the programs modify while they run. This should normally be +@file{/usr/local/com}, but write it as @file{$(prefix)/com}. +(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) + +@item localstatedir +The directory for installing data files which the programs modify while +they run, and that pertain to one specific machine. Users should never +need to modify files in this directory to configure the package's +operation; put such configuration information in separate files that go +in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} +should normally be @file{/usr/local/var}, but write it as +@file{$(prefix)/var}. +(If you are using Autoconf, write it as @samp{@@localstatedir@@}.) +@end table + +These variables specify the directory for installing certain specific +types of files, if your program has them. Every GNU package should +have Info files, so every program needs @samp{infodir}, but not all +need @samp{libdir} or @samp{lispdir}. + +@table @samp +@item includedir +@c rewritten to avoid overfull hbox --roland +The directory for installing header files to be included by user +programs with the C @samp{#include} preprocessor directive. This +should normally be @file{/usr/local/include}, but write it as +@file{$(prefix)/include}. +(If you are using Autoconf, write it as @samp{@@includedir@@}.) + +Most compilers other than GCC do not look for header files in directory +@file{/usr/local/include}. So installing the header files this way is +only useful with GCC. Sometimes this is not a problem because some +libraries are only really intended to work with GCC. But some libraries +are intended to work with other compilers. They should install their +header files in two places, one specified by @code{includedir} and one +specified by @code{oldincludedir}. + +@item oldincludedir +The directory for installing @samp{#include} header files for use with +compilers other than GCC. This should normally be @file{/usr/include}. +(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) + +The Makefile commands should check whether the value of +@code{oldincludedir} is empty. If it is, they should not try to use +it; they should cancel the second installation of the header files. + +A package should not replace an existing header in this directory unless +the header came from the same package. Thus, if your Foo package +provides a header file @file{foo.h}, then it should install the header +file in the @code{oldincludedir} directory if either (1) there is no +@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo +package. + +To tell whether @file{foo.h} came from the Foo package, put a magic +string in the file---part of a comment---and @code{grep} for that string. + +@item infodir +The directory for installing the Info files for this package. By +default, it should be @file{/usr/local/share/info}, but it should be +written as @file{$(datarootdir)/info}. (If you are using Autoconf, +write it as @samp{@@infodir@@}.) + +@item libdir +The directory for object files and libraries of object code. Do not +install executables here, they probably ought to go in @file{$(libexecdir)} +instead. The value of @code{libdir} should normally be +@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. +(If you are using Autoconf, write it as @samp{@@libdir@@}.) + +@item lispdir +The directory for installing any Emacs Lisp files in this package. By +default, it should be @file{/usr/local/share/emacs/site-lisp}, but it +should be written as @file{$(datarootdir)/emacs/site-lisp}. + +If you are using Autoconf, write the default as @samp{@@lispdir@@}. +In order to make @samp{@@lispdir@@} work, you need the following lines +in your @file{configure.in} file: + +@example +lispdir='$@{datarootdir@}/emacs/site-lisp' +AC_SUBST(lispdir) +@end example + +@item localedir +The directory for installing locale-specific message catalogs for this +package. By default, it should be @file{/usr/local/share/locale}, but +it should be written as @file{$(datarootdir)/locale}. (If you are +using Autoconf, write it as @samp{@@localedir@@}.) +@end table + +Unix-style man pages are installed in one of the following: + +@table @samp +@item mandir +The top-level directory for installing the man pages (if any) for this +package. It will normally be @file{/usr/local/share/man}, but you +should write it as @file{$(datarootdir)/man}. (If you are using +Autoconf, write it as @samp{@@mandir@@}.) + +@item man1dir +The directory for installing section 1 man pages. Write it as +@file{$(mandir)/man1}. +@item man2dir +The directory for installing section 2 man pages. Write it as +@file{$(mandir)/man2} +@item @dots{} + +@strong{Don't make the primary documentation for any GNU software be a +man page. Write a manual in Texinfo instead. Man pages are just for +the sake of people running GNU software on Unix, which is a secondary +application only.} + +@item manext +The file name extension for the installed man page. This should contain +a period followed by the appropriate digit; it should normally be @samp{.1}. + +@item man1ext +The file name extension for installed section 1 man pages. +@item man2ext +The file name extension for installed section 2 man pages. +@item @dots{} +Use these names instead of @samp{manext} if the package needs to install man +pages in more than one section of the manual. +@end table + +And finally, you should set the following variable: + +@table @samp +@item srcdir +The directory for the sources being compiled. The value of this +variable is normally inserted by the @code{configure} shell script. +(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.) +@end table + +For example: + +@smallexample +@c I have changed some of the comments here slightly to fix an overfull +@c hbox, so the make manual can format correctly. --roland +# Common prefix for installation directories. +# NOTE: This directory must exist when you start the install. +prefix = /usr/local +datarootdir = $(prefix)/share +datadir = $(datarootdir) +exec_prefix = $(prefix) +# Where to put the executable for the command `gcc'. +bindir = $(exec_prefix)/bin +# Where to put the directories used by the compiler. +libexecdir = $(exec_prefix)/libexec +# Where to put the Info files. +infodir = $(datarootdir)/info +@end smallexample + +If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the @code{install} rule to create these subdirectories. + +Do not expect the user to include the subdirectory name in the value of +any of the variables listed above. The idea of having a uniform set of +variable names for installation directories is to enable the user to +specify the exact same values for several different GNU packages. In +order for this to be useful, all the packages must be designed so that +they will work sensibly when the user does so. + +@node Standard Targets +@section Standard Targets for Users + +All GNU programs should have the following targets in their Makefiles: + +@table @samp +@item all +Compile the entire program. This should be the default target. This +target need not rebuild any documentation files; Info files should +normally be included in the distribution, and DVI files should be made +only when explicitly asked for. + +By default, the Make rules should compile and link with @samp{-g}, so +that executable programs have debugging symbols. Users who don't mind +being helpless can strip the executables later if they wish. + +@item install +Compile the program and copy the executables, libraries, and so on to +the file names where they should reside for actual use. If there is a +simple test to verify that a program is properly installed, this target +should run that test. + +Do not strip executables when installing them. Devil-may-care users can +use the @code{install-strip} target to do that. + +If possible, write the @code{install} target rule so that it does not +modify anything in the directory where the program was built, provided +@samp{make all} has just been done. This is convenient for building the +program under one user name and installing it under another. + +The commands should create all the directories in which files are to be +installed, if they don't already exist. This includes the directories +specified as the values of the variables @code{prefix} and +@code{exec_prefix}, as well as all subdirectories that are needed. +One way to do this is by means of an @code{installdirs} target +as described below. + +Use @samp{-} before any command for installing a man page, so that +@code{make} will ignore any errors. This is in case there are systems +that don't have the Unix man page documentation system installed. + +The way to install Info files is to copy them into @file{$(infodir)} +with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run +the @code{install-info} program if it is present. @code{install-info} +is a program that edits the Info @file{dir} file to add or update the +menu entry for the given Info file; it is part of the Texinfo package. +Here is a sample rule to install an Info file: + +@comment This example has been carefully formatted for the Make manual. +@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. +@smallexample +$(DESTDIR)$(infodir)/foo.info: foo.info + $(POST_INSTALL) +# There may be a newer info file in . than in srcdir. + -if test -f foo.info; then d=.; \ + else d=$(srcdir); fi; \ + $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \ +# Run install-info only if it exists. +# Use `if' instead of just prepending `-' to the +# line so we notice real errors from install-info. +# We use `$(SHELL) -c' because some shells do not +# fail gracefully when there is an unknown command. + if $(SHELL) -c 'install-info --version' \ + >/dev/null 2>&1; then \ + install-info --dir-file=$(DESTDIR)$(infodir)/dir \ + $(DESTDIR)$(infodir)/foo.info; \ + else true; fi +@end smallexample + +When writing the @code{install} target, you must classify all the +commands into three categories: normal ones, @dfn{pre-installation} +commands and @dfn{post-installation} commands. @xref{Install Command +Categories}. + +@item uninstall +Delete all the installed files---the copies that the @samp{install} +target creates. + +This rule should not modify the directories where compilation is done, +only the directories where files are installed. + +The uninstallation commands are divided into three categories, just like +the installation commands. @xref{Install Command Categories}. + +@item install-strip +Like @code{install}, but strip the executable files while installing +them. In simple cases, this target can use the @code{install} target in +a simple way: + +@smallexample +install-strip: + $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ + install +@end smallexample + +But if the package installs scripts as well as real executables, the +@code{install-strip} target can't just refer to the @code{install} +target; it has to strip the executables but not the scripts. + +@code{install-strip} should not strip the executables in the build +directory which are being copied for installation. It should only strip +the copies that are installed. + +Normally we do not recommend stripping an executable unless you are sure +the program has no bugs. However, it can be reasonable to install a +stripped executable for actual execution while saving the unstripped +executable elsewhere in case there is a bug. + +@comment The gratuitous blank line here is to make the table look better +@comment in the printed Make manual. Please leave it in. +@item clean + +Delete all files from the current directory that are normally created by +building the program. Don't delete the files that record the +configuration. Also preserve files that could be made by building, but +normally aren't because the distribution comes with them. + +Delete @file{.dvi} files here if they are not part of the distribution. + +@item distclean +Delete all files from the current directory that are created by +configuring or building the program. If you have unpacked the source +and built the program without creating any other files, @samp{make +distclean} should leave only the files that were in the distribution. + +@item mostlyclean +Like @samp{clean}, but may refrain from deleting a few files that people +normally don't want to recompile. For example, the @samp{mostlyclean} +target for GCC does not delete @file{libgcc.a}, because recompiling it +is rarely necessary and takes a lot of time. + +@item maintainer-clean +Delete almost everything from the current directory that can be +reconstructed with this Makefile. This typically includes everything +deleted by @code{distclean}, plus more: C source files produced by +Bison, tags tables, Info files, and so on. + +The reason we say ``almost everything'' is that running the command +@samp{make maintainer-clean} should not delete @file{configure} even if +@file{configure} can be remade using a rule in the Makefile. More generally, +@samp{make maintainer-clean} should not delete anything that needs to +exist in order to run @file{configure} and then begin to build the +program. This is the only exception; @code{maintainer-clean} should +delete everything else that can be rebuilt. + +The @samp{maintainer-clean} target is intended to be used by a maintainer of +the package, not by ordinary users. You may need special tools to +reconstruct some of the files that @samp{make maintainer-clean} deletes. +Since these files are normally included in the distribution, we don't +take care to make them easy to reconstruct. If you find you need to +unpack the full distribution again, don't blame us. + +To help make users aware of this, the commands for the special +@code{maintainer-clean} target should start with these two: + +@smallexample +@@echo 'This command is intended for maintainers to use; it' +@@echo 'deletes files that may need special tools to rebuild.' +@end smallexample + +@item TAGS +Update a tags table for this program. +@c ADR: how? + +@item info +Generate any Info files needed. The best way to write the rules is as +follows: + +@smallexample +info: foo.info + +foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{MAKEINFO} in the Makefile. It should +run the @code{makeinfo} program, which is part of the Texinfo +distribution. + +Normally a GNU distribution comes with Info files, and that means the +Info files are present in the source directory. Therefore, the Make +rule for an info file should update it in the source directory. When +users build the package, ordinarily Make will not update the Info files +because they will already be up to date. + +@item dvi +Generate DVI files for all Texinfo documentation. +For example: + +@smallexample +dvi: foo.dvi + +foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{TEXI2DVI} in the Makefile. It should +run the program @code{texi2dvi}, which is part of the Texinfo +distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work +of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, +write just the dependencies, and allow GNU @code{make} to provide the command. + +@item dist +Create a distribution tar file for this program. The tar file should be +set up so that the file names in the tar file start with a subdirectory +name which is the name of the package it is a distribution for. This +name can include the version number. + +For example, the distribution tar file of GCC version 1.40 unpacks into +a subdirectory named @file{gcc-1.40}. + +The easiest way to do this is to create a subdirectory appropriately +named, use @code{ln} or @code{cp} to install the proper files in it, and +then @code{tar} that subdirectory. + +Compress the tar file with @code{gzip}. For example, the actual +distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. + +The @code{dist} target should explicitly depend on all non-source files +that are in the distribution, to make sure they are up to date in the +distribution. +@ifset CODESTD +@xref{Releases, , Making Releases}. +@end ifset +@ifclear CODESTD +@xref{Releases, , Making Releases, standards, GNU Coding Standards}. +@end ifclear + +@item check +Perform self-tests (if any). The user must build the program before +running the tests, but need not install the program; you should write +the self-tests so that they work when the program is built but not +installed. +@end table + +The following targets are suggested as conventional names, for programs +in which they are useful. + +@table @code +@item installcheck +Perform installation tests (if any). The user must build and install +the program before running the tests. You should not assume that +@file{$(bindir)} is in the search path. + +@item installdirs +It's useful to add a target named @samp{installdirs} to create the +directories where files are installed, and their parent directories. +There is a script called @file{mkinstalldirs} which is convenient for +this; you can find it in the Texinfo package. +@c It's in /gd/gnu/lib/mkinstalldirs. +You can use a rule like this: + +@comment This has been carefully formatted to look decent in the Make manual. +@comment Please be sure not to make it extend any further to the right.--roland +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) +@end smallexample + +@noindent +or, if you wish to support @env{DESTDIR}, + +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs \ + $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ + $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ + $(DESTDIR)$(mandir) +@end smallexample + +This rule should not modify the directories where compilation is done. +It should do nothing but create installation directories. +@end table + +@node Install Command Categories +@section Install Command Categories + +@cindex pre-installation commands +@cindex post-installation commands +When writing the @code{install} target, you must classify all the +commands into three categories: normal ones, @dfn{pre-installation} +commands and @dfn{post-installation} commands. + +Normal commands move files into their proper places, and set their +modes. They may not alter any files except the ones that come entirely +from the package they belong to. + +Pre-installation and post-installation commands may alter other files; +in particular, they can edit global configuration files or data bases. + +Pre-installation commands are typically executed before the normal +commands, and post-installation commands are typically run after the +normal commands. + +The most common use for a post-installation command is to run +@code{install-info}. This cannot be done with a normal command, since +it alters a file (the Info directory) which does not come entirely and +solely from the package being installed. It is a post-installation +command because it needs to be done after the normal command which +installs the package's Info files. + +Most programs don't need any pre-installation commands, but we have the +feature just in case it is needed. + +To classify the commands in the @code{install} rule into these three +categories, insert @dfn{category lines} among them. A category line +specifies the category for the commands that follow. + +A category line consists of a tab and a reference to a special Make +variable, plus an optional comment at the end. There are three +variables you can use, one for each category; the variable name +specifies the category. Category lines are no-ops in ordinary execution +because these three Make variables are normally undefined (and you +@emph{should not} define them in the makefile). + +Here are the three possible category lines, each with a comment that +explains what it means: + +@smallexample + $(PRE_INSTALL) # @r{Pre-install commands follow.} + $(POST_INSTALL) # @r{Post-install commands follow.} + $(NORMAL_INSTALL) # @r{Normal commands follow.} +@end smallexample + +If you don't use a category line at the beginning of the @code{install} +rule, all the commands are classified as normal until the first category +line. If you don't use any category lines, all the commands are +classified as normal. + +These are the category lines for @code{uninstall}: + +@smallexample + $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.} + $(POST_UNINSTALL) # @r{Post-uninstall commands follow.} + $(NORMAL_UNINSTALL) # @r{Normal commands follow.} +@end smallexample + +Typically, a pre-uninstall command would be used for deleting entries +from the Info directory. + +If the @code{install} or @code{uninstall} target has any dependencies +which act as subroutines of installation, then you should start +@emph{each} dependency's commands with a category line, and start the +main target's commands with a category line also. This way, you can +ensure that each command is placed in the right category regardless of +which of the dependencies actually run. + +Pre-installation and post-installation commands should not run any +programs except for these: + +@example +[ basename bash cat chgrp chmod chown cmp cp dd diff echo +egrep expand expr false fgrep find getopt grep gunzip gzip +hostname install install-info kill ldconfig ln ls md5sum +mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee +test touch true uname xargs yes +@end example + +@cindex binary packages +The reason for distinguishing the commands in this way is for the sake +of making binary packages. Typically a binary package contains all the +executables and other files that need to be installed, and has its own +method of installing them---so it does not need to run the normal +installation commands. But installing the binary package does need to +execute the pre-installation and post-installation commands. + +Programs to build binary packages work by extracting the +pre-installation and post-installation commands. Here is one way of +extracting the pre-installation commands: + +@smallexample +make -n install -o all \ + PRE_INSTALL=pre-install \ + POST_INSTALL=post-install \ + NORMAL_INSTALL=normal-install \ + | gawk -f pre-install.awk +@end smallexample + +@noindent +where the file @file{pre-install.awk} could contain this: + +@smallexample +$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@} +on @{print $0@} +$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@} +@end smallexample + +The resulting file of pre-installation commands is executed as a shell +script as part of installing the binary package.
new file mode 100644 --- /dev/null +++ b/doc/standards.texi @@ -0,0 +1,3868 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename standards.info +@settitle GNU Coding Standards +@c This date is automagically updated when you save this file: +@set lastupdate February 20, 2004 +@c %**end of header + +@dircategory GNU organization +@direntry +* Standards: (standards). GNU coding standards. +@end direntry + +@c @setchapternewpage odd +@setchapternewpage off + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex vr cp + +@c This is used by a cross ref in make-stds.texi +@set CODESTD 1 +@iftex +@set CHAPTER chapter +@end iftex +@ifinfo +@set CHAPTER node +@end ifinfo + +@copying +The GNU coding standards, last updated @value{lastupdate}. + +Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +2001, 2002, 2003, 2004 Free Software Foundation, Inc. + +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''. +@end copying + +@titlepage +@title GNU Coding Standards +@author Richard Stallman, et al. +@author last updated @value{lastupdate} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top, Preface, (dir), (dir) +@top Version + +@insertcopying +@end ifnottex + +@menu +* Preface:: About the GNU Coding Standards +* Legal Issues:: Keeping Free Software Free +* Design Advice:: General Program Design +* Program Behavior:: Program Behavior for All Programs +* Writing C:: Making The Best Use of C +* Documentation:: Documenting Programs +* Managing Releases:: The Release Process +* References:: References to Non-Free Software or Documentation +* Copying This Manual:: How to Make Copies of This Manual +* Index:: + +@end menu + +@node Preface +@chapter About the GNU Coding Standards + +The GNU Coding Standards were written by Richard Stallman and other GNU +Project volunteers. Their purpose is to make the GNU system clean, +consistent, and easy to install. This document can also be read as a +guide to writing portable, robust and reliable programs. It focuses on +programs written in C, but many of the rules and principles are useful +even if you write in another programming language. The rules often +state reasons for writing in a certain way. + +This release of the GNU Coding Standards was last updated +@value{lastupdate}. + +@cindex where to obtain @code{standards.texi} +@cindex downloading this manual +If you did not obtain this file directly from the GNU project and +recently, please check for a newer version. You can get the GNU +Coding Standards from the GNU World Wide Web server host in several +different formats: @uref{http://www.gnu.org/prep/standards.text}, +@uref{http://www.gnu.org/prep/standards.info}, and +@uref{http://www.gnu.org/prep/standards.dvi}, as well as the +Texinfo ``source'' which is divided in two files: +@uref{http://www.gnu.org/prep/standards.texi} and +@uref{http://www.gnu.org/prep/make-stds.texi}. The GNU Coding +Standards are also available in HTML format starting at +@uref{http://www.gnu.org/prep/standards_toc.html}. + +Corrections or suggestions for this document should be sent to +@email{bug-standards@@gnu.org}. If you make a suggestion, please include a +suggested new wording for it; our time is limited. We prefer a context +diff to the @file{standards.texi} or @file{make-stds.texi} files, but if +you don't have those files, please mail your suggestion anyway. + +These standards cover the minimum of what is important when writing a +GNU package. Likely, the needs for additional standards will come up. +Sometimes, you might suggest that such standards be added to this +document. If you think your standards would be generally useful, please +do suggest them. + +You should also set standards for your package on many questions not +addressed or not firmly specified here. The most important point is to +be self-consistent---try to stick to the conventions you pick, and try +to document them as much as possible. That way, your program will be +more maintainable by others. + +The GNU Hello program serves as an example of how to follow the GNU +coding standards for a trivial program which prints @samp{Hello, +world!}. @uref{http://www.gnu.org/software/hello/hello.html}. + +@node Legal Issues +@chapter Keeping Free Software Free +@cindex legal aspects + +This @value{CHAPTER} discusses how you can make sure that GNU software +avoids legal difficulties, and other related issues. + +@menu +* Reading Non-Free Code:: Referring to Proprietary Programs +* Contributions:: Accepting Contributions +* Trademarks:: How We Deal with Trademark Issues +@end menu + +@node Reading Non-Free Code +@section Referring to Proprietary Programs +@cindex proprietary programs +@cindex avoiding proprietary code + +Don't in any circumstances refer to Unix source code for or during +your work on GNU! (Or to any other proprietary programs.) + +If you have a vague recollection of the internals of a Unix program, +this does not absolutely mean you can't write an imitation of it, but +do try to organize the imitation internally along different lines, +because this is likely to make the details of the Unix version +irrelevant and dissimilar to your results. + +For example, Unix utilities were generally optimized to minimize +memory use; if you go for speed instead, your program will be very +different. You could keep the entire input file in core and scan it +there instead of using stdio. Use a smarter algorithm discovered more +recently than the Unix program. Eliminate use of temporary files. Do +it in one pass instead of two (we did this in the assembler). + +Or, on the contrary, emphasize simplicity instead of speed. For some +applications, the speed of today's computers makes simpler algorithms +adequate. + +Or go for generality. For example, Unix programs often have static +tables or fixed-size strings, which make for arbitrary limits; use +dynamic allocation instead. Make sure your program handles NULs and +other funny characters in the input files. Add a programming language +for extensibility and write part of the program in that language. + +Or turn some parts of the program into independently usable libraries. +Or use a simple garbage collector instead of tracking precisely when +to free memory, or use a new GNU facility such as obstacks. + +@node Contributions +@section Accepting Contributions +@cindex legal papers +@cindex accepting contributions + +If the program you are working on is copyrighted by the Free Software +Foundation, then when someone else sends you a piece of code to add to +the program, we need legal papers to use it---just as we asked you to +sign papers initially. @emph{Each} person who makes a nontrivial +contribution to a program must sign some sort of legal papers in order +for us to have clear title to the program; the main author alone is not +enough. + +So, before adding in any contributions from other people, please tell +us, so we can arrange to get the papers. Then wait until we tell you +that we have received the signed papers, before you actually use the +contribution. + +This applies both before you release the program and afterward. If +you receive diffs to fix a bug, and they make significant changes, we +need legal papers for that change. + +This also applies to comments and documentation files. For copyright +law, comments and code are just text. Copyright applies to all kinds of +text, so we need legal papers for all kinds. + +We know it is frustrating to ask for legal papers; it's frustrating for +us as well. But if you don't wait, you are going out on a limb---for +example, what if the contributor's employer won't sign a disclaimer? +You might have to take that code out again! + +You don't need papers for changes of a few lines here or there, since +they are not significant for copyright purposes. Also, you don't need +papers if all you get from the suggestion is some ideas, not actual code +which you use. For example, if someone send you one implementation, but +you write a different implementation of the same idea, you don't need to +get papers. + +The very worst thing is if you forget to tell us about the other +contributor. We could be very embarrassed in court some day as a +result. + +We have more detailed advice for maintainers of programs; if you have +reached the stage of actually maintaining a program for GNU (whether +released or not), please ask us for a copy. + +@node Trademarks +@section Trademarks +@cindex trademarks + +Please do not include any trademark acknowledgements in GNU software +packages or documentation. + +Trademark acknowledgements are the statements that such-and-such is a +trademark of so-and-so. The GNU Project has no objection to the basic +idea of trademarks, but these acknowledgements feel like kowtowing, +and there is no legal requirement for them, so we don't use them. + +What is legally required, as regards other people's trademarks, is to +avoid using them in ways which a reader might reasonably understand as +naming or labeling our own programs or activities. For example, since +``Objective C'' is (or at least was) a trademark, we made sure to say +that we provide a ``compiler for the Objective C language'' rather +than an ``Objective C compiler''. The latter would have been meant as +a shorter way of saying the former, but it does not explicitly state +the relationship, so it could be misinterpreted as using ``Objective +C'' as a label for the compiler rather than for the language. + +Please don't use ``win'' as an abbreviation for Microsoft Windows in +GNU software or documentation. In hacker terminology, calling +something a "win" is a form of praise. If you wish to praise +Microsoft Windows when speaking on your own, by all means do so, but +not in GNU software. Usually we write the word ``windows'' in full, +but when brevity is very important (as in file names and sometimes +symbol names), we abbreviate it to ``w''. For instance, the files and +functions in Emacs that deal with Windows start with @samp{w32}. + +@node Design Advice +@chapter General Program Design +@cindex program design + +This @value{CHAPTER} discusses some of the issues you should take into +account when designing your program. + +@c Standard or ANSI C +@c +@c In 1989 the American National Standards Institute (ANSI) standardized +@c C as standard X3.159-1989. In December of that year the +@c International Standards Organization ISO adopted the ANSI C standard +@c making minor changes. In 1990 ANSI then re-adopted ISO standard +@c C. This version of C is known as either ANSI C or Standard C. + +@c A major revision of the C Standard appeared in 1999. + +@menu +* Source Language:: Which languges to use. +* Compatibility:: Compatibility with other implementations +* Using Extensions:: Using non-standard features +* Standard C:: Using Standard C features +* Conditional Compilation:: Compiling Code Only If A Conditional is True +@end menu + +@node Source Language +@section Which Languages to Use +@cindex programming languges + +When you want to use a language that gets compiled and runs at high +speed, the best language to use is C. Using another language is like +using a non-standard feature: it will cause trouble for users. Even if +GCC supports the other language, users may find it inconvenient to have +to install the compiler for that other language in order to build your +program. For example, if you write your program in C++, people will +have to install the GNU C++ compiler in order to compile your program. + +C has one other advantage over C++ and other compiled languages: more +people know C, so more people will find it easy to read and modify the +program if it is written in C. + +So in general it is much better to use C, rather than the +comparable alternatives. + +But there are two exceptions to that conclusion: + +@itemize @bullet +@item +It is no problem to use another language to write a tool specifically +intended for use with that language. That is because the only people +who want to build the tool will be those who have installed the other +language anyway. + +@item +If an application is of interest only to a narrow part of the community, +then the question of which language it is written in has less effect on +other people, so you may as well please yourself. +@end itemize + +Many programs are designed to be extensible: they include an interpreter +for a language that is higher level than C. Often much of the program +is written in that language, too. The Emacs editor pioneered this +technique. + +@cindex GUILE +The standard extensibility interpreter for GNU software is GUILE, which +implements the language Scheme (an especially clean and simple dialect +of Lisp). @uref{http://www.gnu.org/software/guile/}. We don't reject +programs written in other ``scripting languages'' such as Perl and +Python, but using GUILE is very important for the overall consistency of +the GNU system. + +@node Compatibility +@section Compatibility with Other Implementations +@cindex compatibility with C and @sc{posix} standards +@cindex @sc{posix} compatibility + +With occasional exceptions, utility programs and libraries for GNU +should be upward compatible with those in Berkeley Unix, and upward +compatible with Standard C if Standard C specifies their +behavior, and upward compatible with @sc{posix} if @sc{posix} specifies +their behavior. + +When these standards conflict, it is useful to offer compatibility +modes for each of them. + +@cindex options for compatibility +Standard C and @sc{posix} prohibit many kinds of extensions. Feel +free to make the extensions anyway, and include a @samp{--ansi}, +@samp{--posix}, or @samp{--compatible} option to turn them off. +However, if the extension has a significant chance of breaking any real +programs or scripts, then it is not really upward compatible. So you +should try to redesign its interface to make it upward compatible. + +@cindex @code{POSIXLY_CORRECT}, environment variable +Many GNU programs suppress extensions that conflict with @sc{posix} if the +environment variable @code{POSIXLY_CORRECT} is defined (even if it is +defined with a null value). Please make your program recognize this +variable if appropriate. + +When a feature is used only by users (not by programs or command +files), and it is done poorly in Unix, feel free to replace it +completely with something totally different and better. (For example, +@code{vi} is replaced with Emacs.) But it is nice to offer a compatible +feature as well. (There is a free @code{vi} clone, so we offer it.) + +Additional useful features are welcome regardless of whether +there is any precedent for them. + +@node Using Extensions +@section Using Non-standard Features +@cindex non-standard extensions + +Many GNU facilities that already exist support a number of convenient +extensions over the comparable Unix facilities. Whether to use these +extensions in implementing your program is a difficult question. + +On the one hand, using the extensions can make a cleaner program. +On the other hand, people will not be able to build the program +unless the other GNU tools are available. This might cause the +program to work on fewer kinds of machines. + +With some extensions, it might be easy to provide both alternatives. +For example, you can define functions with a ``keyword'' @code{INLINE} +and define that as a macro to expand into either @code{inline} or +nothing, depending on the compiler. + +In general, perhaps it is best not to use the extensions if you can +straightforwardly do without them, but to use the extensions if they +are a big improvement. + +An exception to this rule are the large, established programs (such as +Emacs) which run on a great variety of systems. Using GNU extensions in +such programs would make many users unhappy, so we don't do that. + +Another exception is for programs that are used as part of compilation: +anything that must be compiled with other compilers in order to +bootstrap the GNU compilation facilities. If these require the GNU +compiler, then no one can compile them without having them installed +already. That would be extremely troublesome in certain cases. + +@node Standard C +@section Standard C and Pre-Standard C +@cindex @sc{ansi} C standard + +1989 Standard C is widespread enough now that it is ok to use its +features in new programs. There is one exception: do not ever use the +``trigraph'' feature of Standard C. + +1999 Standard C is not widespread yet, so please do not require its +features in programs. It is ok to use its features if they are present. + +However, it is easy to support pre-standard compilers in most programs, +so if you know how to do that, feel free. If a program you are +maintaining has such support, you should try to keep it working. + +@cindex function prototypes +To support pre-standard C, instead of writing function definitions in +standard prototype form, + +@example +int +foo (int x, int y) +@dots{} +@end example + +@noindent +write the definition in pre-standard style like this, + +@example +int +foo (x, y) + int x, y; +@dots{} +@end example + +@noindent +and use a separate declaration to specify the argument prototype: + +@example +int foo (int, int); +@end example + +You need such a declaration anyway, in a header file, to get the benefit +of prototypes in all the files where the function is called. And once +you have the declaration, you normally lose nothing by writing the +function definition in the pre-standard style. + +This technique does not work for integer types narrower than @code{int}. +If you think of an argument as being of a type narrower than @code{int}, +declare it as @code{int} instead. + +There are a few special cases where this technique is hard to use. For +example, if a function argument needs to hold the system type +@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than +@code{int} on some machines; but you cannot use @code{int} instead, +because @code{dev_t} is wider than @code{int} on some machines. There +is no type you can safely use on all machines in a non-standard +definition. The only way to support non-standard C and pass such an +argument is to check the width of @code{dev_t} using Autoconf and choose +the argument type accordingly. This may not be worth the trouble. + +In order to support pre-standard compilers that do not recognize +prototypes, you may want to use a preprocessor macro like this: + +@example +/* Declare the prototype for a general external function. */ +#if defined (__STDC__) || defined (WINDOWSNT) +#define P_(proto) proto +#else +#define P_(proto) () +#endif +@end example + +@node Conditional Compilation +@section Conditional Compilation + +When supporting configuration options already known when building your +program we prefer using @code{if (... )} over conditional compilation, +as in the former case the compiler is able to perform more extensive +checking of all possible code paths. + +For example, please write + +@smallexample + if (HAS_FOO) + ... + else + ... +@end smallexample + +@noindent +instead of: + +@smallexample + #ifdef HAS_FOO + ... + #else + ... + #endif +@end smallexample + +A modern compiler such as GCC will generate exactly the same code in +both cases, and we have been using similar techniques with good success +in several projects. Of course, the former method assumes that +@code{HAS_FOO} is defined as either 0 or 1. + +While this is not a silver bullet solving all portability problems, +and is not always appropriate, following this policy would have saved +GCC developers many hours, or even days, per year. + +In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in +GCC which cannot be simply used in @code{if( ...)} statements, there is +an easy workaround. Simply introduce another macro +@code{HAS_REVERSIBLE_CC_MODE} as in the following example: + +@smallexample + #ifdef REVERSIBLE_CC_MODE + #define HAS_REVERSIBLE_CC_MODE 1 + #else + #define HAS_REVERSIBLE_CC_MODE 0 + #endif +@end smallexample + +@node Program Behavior +@chapter Program Behavior for All Programs + +This @value{CHAPTER} describes conventions for writing robust +software. It also describes general standards for error messages, the +command line interface, and how libraries should behave. + +@menu +* Semantics:: Writing robust programs +* Libraries:: Library behavior +* Errors:: Formatting error messages +* User Interfaces:: Standards about interfaces generally +* Graphical Interfaces:: Standards for graphical interfaces +* Command-Line Interfaces:: Standards for command line interfaces +* Option Table:: Table of long options +* Memory Usage:: When and how to care about memory needs +* File Usage:: Which files to use, and where +@end menu + +@node Semantics +@section Writing Robust Programs + +@cindex arbitrary limits on data +Avoid arbitrary limits on the length or number of @emph{any} data +structure, including file names, lines, files, and symbols, by allocating +all data structures dynamically. In most Unix utilities, ``long lines +are silently truncated''. This is not acceptable in a GNU utility. + +@cindex @code{NUL} characters +Utilities reading files should not drop NUL characters, or any other +nonprinting characters @emph{including those with codes above 0177}. +The only sensible exceptions would be utilities specifically intended +for interface to certain types of terminals or printers +that can't handle those characters. +Whenever possible, try to make programs work properly with +sequences of bytes that represent multibyte characters, using encodings +such as UTF-8 and others. + +@cindex error messages +Check every system call for an error return, unless you know you wish to +ignore errors. Include the system error text (from @code{perror} or +equivalent) in @emph{every} error message resulting from a failing +system call, as well as the name of the file if any and the name of the +utility. Just ``cannot open foo.c'' or ``stat failed'' is not +sufficient. + +@cindex @code{malloc} return value +@cindex memory allocation failure +Check every call to @code{malloc} or @code{realloc} to see if it +returned zero. Check @code{realloc} even if you are making the block +smaller; in a system that rounds block sizes to a power of 2, +@code{realloc} may get a different block if you ask for less space. + +In Unix, @code{realloc} can destroy the storage block if it returns +zero. GNU @code{realloc} does not have this bug: if it fails, the +original block is unchanged. Feel free to assume the bug is fixed. If +you wish to run your program on Unix, and wish to avoid lossage in this +case, you can use the GNU @code{malloc}. + +You must expect @code{free} to alter the contents of the block that was +freed. Anything you want to fetch from the block, you must fetch before +calling @code{free}. + +If @code{malloc} fails in a noninteractive program, make that a fatal +error. In an interactive program (one that reads commands from the +user), it is better to abort the command and return to the command +reader loop. This allows the user to kill other processes to free up +virtual memory, and then try the command again. + +@cindex command-line arguments, decoding +Use @code{getopt_long} to decode arguments, unless the argument syntax +makes this unreasonable. + +When static storage is to be written in during program execution, use +explicit C code to initialize it. Reserve C initialized declarations +for data that will not be changed. +@c ADR: why? + +Try to avoid low-level interfaces to obscure Unix data structures (such +as file directories, utmp, or the layout of kernel memory), since these +are less likely to work compatibly. If you need to find all the files +in a directory, use @code{readdir} or some other high-level interface. +These are supported compatibly by GNU. + +@cindex signal handling +The preferred signal handling facilities are the BSD variant of +@code{signal}, and the @sc{posix} @code{sigaction} function; the +alternative USG @code{signal} interface is an inferior design. + +Nowadays, using the @sc{posix} signal functions may be the easiest way +to make a program portable. If you use @code{signal}, then on GNU/Linux +systems running GNU libc version 1, you should include +@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD +behavior. It is up to you whether to support systems where +@code{signal} has only the USG behavior, or give up on them. + +@cindex impossible conditions +In error checks that detect ``impossible'' conditions, just abort. +There is usually no point in printing any message. These checks +indicate the existence of bugs. Whoever wants to fix the bugs will have +to read the source code and run a debugger. So explain the problem with +comments in the source. The relevant data will be in variables, which +are easy to examine with the debugger, so there is no point moving them +elsewhere. + +Do not use a count of errors as the exit status for a program. +@emph{That does not work}, because exit status values are limited to 8 +bits (0 through 255). A single run of the program might have 256 +errors; if you try to return 256 as the exit status, the parent process +will see 0 as the status, and it will appear that the program succeeded. + +@cindex temporary files +@cindex @code{TMPDIR} environment variable +If you make temporary files, check the @code{TMPDIR} environment +variable; if that variable is defined, use the specified directory +instead of @file{/tmp}. + +In addition, be aware that there is a possible security problem when +creating temporary files in world-writable directories. In C, you can +avoid this problem by creating temporary files in this manner: + +@example +fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600); +@end example + +@noindent +or by using the @code{mkstemps} function from libiberty. + +In bash, use @code{set -C} to avoid this problem. + +@node Libraries +@section Library Behavior +@cindex libraries + +Try to make library functions reentrant. If they need to do dynamic +storage allocation, at least try to avoid any nonreentrancy aside from +that of @code{malloc} itself. + +Here are certain name conventions for libraries, to avoid name +conflicts. + +Choose a name prefix for the library, more than two characters long. +All external function and variable names should start with this +prefix. In addition, there should only be one of these in any given +library member. This usually means putting each one in a separate +source file. + +An exception can be made when two external symbols are always used +together, so that no reasonable program could use one without the +other; then they can both go in the same file. + +External symbols that are not documented entry points for the user +should have names beginning with @samp{_}. The @samp{_} should be +followed by the chosen name prefix for the library, to prevent +collisions with other libraries. These can go in the same files with +user entry points if you like. + +Static functions and variables can be used as you like and need not +fit any naming convention. + +@node Errors +@section Formatting Error Messages +@cindex formatting error messages +@cindex error messages, formatting + +Error messages from compilers should look like this: + +@example +@var{source-file-name}:@var{lineno}: @var{message} +@end example + +@noindent +If you want to mention the column number, use one of these formats: + +@example +@var{source-file-name}:@var{lineno}:@var{column}: @var{message} +@var{source-file-name}:@var{lineno}.@var{column}: @var{message} + +@end example + +@noindent +Line numbers should start from 1 at the beginning of the file, and +column numbers should start from 1 at the beginning of the line. (Both +of these conventions are chosen for compatibility.) Calculate column +numbers assuming that space and all ASCII printing characters have +equal width, and assuming tab stops every 8 columns. + +The error message can also give both the starting and ending positions +of the erroneous text. There are several formats so that you can +avoid redundant information such as a duplicate line number. +Here are the possible formats: + +@example +@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message} +@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message} +@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message} +@end example + +@noindent +When an error is spread over several files, you can use this format: + +@example +@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message} +@end example + +Error messages from other noninteractive programs should look like this: + +@example +@var{program}:@var{source-file-name}:@var{lineno}: @var{message} +@end example + +@noindent +when there is an appropriate source file, or like this: + +@example +@var{program}: @var{message} +@end example + +@noindent +when there is no relevant source file. + +If you want to mention the column number, use this format: + +@example +@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message} +@end example + +In an interactive program (one that is reading commands from a +terminal), it is better not to include the program name in an error +message. The place to indicate which program is running is in the +prompt or with the screen layout. (When the same program runs with +input from a source other than a terminal, it is not interactive and +would do best to print error messages using the noninteractive style.) + +The string @var{message} should not begin with a capital letter when +it follows a program name and/or file name, because that isn't the +beginning of a sentence. (The sentence conceptually starts at the +beginning of the line.) Also, it should not end with a period. + +Error messages from interactive programs, and other messages such as +usage messages, should start with a capital letter. But they should not +end with a period. + +@node User Interfaces +@section Standards for Interfaces Generally + +@cindex program name and its behavior +@cindex behavior, dependent on program's name +Please don't make the behavior of a utility depend on the name used +to invoke it. It is useful sometimes to make a link to a utility +with a different name, and that should not change what it does. + +Instead, use a run time option or a compilation switch or both +to select among the alternate behaviors. + +@cindex output device and program's behavior +Likewise, please don't make the behavior of the program depend on the +type of output device it is used with. Device independence is an +important principle of the system's design; do not compromise it merely +to save someone from typing an option now and then. (Variation in error +message syntax when using a terminal is ok, because that is a side issue +that people do not depend on.) + +If you think one behavior is most useful when the output is to a +terminal, and another is most useful when the output is a file or a +pipe, then it is usually best to make the default behavior the one that +is useful with output to a terminal, and have an option for the other +behavior. + +Compatibility requires certain programs to depend on the type of output +device. It would be disastrous if @code{ls} or @code{sh} did not do so +in the way all users expect. In some of these cases, we supplement the +program with a preferred alternate version that does not depend on the +output device type. For example, we provide a @code{dir} program much +like @code{ls} except that its default output format is always +multi-column format. + +@node Graphical Interfaces +@section Standards for Graphical Interfaces +@cindex graphical user interface + +@cindex gtk+ +When you write a program that provides a graphical user interface, +please make it work with X Windows and the GTK+ toolkit unless the +functionality specifically requires some alternative (for example, +``displaying jpeg images while in console mode''). + +In addition, please provide a command-line interface to control the +functionality. (In many cases, the graphical user interface can be a +separate program which invokes the command-line program.) This is +so that the same jobs can be done from scripts. + +@cindex corba +@cindex gnome +Please also consider providing a CORBA interface (for use from GNOME), a +library interface (for use from C), and perhaps a keyboard-driven +console interface (for use by users from console mode). Once you are +doing the work to provide the functionality and the graphical interface, +these won't be much extra work. + +@node Command-Line Interfaces +@section Standards for Command Line Interfaces +@cindex command-line interface + +@findex getopt +It is a good idea to follow the @sc{posix} guidelines for the +command-line options of a program. The easiest way to do this is to use +@code{getopt} to parse them. Note that the GNU version of @code{getopt} +will normally permit options anywhere among the arguments unless the +special argument @samp{--} is used. This is not what @sc{posix} +specifies; it is a GNU extension. + +@cindex long-named options +Please define long-named options that are equivalent to the +single-letter Unix-style options. We hope to make GNU more user +friendly this way. This is easy to do with the GNU function +@code{getopt_long}. + +One of the advantages of long-named options is that they can be +consistent from program to program. For example, users should be able +to expect the ``verbose'' option of any GNU program which has one, to be +spelled precisely @samp{--verbose}. To achieve this uniformity, look at +the table of common long-option names when you choose the option names +for your program (@pxref{Option Table}). + +It is usually a good idea for file names given as ordinary arguments to +be input files only; any output files would be specified using options +(preferably @samp{-o} or @samp{--output}). Even if you allow an output +file name as an ordinary argument for compatibility, try to provide an +option as another way to specify it. This will lead to more consistency +among GNU utilities, and fewer idiosyncracies for users to remember. + +@cindex standard command-line options +@cindex options, standard command-line +@cindex CGI programs, standard options for +@cindex PATH_INFO, specifying standard options as +All programs should support two standard options: @samp{--version} +and @samp{--help}. CGI programs should accept these as command-line +options, and also if given as the @env{PATH_INFO}; for instance, +visiting @url{http://example.org/p.cgi/--help} in a browser should +output the same information as inokving @samp{p.cgi --help} from the +command line. + +@table @code +@cindex @samp{--version} option +@item --version +This option should direct the program to print information about its name, +version, origin and legal status, all on standard output, and then exit +successfully. Other options and arguments should be ignored once this +is seen, and the program should not perform its normal function. + +@cindex canonical name of a program +@cindex program's canonical name +The first line is meant to be easy for a program to parse; the version +number proper starts after the last space. In addition, it contains +the canonical name for this program, in this format: + +@example +GNU Emacs 19.30 +@end example + +@noindent +The program's name should be a constant string; @emph{don't} compute it +from @code{argv[0]}. The idea is to state the standard or canonical +name for the program, not its file name. There are other ways to find +out the precise file name where a command is found in @code{PATH}. + +If the program is a subsidiary part of a larger package, mention the +package name in parentheses, like this: + +@example +emacsserver (GNU Emacs) 19.30 +@end example + +@noindent +If the package has a version number which is different from this +program's version number, you can mention the package version number +just before the close-parenthesis. + +If you @strong{need} to mention the version numbers of libraries which +are distributed separately from the package which contains this program, +you can do so by printing an additional line of version info for each +library you want to mention. Use the same format for these lines as for +the first line. + +Please do not mention all of the libraries that the program uses ``just +for completeness''---that would produce a lot of unhelpful clutter. +Please mention library version numbers only if you find in practice that +they are very important to you in debugging. + +The following line, after the version number line or lines, should be a +copyright notice. If more than one copyright notice is called for, put +each on a separate line. + +Next should follow a brief statement that the program is free software, +and that users are free to copy and change it on certain conditions. If +the program is covered by the GNU GPL, say so here. Also mention that +there is no warranty, to the extent permitted by law. + +It is ok to finish the output with a list of the major authors of the +program, as a way of giving credit. + +Here's an example of output that follows these rules: + +@smallexample +GNU Emacs 19.34.5 +Copyright (C) 1996 Free Software Foundation, Inc. +GNU Emacs comes with NO WARRANTY, +to the extent permitted by law. +You may redistribute copies of GNU Emacs +under the terms of the GNU General Public License. +For more information about these matters, +see the files named COPYING. +@end smallexample + +You should adapt this to your program, of course, filling in the proper +year, copyright holder, name of program, and the references to +distribution terms, and changing the rest of the wording as necessary. + +This copyright notice only needs to mention the most recent year in +which changes were made---there's no need to list the years for previous +versions' changes. You don't have to mention the name of the program in +these notices, if that is inconvenient, since it appeared in the first +line. + +Translations of the above lines must preserve the validity of the +copyright notices (@pxref{Internationalization}). If the translation's +character set supports it, the @samp{(C)} should be replaced with the +copyright symbol, as follows: + +@ifinfo +(the official copyright symbol, which is the letter C in a circle); +@end ifinfo +@ifnotinfo +@copyright{} +@end ifnotinfo + +Write the word ``Copyright'' exactly like that, in English. Do not +translate it into another language. International treaties recognize +the English word ``Copyright''; translations into other languages do not +have legal significance. + + +@cindex @samp{--help} option +@item --help +This option should output brief documentation for how to invoke the +program, on standard output, then exit successfully. Other options and +arguments should be ignored once this is seen, and the program should +not perform its normal function. + +@cindex address for bug reports +@cindex bug reports +Near the end of the @samp{--help} option's output there should be a line +that says where to mail bug reports. It should have this format: + +@example +Report bugs to @var{mailing-address}. +@end example +@end table + +@node Option Table +@section Table of Long Options +@cindex long option names +@cindex table of long options + +Here is a table of long options used by GNU programs. It is surely +incomplete, but we aim to list all the options that a new program might +want to be compatible with. If you use names not already in the table, +please send @email{bug-standards@@gnu.org} a list of them, with their +meanings, so we can update the table. + +@c Please leave newlines between items in this table; it's much easier +@c to update when it isn't completely squashed together and unreadable. +@c When there is more than one short option for a long option name, put +@c a semicolon between the lists of the programs that use them, not a +@c period. --friedman + +@table @samp +@item after-date +@samp{-N} in @code{tar}. + +@item all +@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, +and @code{unexpand}. + +@item all-text +@samp{-a} in @code{diff}. + +@item almost-all +@samp{-A} in @code{ls}. + +@item append +@samp{-a} in @code{etags}, @code{tee}, @code{time}; +@samp{-r} in @code{tar}. + +@item archive +@samp{-a} in @code{cp}. + +@item archive-name +@samp{-n} in @code{shar}. + +@item arglength +@samp{-l} in @code{m4}. + +@item ascii +@samp{-a} in @code{diff}. + +@item assign +@samp{-v} in @code{gawk}. + +@item assume-new +@samp{-W} in Make. + +@item assume-old +@samp{-o} in Make. + +@item auto-check +@samp{-a} in @code{recode}. + +@item auto-pager +@samp{-a} in @code{wdiff}. + +@item auto-reference +@samp{-A} in @code{ptx}. + +@item avoid-wraps +@samp{-n} in @code{wdiff}. + +@item background +For server programs, run in the background. + +@item backward-search +@samp{-B} in @code{ctags}. + +@item basename +@samp{-f} in @code{shar}. + +@item batch +Used in GDB. + +@item baud +Used in GDB. + +@item before +@samp{-b} in @code{tac}. + +@item binary +@samp{-b} in @code{cpio} and @code{diff}. + +@item bits-per-code +@samp{-b} in @code{shar}. + +@item block-size +Used in @code{cpio} and @code{tar}. + +@item blocks +@samp{-b} in @code{head} and @code{tail}. + +@item break-file +@samp{-b} in @code{ptx}. + +@item brief +Used in various programs to make output shorter. + +@item bytes +@samp{-c} in @code{head}, @code{split}, and @code{tail}. + +@item c@t{++} +@samp{-C} in @code{etags}. + +@item catenate +@samp{-A} in @code{tar}. + +@item cd +Used in various programs to specify the directory to use. + +@item changes +@samp{-c} in @code{chgrp} and @code{chown}. + +@item classify +@samp{-F} in @code{ls}. + +@item colons +@samp{-c} in @code{recode}. + +@item command +@samp{-c} in @code{su}; +@samp{-x} in GDB. + +@item compare +@samp{-d} in @code{tar}. + +@item compat +Used in @code{gawk}. + +@item compress +@samp{-Z} in @code{tar} and @code{shar}. + +@item concatenate +@samp{-A} in @code{tar}. + +@item confirmation +@samp{-w} in @code{tar}. + +@item context +Used in @code{diff}. + +@item copyleft +@samp{-W copyleft} in @code{gawk}. + +@item copyright +@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}; +@samp{-W copyright} in @code{gawk}. + +@item core +Used in GDB. + +@item count +@samp{-q} in @code{who}. + +@item count-links +@samp{-l} in @code{du}. + +@item create +Used in @code{tar} and @code{cpio}. + +@item cut-mark +@samp{-c} in @code{shar}. + +@item cxref +@samp{-x} in @code{ctags}. + +@item date +@samp{-d} in @code{touch}. + +@item debug +@samp{-d} in Make and @code{m4}; +@samp{-t} in Bison. + +@item define +@samp{-D} in @code{m4}. + +@item defines +@samp{-d} in Bison and @code{ctags}. + +@item delete +@samp{-D} in @code{tar}. + +@item dereference +@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, +@code{ls}, and @code{tar}. + +@item dereference-args +@samp{-D} in @code{du}. + +@item device +Specify an I/O device (special file name). + +@item diacritics +@samp{-d} in @code{recode}. + +@item dictionary-order +@samp{-d} in @code{look}. + +@item diff +@samp{-d} in @code{tar}. + +@item digits +@samp{-n} in @code{csplit}. + +@item directory +Specify the directory to use, in various programs. In @code{ls}, it +means to show directories themselves rather than their contents. In +@code{rm} and @code{ln}, it means to not treat links to directories +specially. + +@item discard-all +@samp{-x} in @code{strip}. + +@item discard-locals +@samp{-X} in @code{strip}. + +@item dry-run +@samp{-n} in Make. + +@item ed +@samp{-e} in @code{diff}. + +@item elide-empty-files +@samp{-z} in @code{csplit}. + +@item end-delete +@samp{-x} in @code{wdiff}. + +@item end-insert +@samp{-z} in @code{wdiff}. + +@item entire-new-file +@samp{-N} in @code{diff}. + +@item environment-overrides +@samp{-e} in Make. + +@item eof +@samp{-e} in @code{xargs}. + +@item epoch +Used in GDB. + +@item error-limit +Used in @code{makeinfo}. + +@item error-output +@samp{-o} in @code{m4}. + +@item escape +@samp{-b} in @code{ls}. + +@item exclude-from +@samp{-X} in @code{tar}. + +@item exec +Used in GDB. + +@item exit +@samp{-x} in @code{xargs}. + +@item exit-0 +@samp{-e} in @code{unshar}. + +@item expand-tabs +@samp{-t} in @code{diff}. + +@item expression +@samp{-e} in @code{sed}. + +@item extern-only +@samp{-g} in @code{nm}. + +@item extract +@samp{-i} in @code{cpio}; +@samp{-x} in @code{tar}. + +@item faces +@samp{-f} in @code{finger}. + +@item fast +@samp{-f} in @code{su}. + +@item fatal-warnings +@samp{-E} in @code{m4}. + +@item file +@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar}; +@samp{-n} in @code{sed}; +@samp{-r} in @code{touch}. + +@item field-separator +@samp{-F} in @code{gawk}. + +@item file-prefix +@samp{-b} in Bison. + +@item file-type +@samp{-F} in @code{ls}. + +@item files-from +@samp{-T} in @code{tar}. + +@item fill-column +Used in @code{makeinfo}. + +@item flag-truncation +@samp{-F} in @code{ptx}. + +@item fixed-output-files +@samp{-y} in Bison. + +@item follow +@samp{-f} in @code{tail}. + +@item footnote-style +Used in @code{makeinfo}. + +@item force +@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. + +@item force-prefix +@samp{-F} in @code{shar}. + +@item foreground +For server programs, run in the foreground; +in other words, don't do anything special to run the server +in the background. + +@item format +Used in @code{ls}, @code{time}, and @code{ptx}. + +@item freeze-state +@samp{-F} in @code{m4}. + +@item fullname +Used in GDB. + +@item gap-size +@samp{-g} in @code{ptx}. + +@item get +@samp{-x} in @code{tar}. + +@item graphic +@samp{-i} in @code{ul}. + +@item graphics +@samp{-g} in @code{recode}. + +@item group +@samp{-g} in @code{install}. + +@item gzip +@samp{-z} in @code{tar} and @code{shar}. + +@item hashsize +@samp{-H} in @code{m4}. + +@item header +@samp{-h} in @code{objdump} and @code{recode} + +@item heading +@samp{-H} in @code{who}. + +@item help +Used to ask for brief usage information. + +@item here-delimiter +@samp{-d} in @code{shar}. + +@item hide-control-chars +@samp{-q} in @code{ls}. + +@item html +In @code{makeinfo}, output HTML. + +@item idle +@samp{-u} in @code{who}. + +@item ifdef +@samp{-D} in @code{diff}. + +@item ignore +@samp{-I} in @code{ls}; +@samp{-x} in @code{recode}. + +@item ignore-all-space +@samp{-w} in @code{diff}. + +@item ignore-backups +@samp{-B} in @code{ls}. + +@item ignore-blank-lines +@samp{-B} in @code{diff}. + +@item ignore-case +@samp{-f} in @code{look} and @code{ptx}; +@samp{-i} in @code{diff} and @code{wdiff}. + +@item ignore-errors +@samp{-i} in Make. + +@item ignore-file +@samp{-i} in @code{ptx}. + +@item ignore-indentation +@samp{-I} in @code{etags}. + +@item ignore-init-file +@samp{-f} in Oleo. + +@item ignore-interrupts +@samp{-i} in @code{tee}. + +@item ignore-matching-lines +@samp{-I} in @code{diff}. + +@item ignore-space-change +@samp{-b} in @code{diff}. + +@item ignore-zeros +@samp{-i} in @code{tar}. + +@item include +@samp{-i} in @code{etags}; +@samp{-I} in @code{m4}. + +@item include-dir +@samp{-I} in Make. + +@item incremental +@samp{-G} in @code{tar}. + +@item info +@samp{-i}, @samp{-l}, and @samp{-m} in Finger. + +@item init-file +In some programs, specify the name of the file to read as the user's +init file. + +@item initial +@samp{-i} in @code{expand}. + +@item initial-tab +@samp{-T} in @code{diff}. + +@item inode +@samp{-i} in @code{ls}. + +@item interactive +@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; +@samp{-e} in @code{m4}; +@samp{-p} in @code{xargs}; +@samp{-w} in @code{tar}. + +@item intermix-type +@samp{-p} in @code{shar}. + +@item iso-8601 +Used in @code{date} + +@item jobs +@samp{-j} in Make. + +@item just-print +@samp{-n} in Make. + +@item keep-going +@samp{-k} in Make. + +@item keep-files +@samp{-k} in @code{csplit}. + +@item kilobytes +@samp{-k} in @code{du} and @code{ls}. + +@item language +@samp{-l} in @code{etags}. + +@item less-mode +@samp{-l} in @code{wdiff}. + +@item level-for-gzip +@samp{-g} in @code{shar}. + +@item line-bytes +@samp{-C} in @code{split}. + +@item lines +Used in @code{split}, @code{head}, and @code{tail}. + +@item link +@samp{-l} in @code{cpio}. + +@item lint +@itemx lint-old +Used in @code{gawk}. + +@item list +@samp{-t} in @code{cpio}; +@samp{-l} in @code{recode}. + +@item list +@samp{-t} in @code{tar}. + +@item literal +@samp{-N} in @code{ls}. + +@item load-average +@samp{-l} in Make. + +@item login +Used in @code{su}. + +@item machine +No listing of which programs already use this; +someone should check to +see if any actually do, and tell @email{gnu@@gnu.org}. + +@item macro-name +@samp{-M} in @code{ptx}. + +@item mail +@samp{-m} in @code{hello} and @code{uname}. + +@item make-directories +@samp{-d} in @code{cpio}. + +@item makefile +@samp{-f} in Make. + +@item mapped +Used in GDB. + +@item max-args +@samp{-n} in @code{xargs}. + +@item max-chars +@samp{-n} in @code{xargs}. + +@item max-lines +@samp{-l} in @code{xargs}. + +@item max-load +@samp{-l} in Make. + +@item max-procs +@samp{-P} in @code{xargs}. + +@item mesg +@samp{-T} in @code{who}. + +@item message +@samp{-T} in @code{who}. + +@item minimal +@samp{-d} in @code{diff}. + +@item mixed-uuencode +@samp{-M} in @code{shar}. + +@item mode +@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. + +@item modification-time +@samp{-m} in @code{tar}. + +@item multi-volume +@samp{-M} in @code{tar}. + +@item name-prefix +@samp{-a} in Bison. + +@item nesting-limit +@samp{-L} in @code{m4}. + +@item net-headers +@samp{-a} in @code{shar}. + +@item new-file +@samp{-W} in Make. + +@item no-builtin-rules +@samp{-r} in Make. + +@item no-character-count +@samp{-w} in @code{shar}. + +@item no-check-existing +@samp{-x} in @code{shar}. + +@item no-common +@samp{-3} in @code{wdiff}. + +@item no-create +@samp{-c} in @code{touch}. + +@item no-defines +@samp{-D} in @code{etags}. + +@item no-deleted +@samp{-1} in @code{wdiff}. + +@item no-dereference +@samp{-d} in @code{cp}. + +@item no-inserted +@samp{-2} in @code{wdiff}. + +@item no-keep-going +@samp{-S} in Make. + +@item no-lines +@samp{-l} in Bison. + +@item no-piping +@samp{-P} in @code{shar}. + +@item no-prof +@samp{-e} in @code{gprof}. + +@item no-regex +@samp{-R} in @code{etags}. + +@item no-sort +@samp{-p} in @code{nm}. + +@item no-splash +Don't print a startup splash screen. + +@item no-split +Used in @code{makeinfo}. + +@item no-static +@samp{-a} in @code{gprof}. + +@item no-time +@samp{-E} in @code{gprof}. + +@item no-timestamp +@samp{-m} in @code{shar}. + +@item no-validate +Used in @code{makeinfo}. + +@item no-wait +Used in @code{emacsclient}. + +@item no-warn +Used in various programs to inhibit warnings. + +@item node +@samp{-n} in @code{info}. + +@item nodename +@samp{-n} in @code{uname}. + +@item nonmatching +@samp{-f} in @code{cpio}. + +@item nstuff +@samp{-n} in @code{objdump}. + +@item null +@samp{-0} in @code{xargs}. + +@item number +@samp{-n} in @code{cat}. + +@item number-nonblank +@samp{-b} in @code{cat}. + +@item numeric-sort +@samp{-n} in @code{nm}. + +@item numeric-uid-gid +@samp{-n} in @code{cpio} and @code{ls}. + +@item nx +Used in GDB. + +@item old-archive +@samp{-o} in @code{tar}. + +@item old-file +@samp{-o} in Make. + +@item one-file-system +@samp{-l} in @code{tar}, @code{cp}, and @code{du}. + +@item only-file +@samp{-o} in @code{ptx}. + +@item only-prof +@samp{-f} in @code{gprof}. + +@item only-time +@samp{-F} in @code{gprof}. + +@item options +@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount}, +@code{fdmountd}, and @code{fdumount}. + +@item output +In various programs, specify the output file name. + +@item output-prefix +@samp{-o} in @code{shar}. + +@item override +@samp{-o} in @code{rm}. + +@item overwrite +@samp{-c} in @code{unshar}. + +@item owner +@samp{-o} in @code{install}. + +@item paginate +@samp{-l} in @code{diff}. + +@item paragraph-indent +Used in @code{makeinfo}. + +@item parents +@samp{-p} in @code{mkdir} and @code{rmdir}. + +@item pass-all +@samp{-p} in @code{ul}. + +@item pass-through +@samp{-p} in @code{cpio}. + +@item port +@samp{-P} in @code{finger}. + +@item portability +@samp{-c} in @code{cpio} and @code{tar}. + +@item posix +Used in @code{gawk}. + +@item prefix-builtins +@samp{-P} in @code{m4}. + +@item prefix +@samp{-f} in @code{csplit}. + +@item preserve +Used in @code{tar} and @code{cp}. + +@item preserve-environment +@samp{-p} in @code{su}. + +@item preserve-modification-time +@samp{-m} in @code{cpio}. + +@item preserve-order +@samp{-s} in @code{tar}. + +@item preserve-permissions +@samp{-p} in @code{tar}. + +@item print +@samp{-l} in @code{diff}. + +@item print-chars +@samp{-L} in @code{cmp}. + +@item print-data-base +@samp{-p} in Make. + +@item print-directory +@samp{-w} in Make. + +@item print-file-name +@samp{-o} in @code{nm}. + +@item print-symdefs +@samp{-s} in @code{nm}. + +@item printer +@samp{-p} in @code{wdiff}. + +@item prompt +@samp{-p} in @code{ed}. + +@item proxy +Specify an HTTP proxy. + +@item query-user +@samp{-X} in @code{shar}. + +@item question +@samp{-q} in Make. + +@item quiet +Used in many programs to inhibit the usual output. Every +program accepting @samp{--quiet} should accept @samp{--silent} as a +synonym. + +@item quiet-unshar +@samp{-Q} in @code{shar} + +@item quote-name +@samp{-Q} in @code{ls}. + +@item rcs +@samp{-n} in @code{diff}. + +@item re-interval +Used in @code{gawk}. + +@item read-full-blocks +@samp{-B} in @code{tar}. + +@item readnow +Used in GDB. + +@item recon +@samp{-n} in Make. + +@item record-number +@samp{-R} in @code{tar}. + +@item recursive +Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, +and @code{rm}. + +@item reference-limit +Used in @code{makeinfo}. + +@item references +@samp{-r} in @code{ptx}. + +@item regex +@samp{-r} in @code{tac} and @code{etags}. + +@item release +@samp{-r} in @code{uname}. + +@item reload-state +@samp{-R} in @code{m4}. + +@item relocation +@samp{-r} in @code{objdump}. + +@item rename +@samp{-r} in @code{cpio}. + +@item replace +@samp{-i} in @code{xargs}. + +@item report-identical-files +@samp{-s} in @code{diff}. + +@item reset-access-time +@samp{-a} in @code{cpio}. + +@item reverse +@samp{-r} in @code{ls} and @code{nm}. + +@item reversed-ed +@samp{-f} in @code{diff}. + +@item right-side-defs +@samp{-R} in @code{ptx}. + +@item same-order +@samp{-s} in @code{tar}. + +@item same-permissions +@samp{-p} in @code{tar}. + +@item save +@samp{-g} in @code{stty}. + +@item se +Used in GDB. + +@item sentence-regexp +@samp{-S} in @code{ptx}. + +@item separate-dirs +@samp{-S} in @code{du}. + +@item separator +@samp{-s} in @code{tac}. + +@item sequence +Used by @code{recode} to chose files or pipes for sequencing passes. + +@item shell +@samp{-s} in @code{su}. + +@item show-all +@samp{-A} in @code{cat}. + +@item show-c-function +@samp{-p} in @code{diff}. + +@item show-ends +@samp{-E} in @code{cat}. + +@item show-function-line +@samp{-F} in @code{diff}. + +@item show-tabs +@samp{-T} in @code{cat}. + +@item silent +Used in many programs to inhibit the usual output. +Every program accepting +@samp{--silent} should accept @samp{--quiet} as a synonym. + +@item size +@samp{-s} in @code{ls}. + +@item socket +Specify a file descriptor for a network server to use for its socket, +instead of opening and binding a new socket. This provides a way to +run, in a nonpriveledged process, a server that normally needs a +reserved port number. + +@item sort +Used in @code{ls}. + +@item source +@samp{-W source} in @code{gawk}. + +@item sparse +@samp{-S} in @code{tar}. + +@item speed-large-files +@samp{-H} in @code{diff}. + +@item split-at +@samp{-E} in @code{unshar}. + +@item split-size-limit +@samp{-L} in @code{shar}. + +@item squeeze-blank +@samp{-s} in @code{cat}. + +@item start-delete +@samp{-w} in @code{wdiff}. + +@item start-insert +@samp{-y} in @code{wdiff}. + +@item starting-file +Used in @code{tar} and @code{diff} to specify which file within +a directory to start processing with. + +@item statistics +@samp{-s} in @code{wdiff}. + +@item stdin-file-list +@samp{-S} in @code{shar}. + +@item stop +@samp{-S} in Make. + +@item strict +@samp{-s} in @code{recode}. + +@item strip +@samp{-s} in @code{install}. + +@item strip-all +@samp{-s} in @code{strip}. + +@item strip-debug +@samp{-S} in @code{strip}. + +@item submitter +@samp{-s} in @code{shar}. + +@item suffix +@samp{-S} in @code{cp}, @code{ln}, @code{mv}. + +@item suffix-format +@samp{-b} in @code{csplit}. + +@item sum +@samp{-s} in @code{gprof}. + +@item summarize +@samp{-s} in @code{du}. + +@item symbolic +@samp{-s} in @code{ln}. + +@item symbols +Used in GDB and @code{objdump}. + +@item synclines +@samp{-s} in @code{m4}. + +@item sysname +@samp{-s} in @code{uname}. + +@item tabs +@samp{-t} in @code{expand} and @code{unexpand}. + +@item tabsize +@samp{-T} in @code{ls}. + +@item terminal +@samp{-T} in @code{tput} and @code{ul}. +@samp{-t} in @code{wdiff}. + +@item text +@samp{-a} in @code{diff}. + +@item text-files +@samp{-T} in @code{shar}. + +@item time +Used in @code{ls} and @code{touch}. + +@item timeout +Specify how long to wait before giving up on some operation. + +@item to-stdout +@samp{-O} in @code{tar}. + +@item total +@samp{-c} in @code{du}. + +@item touch +@samp{-t} in Make, @code{ranlib}, and @code{recode}. + +@item trace +@samp{-t} in @code{m4}. + +@item traditional +@samp{-t} in @code{hello}; +@samp{-W traditional} in @code{gawk}; +@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. + +@item tty +Used in GDB. + +@item typedefs +@samp{-t} in @code{ctags}. + +@item typedefs-and-c++ +@samp{-T} in @code{ctags}. + +@item typeset-mode +@samp{-t} in @code{ptx}. + +@item uncompress +@samp{-z} in @code{tar}. + +@item unconditional +@samp{-u} in @code{cpio}. + +@item undefine +@samp{-U} in @code{m4}. + +@item undefined-only +@samp{-u} in @code{nm}. + +@item update +@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. + +@item usage +Used in @code{gawk}; same as @samp{--help}. + +@item uuencode +@samp{-B} in @code{shar}. + +@item vanilla-operation +@samp{-V} in @code{shar}. + +@item verbose +Print more information about progress. Many programs support this. + +@item verify +@samp{-W} in @code{tar}. + +@item version +Print the version number. + +@item version-control +@samp{-V} in @code{cp}, @code{ln}, @code{mv}. + +@item vgrind +@samp{-v} in @code{ctags}. + +@item volume +@samp{-V} in @code{tar}. + +@item what-if +@samp{-W} in Make. + +@item whole-size-limit +@samp{-l} in @code{shar}. + +@item width +@samp{-w} in @code{ls} and @code{ptx}. + +@item word-regexp +@samp{-W} in @code{ptx}. + +@item writable +@samp{-T} in @code{who}. + +@item zeros +@samp{-z} in @code{gprof}. +@end table + +@node Memory Usage +@section Memory Usage +@cindex memory usage + +If a program typically uses just a few meg of memory, don't bother making any +effort to reduce memory usage. For example, if it is impractical for +other reasons to operate on files more than a few meg long, it is +reasonable to read entire input files into core to operate on them. + +However, for programs such as @code{cat} or @code{tail}, that can +usefully operate on very large files, it is important to avoid using a +technique that would artificially limit the size of files it can handle. +If a program works by lines and could be applied to arbitrary +user-supplied input files, it should keep only a line in memory, because +this is not very hard and users will want to be able to operate on input +files that are bigger than will fit in core all at once. + +If your program creates complicated data structures, just make them in +core and give a fatal error if @code{malloc} returns zero. + +@node File Usage +@section File Usage +@cindex file usage + +Programs should be prepared to operate when @file{/usr} and @file{/etc} +are read-only file systems. Thus, if the program manages log files, +lock files, backup files, score files, or any other files which are +modified for internal purposes, these files should not be stored in +@file{/usr} or @file{/etc}. + +There are two exceptions. @file{/etc} is used to store system +configuration information; it is reasonable for a program to modify +files in @file{/etc} when its job is to update the system configuration. +Also, if the user explicitly asks to modify one file in a directory, it +is reasonable for the program to store other files in the same +directory. + +@node Writing C +@chapter Making The Best Use of C + +This @value{CHAPTER} provides advice on how best to use the C language +when writing GNU software. + +@menu +* Formatting:: Formatting Your Source Code +* Comments:: Commenting Your Work +* Syntactic Conventions:: Clean Use of C Constructs +* Names:: Naming Variables, Functions, and Files +* System Portability:: Portability between different operating systems +* CPU Portability:: Supporting the range of CPU types +* System Functions:: Portability and ``standard'' library functions +* Internationalization:: Techniques for internationalization +* Mmap:: How you can safely use @code{mmap}. +@end menu + +@node Formatting +@section Formatting Your Source Code +@cindex formatting source code + +@cindex open brace +@cindex braces, in C source +It is important to put the open-brace that starts the body of a C +function in column zero, and avoid putting any other open-brace or +open-parenthesis or open-bracket in column zero. Several tools look +for open-braces in column zero to find the beginnings of C functions. +These tools will not work on code not formatted that way. + +It is also important for function definitions to start the name of the +function in column zero. This helps people to search for function +definitions, and may also help certain tools recognize them. Thus, +the proper format is this: + +@example +static char * +concat (s1, s2) /* Name starts in column zero here */ + char *s1, *s2; +@{ /* Open brace in column zero here */ + @dots{} +@} +@end example + +@noindent +or, if you want to use Standard C syntax, format the definition like +this: + +@example +static char * +concat (char *s1, char *s2) +@{ + @dots{} +@} +@end example + +In Standard C, if the arguments don't fit nicely on one line, +split it like this: + +@example +int +lots_of_args (int an_integer, long a_long, short a_short, + double a_double, float a_float) +@dots{} +@end example + +The rest of this section gives our recommendations for other aspects of +C formatting style, which is also the default style of the @code{indent} +program in version 1.2 and newer. It corresponds to the options + +@smallexample +-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 +-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob +@end smallexample + +We don't think of these recommendations as requirements, because it +causes no problems for users if two different programs have different +formatting styles. + +But whatever style you use, please use it consistently, since a mixture +of styles within one program tends to look ugly. If you are +contributing changes to an existing program, please follow the style of +that program. + +For the body of the function, our recommended style looks like this: + +@example +if (x < foo (y, z)) + haha = bar[4] + 5; +else + @{ + while (z) + @{ + haha += foo (z, z); + z--; + @} + return ++x + bar (); + @} +@end example + +@cindex spaces before open-paren +We find it easier to read a program when it has spaces before the +open-parentheses and after the commas. Especially after the commas. + +When you split an expression into multiple lines, split it +before an operator, not after one. Here is the right way: + +@cindex expressions, splitting +@example +if (foo_this_is_long && bar > win (x, y, z) + && remaining_condition) +@end example + +Try to avoid having two operators of different precedence at the same +level of indentation. For example, don't write this: + +@example +mode = (inmode[j] == VOIDmode + || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) + ? outmode[j] : inmode[j]); +@end example + +Instead, use extra parentheses so that the indentation shows the nesting: + +@example +mode = ((inmode[j] == VOIDmode + || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) + ? outmode[j] : inmode[j]); +@end example + +Insert extra parentheses so that Emacs will indent the code properly. +For example, the following indentation looks nice if you do it by hand, + +@example +v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; +@end example + +@noindent +but Emacs would alter it. Adding a set of parentheses produces +something that looks equally nice, and which Emacs will preserve: + +@example +v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 + + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); +@end example + +Format do-while statements like this: + +@example +do + @{ + a = foo (a); + @} +while (a > 0); +@end example + +@cindex formfeed +@cindex control-L +Please use formfeed characters (control-L) to divide the program into +pages at logical places (but not within a function). It does not matter +just how long the pages are, since they do not have to fit on a printed +page. The formfeeds should appear alone on lines by themselves. + +@node Comments +@section Commenting Your Work +@cindex commenting + +Every program should start with a comment saying briefly what it is for. +Example: @samp{fmt - filter for simple filling of text}. + +Please write the comments in a GNU program in English, because English +is the one language that nearly all programmers in all countries can +read. If you do not write English well, please write comments in +English as well as you can, then ask other people to help rewrite them. +If you can't write comments in English, please find someone to work with +you and translate your comments into English. + +Please put a comment on each function saying what the function does, +what sorts of arguments it gets, and what the possible values of +arguments mean and are used for. It is not necessary to duplicate in +words the meaning of the C argument declarations, if a C type is being +used in its customary fashion. If there is anything nonstandard about +its use (such as an argument of type @code{char *} which is really the +address of the second character of a string, not the first), or any +possible values that would not work the way one would expect (such as, +that strings containing newlines are not guaranteed to work), be sure +to say so. + +Also explain the significance of the return value, if there is one. + +Please put two spaces after the end of a sentence in your comments, so +that the Emacs sentence commands will work. Also, please write +complete sentences and capitalize the first word. If a lower-case +identifier comes at the beginning of a sentence, don't capitalize it! +Changing the spelling makes it a different identifier. If you don't +like starting a sentence with a lower case letter, write the sentence +differently (e.g., ``The identifier lower-case is @dots{}''). + +The comment on a function is much clearer if you use the argument +names to speak about the argument values. The variable name itself +should be lower case, but write it in upper case when you are speaking +about the value rather than the variable itself. Thus, ``the inode +number NODE_NUM'' rather than ``an inode''. + +There is usually no purpose in restating the name of the function in +the comment before it, because the reader can see that for himself. +There might be an exception when the comment is so long that the function +itself would be off the bottom of the screen. + +There should be a comment on each static variable as well, like this: + +@example +/* Nonzero means truncate lines in the display; + zero means continue them. */ +int truncate_lines; +@end example + +@cindex conditionals, comments for +@cindex @code{#endif}, commenting +Every @samp{#endif} should have a comment, except in the case of short +conditionals (just a few lines) that are not nested. The comment should +state the condition of the conditional that is ending, @emph{including +its sense}. @samp{#else} should have a comment describing the condition +@emph{and sense} of the code that follows. For example: + +@example +@group +#ifdef foo + @dots{} +#else /* not foo */ + @dots{} +#endif /* not foo */ +@end group +@group +#ifdef foo + @dots{} +#endif /* foo */ +@end group +@end example + +@noindent +but, by contrast, write the comments this way for a @samp{#ifndef}: + +@example +@group +#ifndef foo + @dots{} +#else /* foo */ + @dots{} +#endif /* foo */ +@end group +@group +#ifndef foo + @dots{} +#endif /* not foo */ +@end group +@end example + +@node Syntactic Conventions +@section Clean Use of C Constructs +@cindex syntactic conventions + +@cindex implicit @code{int} +@cindex function argument, declaring +Please explicitly declare the types of all objects. For example, you +should explicitly declare all arguments to functions, and you should +declare functions to return @code{int} rather than omitting the +@code{int}. + +@cindex compiler warnings +@cindex @samp{-Wall} compiler option +Some programmers like to use the GCC @samp{-Wall} option, and change the +code whenever it issues a warning. If you want to do this, then do. +Other programmers prefer not to use @samp{-Wall}, because it gives +warnings for valid and legitimate code which they do not want to change. +If you want to do this, then do. The compiler should be your servant, +not your master. + +Declarations of external functions and functions to appear later in the +source file should all go in one place near the beginning of the file +(somewhere before the first function definition in the file), or else +should go in a header file. Don't put @code{extern} declarations inside +functions. + +@cindex temporary variables +It used to be common practice to use the same local variables (with +names like @code{tem}) over and over for different values within one +function. Instead of doing this, it is better to declare a separate local +variable for each distinct purpose, and give it a name which is +meaningful. This not only makes programs easier to understand, it also +facilitates optimization by good compilers. You can also move the +declaration of each local variable into the smallest scope that includes +all its uses. This makes the program even cleaner. + +Don't use local variables or parameters that shadow global identifiers. + +@cindex multiple variables in a line +Don't declare multiple variables in one declaration that spans lines. +Start a new declaration on each line, instead. For example, instead +of this: + +@example +@group +int foo, + bar; +@end group +@end example + +@noindent +write either this: + +@example +int foo, bar; +@end example + +@noindent +or this: + +@example +int foo; +int bar; +@end example + +@noindent +(If they are global variables, each should have a comment preceding it +anyway.) + +When you have an @code{if}-@code{else} statement nested in another +@code{if} statement, always put braces around the @code{if}-@code{else}. +Thus, never write like this: + +@example +if (foo) + if (bar) + win (); + else + lose (); +@end example + +@noindent +always like this: + +@example +if (foo) + @{ + if (bar) + win (); + else + lose (); + @} +@end example + +If you have an @code{if} statement nested inside of an @code{else} +statement, either write @code{else if} on one line, like this, + +@example +if (foo) + @dots{} +else if (bar) + @dots{} +@end example + +@noindent +with its @code{then}-part indented like the preceding @code{then}-part, +or write the nested @code{if} within braces like this: + +@example +if (foo) + @dots{} +else + @{ + if (bar) + @dots{} + @} +@end example + +Don't declare both a structure tag and variables or typedefs in the +same declaration. Instead, declare the structure tag separately +and then use it to declare the variables or typedefs. + +Try to avoid assignments inside @code{if}-conditions. For example, +don't write this: + +@example +if ((foo = (char *) malloc (sizeof *foo)) == 0) + fatal ("virtual memory exhausted"); +@end example + +@noindent +instead, write this: + +@example +foo = (char *) malloc (sizeof *foo); +if (foo == 0) + fatal ("virtual memory exhausted"); +@end example + +@pindex lint +Don't make the program ugly to placate @code{lint}. Please don't insert any +casts to @code{void}. Zero without a cast is perfectly fine as a null +pointer constant, except when calling a varargs function. + +@node Names +@section Naming Variables, Functions, and Files + +@cindex names of variables, functions, and files +The names of global variables and functions in a program serve as +comments of a sort. So don't choose terse names---instead, look for +names that give useful information about the meaning of the variable or +function. In a GNU program, names should be English, like other +comments. + +Local variable names can be shorter, because they are used only within +one context, where (presumably) comments explain their purpose. + +Try to limit your use of abbreviations in symbol names. It is ok to +make a few abbreviations, explain what they mean, and then use them +frequently, but don't use lots of obscure abbreviations. + +Please use underscores to separate words in a name, so that the Emacs +word commands can be useful within them. Stick to lower case; reserve +upper case for macros and @code{enum} constants, and for name-prefixes +that follow a uniform convention. + +For example, you should use names like @code{ignore_space_change_flag}; +don't use names like @code{iCantReadThis}. + +Variables that indicate whether command-line options have been +specified should be named after the meaning of the option, not after +the option-letter. A comment should state both the exact meaning of +the option and its letter. For example, + +@example +@group +/* Ignore changes in horizontal whitespace (-b). */ +int ignore_space_change_flag; +@end group +@end example + +When you want to define names with constant integer values, use +@code{enum} rather than @samp{#define}. GDB knows about enumeration +constants. + +@cindex file-name limitations +@pindex doschk +You might want to make sure that none of the file names would conflict +the files were loaded onto an MS-DOS file system which shortens the +names. You can use the program @code{doschk} to test for this. + +Some GNU programs were designed to limit themselves to file names of 14 +characters or less, to avoid file name conflicts if they are read into +older System V systems. Please preserve this feature in the existing +GNU programs that have it, but there is no need to do this in new GNU +programs. @code{doschk} also reports file names longer than 14 +characters. + +@node System Portability +@section Portability between System Types +@cindex portability, between system types + +In the Unix world, ``portability'' refers to porting to different Unix +versions. For a GNU program, this kind of portability is desirable, but +not paramount. + +The primary purpose of GNU software is to run on top of the GNU kernel, +compiled with the GNU C compiler, on various types of @sc{cpu}. So the +kinds of portability that are absolutely necessary are quite limited. +But it is important to support Linux-based GNU systems, since they +are the form of GNU that is popular. + +Beyond that, it is good to support the other free operating systems +(*BSD), and it is nice to support other Unix-like systems if you want +to. Supporting a variety of Unix-like systems is desirable, although +not paramount. It is usually not too hard, so you may as well do it. +But you don't have to consider it an obligation, if it does turn out to +be hard. + +@pindex autoconf +The easiest way to achieve portability to most Unix-like systems is to +use Autoconf. It's unlikely that your program needs to know more +information about the host platform than Autoconf can provide, simply +because most of the programs that need such knowledge have already been +written. + +Avoid using the format of semi-internal data bases (e.g., directories) +when there is a higher-level alternative (@code{readdir}). + +@cindex non-@sc{posix} systems, and portability +As for systems that are not like Unix, such as MSDOS, Windows, the +Macintosh, VMS, and MVS, supporting them is often a lot of work. When +that is the case, it is better to spend your time adding features that +will be useful on GNU and GNU/Linux, rather than on supporting other +incompatible systems. + +If you do support Windows, please do not abbreviate it as ``win''. In +hacker terminology, calling something a ``win'' is a form of praise. +You're free to praise Microsoft Windows on your own if you want, but +please don't do this in GNU packages. Instead of abbreviating +``Windows'' to ``un'', you can write it in full or abbreviate it to +``woe'' or ``w''. In GNU Emacs, for instance, we use @samp{w32} in +file names of Windows-specific files, but the macro for Windows +conditionals is called @code{WINDOWSNT}. + +It is a good idea to define the ``feature test macro'' +@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU +or GNU/Linux, this will enable the declarations of GNU library extension +functions, and that will usually give you a compiler error message if +you define the same function names in some other way in your program. +(You don't have to actually @emph{use} these functions, if you prefer +to make the program more portable to other systems.) + +But whether or not you use these GNU extensions, you should avoid +using their names for any other meanings. Doing so would make it hard +to move your code into other GNU programs. + +@node CPU Portability +@section Portability between @sc{cpu}s + +@cindex data types, and portability +@cindex portability, and data types +Even GNU systems will differ because of differences among @sc{cpu} +types---for example, difference in byte ordering and alignment +requirements. It is absolutely essential to handle these differences. +However, don't make any effort to cater to the possibility that an +@code{int} will be less than 32 bits. We don't support 16-bit machines +in GNU. + +Similarly, don't make any effort to cater to the possibility that +@code{long} will be smaller than predefined types like @code{size_t}. +For example, the following code is ok: + +@example +printf ("size = %lu\n", (unsigned long) sizeof array); +printf ("diff = %ld\n", (long) (pointer2 - pointer1)); +@end example + +1989 Standard C requires this to work, and we know of only one +counterexample: 64-bit programs on Microsoft Windows IA-64. We will +leave it to those who want to port GNU programs to that environment +to figure out how to do it. + +Predefined file-size types like @code{off_t} are an exception: they are +longer than @code{long} on many platforms, so code like the above won't +work with them. One way to print an @code{off_t} value portably is to +print its digits yourself, one by one. + +Don't assume that the address of an @code{int} object is also the +address of its least-significant byte. This is false on big-endian +machines. Thus, don't make the following mistake: + +@example +int c; +@dots{} +while ((c = getchar()) != EOF) + write(file_descriptor, &c, 1); +@end example + +When calling functions, you need not worry about the difference between +pointers of various types, or between pointers and integers. On most +machines, there's no difference anyway. As for the few machines where +there is a difference, all of them support Standard C prototypes, so you can +use prototypes (perhaps conditionalized to be active only in Standard C) +to make the code work on those systems. + +In certain cases, it is ok to pass integer and pointer arguments +indiscriminately to the same function, and use no prototype on any +system. For example, many GNU programs have error-reporting functions +that pass their arguments along to @code{printf} and friends: + +@example +error (s, a1, a2, a3) + char *s; + char *a1, *a2, *a3; +@{ + fprintf (stderr, "error: "); + fprintf (stderr, s, a1, a2, a3); +@} +@end example + +@noindent +In practice, this works on all machines, since a pointer is generally +the widest possible kind of argument; it is much simpler than any +``correct'' alternative. Be sure @emph{not} to use a prototype for such +functions. + +If you have decided to use Standard C, then you can instead define +@code{error} using @file{stdarg.h}, and pass the arguments along to +@code{vfprintf}. + +@cindex casting pointers to integers +Avoid casting pointers to integers if you can. Such casts greatly +reduce portability, and in most programs they are easy to avoid. In the +cases where casting pointers to integers is essential---such as, a Lisp +interpreter which stores type information as well as an address in one +word---you'll have to make explicit provisions to handle different word +sizes. You will also need to make provision for systems in which the +normal range of addresses you can get from @code{malloc} starts far away +from zero. + +@node System Functions +@section Calling System Functions +@cindex library functions, and portability +@cindex portability, and library functions + +C implementations differ substantially. Standard C reduces but does +not eliminate the incompatibilities; meanwhile, many GNU packages still +support pre-standard compilers because this is not hard to do. This +chapter gives recommendations for how to use the more-or-less standard C +library functions to avoid unnecessary loss of portability. + +@itemize @bullet +@item +Don't use the return value of @code{sprintf}. It returns the number of +characters written on some systems, but not on all systems. + +@item +Be aware that @code{vfprintf} is not always available. + +@item +@code{main} should be declared to return type @code{int}. It should +terminate either by calling @code{exit} or by returning the integer +status code; make sure it cannot ever return an undefined value. + +@cindex declaration for system functions +@item +Don't declare system functions explicitly. + +Almost any declaration for a system function is wrong on some system. +To minimize conflicts, leave it to the system header files to declare +system functions. If the headers don't declare a function, let it +remain undeclared. + +While it may seem unclean to use a function without declaring it, in +practice this works fine for most system library functions on the +systems where this really happens; thus, the disadvantage is only +theoretical. By contrast, actual declarations have frequently caused +actual conflicts. + +@item +If you must declare a system function, don't specify the argument types. +Use an old-style declaration, not a Standard C prototype. The more you +specify about the function, the more likely a conflict. + +@item +In particular, don't unconditionally declare @code{malloc} or +@code{realloc}. + +Most GNU programs use those functions just once, in functions +conventionally named @code{xmalloc} and @code{xrealloc}. These +functions call @code{malloc} and @code{realloc}, respectively, and +check the results. + +Because @code{xmalloc} and @code{xrealloc} are defined in your program, +you can declare them in other files without any risk of type conflict. + +On most systems, @code{int} is the same length as a pointer; thus, the +calls to @code{malloc} and @code{realloc} work fine. For the few +exceptional systems (mostly 64-bit machines), you can use +@strong{conditionalized} declarations of @code{malloc} and +@code{realloc}---or put these declarations in configuration files +specific to those systems. + +@cindex string library functions +@item +The string functions require special treatment. Some Unix systems have +a header file @file{string.h}; others have @file{strings.h}. Neither +file name is portable. There are two things you can do: use Autoconf to +figure out which file to include, or don't include either file. + +@item +If you don't include either strings file, you can't get declarations for +the string functions from the header file in the usual way. + +That causes less of a problem than you might think. The newer standard +string functions should be avoided anyway because many systems still +don't support them. The string functions you can use are these: + +@example +strcpy strncpy strcat strncat +strlen strcmp strncmp +strchr strrchr +@end example + +The copy and concatenate functions work fine without a declaration as +long as you don't use their values. Using their values without a +declaration fails on systems where the width of a pointer differs from +the width of @code{int}, and perhaps in other cases. It is trivial to +avoid using their values, so do that. + +The compare functions and @code{strlen} work fine without a declaration +on most systems, possibly all the ones that GNU software runs on. +You may find it necessary to declare them @strong{conditionally} on a +few systems. + +The search functions must be declared to return @code{char *}. Luckily, +there is no variation in the data type they return. But there is +variation in their names. Some systems give these functions the names +@code{index} and @code{rindex}; other systems use the names +@code{strchr} and @code{strrchr}. Some systems support both pairs of +names, but neither pair works on all systems. + +You should pick a single pair of names and use it throughout your +program. (Nowadays, it is better to choose @code{strchr} and +@code{strrchr} for new programs, since those are the standard +names.) Declare both of those names as functions returning @code{char +*}. On systems which don't support those names, define them as macros +in terms of the other pair. For example, here is what to put at the +beginning of your file (or in a header) if you want to use the names +@code{strchr} and @code{strrchr} throughout: + +@example +#ifndef HAVE_STRCHR +#define strchr index +#endif +#ifndef HAVE_STRRCHR +#define strrchr rindex +#endif + +char *strchr (); +char *strrchr (); +@end example +@end itemize + +Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are +macros defined in systems where the corresponding functions exist. +One way to get them properly defined is to use Autoconf. + +@node Internationalization +@section Internationalization +@cindex internationalization + +@pindex gettext +GNU has a library called GNU gettext that makes it easy to translate the +messages in a program into various languages. You should use this +library in every program. Use English for the messages as they appear +in the program, and let gettext provide the way to translate them into +other languages. + +Using GNU gettext involves putting a call to the @code{gettext} macro +around each string that might need translation---like this: + +@example +printf (gettext ("Processing file `%s'...")); +@end example + +@noindent +This permits GNU gettext to replace the string @code{"Processing file +`%s'..."} with a translated version. + +Once a program uses gettext, please make a point of writing calls to +@code{gettext} when you add new strings that call for translation. + +Using GNU gettext in a package involves specifying a @dfn{text domain +name} for the package. The text domain name is used to separate the +translations for this package from the translations for other packages. +Normally, the text domain name should be the same as the name of the +package---for example, @samp{fileutils} for the GNU file utilities. + +@cindex message text, and internationalization +To enable gettext to work well, avoid writing code that makes +assumptions about the structure of words or sentences. When you want +the precise text of a sentence to vary depending on the data, use two or +more alternative string constants each containing a complete sentences, +rather than inserting conditionalized words or phrases into a single +sentence framework. + +Here is an example of what not to do: + +@example +printf ("%d file%s processed", nfiles, + nfiles != 1 ? "s" : ""); +@end example + +@noindent +The problem with that example is that it assumes that plurals are made +by adding `s'. If you apply gettext to the format string, like this, + +@example +printf (gettext ("%d file%s processed"), nfiles, + nfiles != 1 ? "s" : ""); +@end example + +@noindent +the message can use different words, but it will still be forced to use +`s' for the plural. Here is a better way: + +@example +printf ((nfiles != 1 ? "%d files processed" + : "%d file processed"), + nfiles); +@end example + +@noindent +This way, you can apply gettext to each of the two strings +independently: + +@example +printf ((nfiles != 1 ? gettext ("%d files processed") + : gettext ("%d file processed")), + nfiles); +@end example + +@noindent +This can be any method of forming the plural of the word for ``file'', and +also handles languages that require agreement in the word for +``processed''. + +A similar problem appears at the level of sentence structure with this +code: + +@example +printf ("# Implicit rule search has%s been done.\n", + f->tried_implicit ? "" : " not"); +@end example + +@noindent +Adding @code{gettext} calls to this code cannot give correct results for +all languages, because negation in some languages requires adding words +at more than one place in the sentence. By contrast, adding +@code{gettext} calls does the job straightfowardly if the code starts +out like this: + +@example +printf (f->tried_implicit + ? "# Implicit rule search has been done.\n", + : "# Implicit rule search has not been done.\n"); +@end example + +@node Mmap +@section Mmap +@findex mmap + +Don't assume that @code{mmap} either works on all files or fails +for all files. It may work on some files and fail on others. + +The proper way to use @code{mmap} is to try it on the specific file for +which you want to use it---and if @code{mmap} doesn't work, fall back on +doing the job in another way using @code{read} and @code{write}. + +The reason this precaution is needed is that the GNU kernel (the HURD) +provides a user-extensible file system, in which there can be many +different kinds of ``ordinary files.'' Many of them support +@code{mmap}, but some do not. It is important to make programs handle +all these kinds of files. + +@node Documentation +@chapter Documenting Programs +@cindex documentation + +A GNU program should ideally come with full free documentation, adequate +for both reference and tutorial purposes. If the package can be +programmed or extended, the documentation should cover programming or +extending it, as well as just using it. + +@menu +* GNU Manuals:: Writing proper manuals. +* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. +* Manual Structure Details:: Specific structure conventions. +* License for Manuals:: Writing the distribution terms for a manual. +* Manual Credits:: Giving credit to documentation contributors. +* Printed Manuals:: Mentioning the printed manual. +* NEWS File:: NEWS files supplement manuals. +* Change Logs:: Recording Changes +* Man Pages:: Man pages are secondary. +* Reading other Manuals:: How far you can go in learning + from other manuals. +@end menu + +@node GNU Manuals +@section GNU Manuals + +The preferred document format for the GNU system is the Texinfo +formatting language. Every GNU package should (ideally) have +documentation in Texinfo both for reference and for learners. Texinfo +makes it possible to produce a good quality formatted book, using +@TeX{}, and to generate an Info file. It is also possible to generate +HTML output from Texinfo source. See the Texinfo manual, either the +hardcopy, or the on-line version available through @code{info} or the +Emacs Info subsystem (@kbd{C-h i}). + +Nowadays some other formats such as Docbook and Sgmltexi can be +converted automatically into Texinfo. It is ok to produce the Texinfo +documentation by conversion this way, as long as it gives good results. + +Programmers often find it most natural to structure the documentation +following the structure of the implementation, which they know. But +this structure is not necessarily good for explaining how to use the +program; it may be irrelevant and confusing for a user. + +At every level, from the sentences in a paragraph to the grouping of +topics into separate manuals, the right way to structure documentation +is according to the concepts and questions that a user will have in mind +when reading it. Sometimes this structure of ideas matches the +structure of the implementation of the software being documented---but +often they are different. Often the most important part of learning to +write good documentation is learning to notice when you are structuring +the documentation like the implementation, and think about better +alternatives. + +For example, each program in the GNU system probably ought to be +documented in one manual; but this does not mean each program should +have its own manual. That would be following the structure of the +implementation, rather than the structure that helps the user +understand. + +Instead, each manual should cover a coherent @emph{topic}. For example, +instead of a manual for @code{diff} and a manual for @code{diff3}, we +have one manual for ``comparison of files'' which covers both of those +programs, as well as @code{cmp}. By documenting these programs +together, we can make the whole subject clearer. + +The manual which discusses a program should certainly document all of +the program's command-line options and all of its commands. It should +give examples of their use. But don't organize the manual as a list +of features. Instead, organize it logically, by subtopics. Address +the questions that a user will ask when thinking about the job that +the program does. Don't just tell the reader what each feature can +do---say what jobs it is good for, and show how to use it for those +jobs. Explain what is recommended usage, and what kinds of usage +users should avoid. + +In general, a GNU manual should serve both as tutorial and reference. +It should be set up for convenient access to each topic through Info, +and for reading straight through (appendixes aside). A GNU manual +should give a good introduction to a beginner reading through from the +start, and should also provide all the details that hackers want. +The Bison manual is a good example of this---please take a look at it +to see what we mean. + +That is not as hard as it first sounds. Arrange each chapter as a +logical breakdown of its topic, but order the sections, and write their +text, so that reading the chapter straight through makes sense. Do +likewise when structuring the book into chapters, and when structuring a +section into paragraphs. The watchword is, @emph{at each point, address +the most fundamental and important issue raised by the preceding text.} + +If necessary, add extra chapters at the beginning of the manual which +are purely tutorial and cover the basics of the subject. These provide +the framework for a beginner to understand the rest of the manual. The +Bison manual provides a good example of how to do this. + +To serve as a reference, a manual should have an Index that list all the +functions, variables, options, and important concepts that are part of +the program. One combined Index should do for a short manual, but +sometimes for a complex package it is better to use multiple indices. +The Texinfo manual includes advice on preparing good index entries, see +@ref{Index Entries, , Making Index Entries, texinfo, The GNU Texinfo +Manual}, and see @ref{Indexing Commands, , Defining the Entries of an +Index, texinfo, The GNU Texinfo manual}. + +Don't use Unix man pages as a model for how to write GNU documentation; +most of them are terse, badly structured, and give inadequate +explanation of the underlying concepts. (There are, of course, some +exceptions.) Also, Unix man pages use a particular format which is +different from what we use in GNU manuals. + +Please include an email address in the manual for where to report +bugs @emph{in the text of the manual}. + +Please do not use the term ``pathname'' that is used in Unix +documentation; use ``file name'' (two words) instead. We use the term +``path'' only for search paths, which are lists of directory names. + +Please do not use the term ``illegal'' to refer to erroneous input to +a computer program. Please use ``invalid'' for this, and reserve the +term ``illegal'' for activities prohibited by law. + +@node Doc Strings and Manuals +@section Doc Strings and Manuals + +Some programming systems, such as Emacs, provide a documentation string +for each function, command or variable. You may be tempted to write a +reference manual by compiling the documentation strings and writing a +little additional text to go around them---but you must not do it. That +approach is a fundamental mistake. The text of well-written +documentation strings will be entirely wrong for a manual. + +A documentation string needs to stand alone---when it appears on the +screen, there will be no other text to introduce or explain it. +Meanwhile, it can be rather informal in style. + +The text describing a function or variable in a manual must not stand +alone; it appears in the context of a section or subsection. Other text +at the beginning of the section should explain some of the concepts, and +should often make some general points that apply to several functions or +variables. The previous descriptions of functions and variables in the +section will also have given information about the topic. A description +written to stand alone would repeat some of that information; this +redundance looks bad. Meanwhile, the informality that is acceptable in +a documentation string is totally unacceptable in a manual. + +The only good way to use documentation strings in writing a good manual +is to use them as a source of information for writing good text. + +@node Manual Structure Details +@section Manual Structure Details +@cindex manual structure + +The title page of the manual should state the version of the programs or +packages documented in the manual. The Top node of the manual should +also contain this information. If the manual is changing more +frequently than or independent of the program, also state a version +number for the manual in both of these places. + +Each program documented in the manual should have a node named +@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This +node (together with its subnodes, if any) should describe the program's +command line arguments and how to run it (the sort of information people +would look in a man page for). Start with an @samp{@@example} +containing a template for all the options and arguments that the program +uses. + +Alternatively, put a menu item in some menu whose item name fits one of +the above patterns. This identifies the node which that item points to +as the node for this purpose, regardless of the node's actual name. + +The @samp{--usage} feature of the Info reader looks for such a node +or menu item in order to find the relevant text, so it is essential +for every Texinfo file to have one. + +If one manual describes several programs, it should have such a node for +each program described in the manual. + +@node License for Manuals +@section License for Manuals +@cindex license for manuals + +Please use the GNU Free Documentation License for all GNU manuals that +are more than a few pages long. Likewise for a collection of short +documents---you only need one copy of the GNU FDL for the whole +collection. For a single short document, you can use a very permissive +non-copyleft license, to avoid taking up space with a long license. + +See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation +of how to employ the GFDL. + +Note that it is not obligatory to include a copy of the GNU GPL or GNU +LGPL in a manual whose license is neither the GPL nor the LGPL. It can +be a good idea to include the program's license in a large manual; in a +short manual, whose size would be increased considerably by including +the program's license, it is probably better not to include it. + +@node Manual Credits +@section Manual Credits +@cindex credits for manuals + +Please credit the principal human writers of the manual as the authors, +on the title page of the manual. If a company sponsored the work, thank +the company in a suitable place in the manual, but do not cite the +company as an author. + +@node Printed Manuals +@section Printed Manuals + +The FSF publishes some GNU manuals in printed form. To encourage sales +of these manuals, the on-line versions of the manual should mention at +the very start that the printed manual is available and should point at +information for getting it---for instance, with a link to the page +@url{http://www.gnu.org/order/order.html}. This should not be included +in the printed manual, though, because there it is redundant. + +It is also useful to explain in the on-line forms of the manual how the +user can print out the manual from the sources. + +@node NEWS File +@section The NEWS File +@cindex @file{NEWS} file + +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; leave +them in the file after the newer items. This way, a user upgrading from +any previous version can see what is new. + +If the @file{NEWS} file gets very long, move some of the older items +into a file named @file{ONEWS} and put a note at the end referring the +user to that file. + +@node Change Logs +@section Change Logs +@cindex change logs + +Keep a change log to describe all the changes made to program source +files. The purpose of this is so that people investigating bugs in the +future will know about the changes that might have introduced the bug. +Often a new bug can be found by looking at what was recently changed. +More importantly, change logs can help you eliminate conceptual +inconsistencies between different parts of a program, by giving you a +history of how the conflicting concepts arose and who they came from. + +@menu +* Change Log Concepts:: +* Style of Change Logs:: +* Simple Changes:: +* Conditional Changes:: +* Indicating the Part Changed:: +@end menu + +@node Change Log Concepts +@subsection Change Log Concepts + +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. + +The change log file is normally called @file{ChangeLog} and covers an +entire directory. Each directory can have its own change log, or a +directory can use the change log of its parent directory--it's up to +you. + +Another alternative is to record change log information with a version +control system such as RCS or CVS. This can be converted automatically +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. If you think that a change calls for explanation, you're +probably right. Please do explain it---but please put the explanation +in comments in the code, where people will see it whenever they see the +code. For example, ``New function'' is enough for the change log when +you add a 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, etc.) in change logs. However, we've been +advised that it is a good idea to include them, for the sake of +copyright records. + +However, sometimes it is useful to write one line to describe the +overall purpose of a batch of changes. + +The easiest way to add an entry to @file{ChangeLog} is with the Emacs +command @kbd{M-x add-change-log-entry}. An entry should have an +asterisk, the name of the changed file, and then in parentheses the name +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 +@subsection Style of Change Logs +@cindex change logs, style + +Here are some simple examples of change log entries, starting with the +header line that says who made the change and when it was installed, +followed by descriptions of specific changes. (These examples are +drawn from Emacs and GCC.) + +@example +1998-08-17 Richard Stallman <rms@@gnu.org> + +* register.el (insert-register): Return nil. +(jump-to-register): Likewise. + +* sort.el (sort-subr): Return nil. + +* tex-mode.el (tex-bibtex-file, tex-file, tex-region): +Restart the tex shell if process is gone or stopped. +(tex-shell-running): New function. + +* expr.c (store_one_arg): Round size up for move_block_to_reg. +(expand_call): Round up when emitting USE insns. +* stmt.c (assign_parms): Round size up for move_block_from_reg. +@end example + +It's important to name the changed function or variable in full. Don't +abbreviate function or variable names, and don't combine them. +Subsequent maintainers will often search for a function name to find all +the change log entries that pertain to it; if you abbreviate the name, +they won't find it when they search. + +For example, some people are tempted to abbreviate groups of function +names by writing @samp{* register.el (@{insert,jump-to@}-register)}; +this is not a good idea, since searching for @code{jump-to-register} or +@code{insert-register} would not find that entry. + +Separate unrelated change log entries with blank lines. When two +entries represent parts of the same change, so that they work together, +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. + +Break long lists of function names by closing continued lines with +@samp{)}, rather than @samp{,}, and opening the continuation with +@samp{(} as in this example: + +@example +* keyboard.c (menu_bar_items, tool_bar_items) +(Fexecute_extended_command): Deal with `keymap' property. +@end example + +When you install someone else's changes, put the contributor's name in +the change log entry rather than in the text of the entry. In other +words, write this: + +@example +2002-07-14 John Doe <jdoe@@gnu.org> + + * sewing.c: Make it sew. +@end example + +@noindent +rather than this: + +@example +2002-07-14 Usual Maintainer <usual@@gnu.org> + + * sewing.c: Make it sew. Patch by jdoe@@gnu.org. +@end example + +As for the date, that should be the date you applied the change. + +@node Simple Changes +@subsection Simple Changes + +Certain simple kinds of changes don't need much detail in the change +log. + +When you change the calling sequence of a function in a simple fashion, +and you change all the callers of the function to use the new calling +sequence, there is no need to make individual entries for all the +callers that you changed. Just write in the entry for the function +being called, ``All callers changed''---like this: + +@example +* keyboard.c (Fcommand_execute): New arg SPECIAL. +All callers changed. +@end example + +When you change just comments or doc strings, it is enough to write an +entry for the file, without mentioning the functions. Just ``Doc +fixes'' is enough for the change log. + +There's no technical need to make change log entries for documentation +files. This is because documentation is not susceptible to bugs that +are hard to fix. Documentation does not consist of parts that must +interact in a precisely engineered fashion. To correct an error, you +need not know the history of the erroneous passage; it is enough to +compare what the documentation says with the way the program actually +works. + +However, you should keep change logs for documentation files when the +project gets copyright assignments from its contributors, so as to +make the records of authorship more accurate. + +@node Conditional Changes +@subsection Conditional Changes +@cindex conditional changes, and change logs +@cindex change logs, conditional changes + +C programs often contain compile-time @code{#if} conditionals. Many +changes are conditional; sometimes you add a new definition which is +entirely contained in a conditional. It is very useful to indicate in +the change log the conditions for which the change applies. + +Our convention for indicating conditional changes is to use square +brackets around the name of the condition. + +Here is a simple example, describing a change which is conditional but +does not have a function or entity name associated with it: + +@example +* xterm.c [SOLARIS2]: Include string.h. +@end example + +Here is an entry describing a new definition which is entirely +conditional. This new definition for the macro @code{FRAME_WINDOW_P} is +used only when @code{HAVE_X_WINDOWS} is defined: + +@example +* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. +@end example + +Here is an entry for a change within the function @code{init_display}, +whose definition as a whole is unconditional, but the changes themselves +are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional: + +@example +* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. +@end example + +Here is an entry for a change that takes affect only when +a certain macro is @emph{not} defined: + +@example +(gethostname) [!HAVE_SOCKETS]: Replace with winsock version. +@end example + +@node Indicating the Part Changed +@subsection Indicating the Part Changed + +Indicate the part of a function which changed by using angle brackets +enclosing an indication of what the changed part does. Here is an entry +for a change in the part of the function @code{sh-while-getopts} that +deals with @code{sh} commands: + +@example +* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that +user-specified option string is empty. +@end example + + +@node Man Pages +@section Man Pages +@cindex man pages + +In the GNU project, man pages are secondary. It is not necessary or +expected for every GNU program to have a man page, but some of them do. +It's your choice whether to include a man page in your program. + +When you make this decision, consider that supporting a man page +requires continual effort each time the program is changed. The time +you spend on the man page is time taken away from more useful work. + +For a simple program which changes little, updating the man page may be +a small job. Then there is little reason not to include a man page, if +you have one. + +For a large program that changes a great deal, updating a man page may +be a substantial burden. If a user offers to donate a man page, you may +find this gift costly to accept. It may be better to refuse the man +page unless the same person agrees to take full responsibility for +maintaining it---so that you can wash your hands of it entirely. If +this volunteer later ceases to do the job, then don't feel obliged to +pick it up yourself; it may be better to withdraw the man page from the +distribution until someone else agrees to update it. + +When a program changes only a little, you may feel that the +discrepancies are small enough that the man page remains useful without +updating. If so, put a prominent note near the beginning of the man +page explaining that you don't maintain it and that the Texinfo manual +is more authoritative. The note should say how to access the Texinfo +documentation. + +@node Reading other Manuals +@section Reading other Manuals + +There may be non-free books or documentation files that describe the +program you are documenting. + +It is ok to use these documents for reference, just as the author of a +new algebra textbook can read other books on algebra. A large portion +of any non-fiction book consists of facts, in this case facts about how +a certain program works, and these facts are necessarily the same for +everyone who writes about the subject. But be careful not to copy your +outline structure, wording, tables or examples from preexisting non-free +documentation. Copying from free documentation may be ok; please check +with the FSF about the individual case. + +@node Managing Releases +@chapter The Release Process +@cindex releasing + +Making a release is more than just bundling up your source files in a +tar file and putting it up for FTP. You should set up your software so +that it can be configured to run on a variety of systems. Your Makefile +should conform to the GNU standards described below, and your directory +layout should also conform to the standards discussed below. Doing so +makes it easy to include your package into the larger framework of +all GNU software. + +@menu +* Configuration:: How Configuration Should Work +* Makefile Conventions:: Makefile Conventions +* Releases:: Making Releases +@end menu + +@node Configuration +@section How Configuration Should Work +@cindex program configuration + +@pindex configure +Each GNU distribution should come with a shell script named +@code{configure}. This script is given arguments which describe the +kind of machine and system you want to compile the program for. + +The @code{configure} script must record the configuration options so +that they affect compilation. + +One way to do this is to make a link from a standard name such as +@file{config.h} to the proper configuration file for the chosen system. +If you use this technique, the distribution should @emph{not} contain a +file named @file{config.h}. This is so that people won't be able to +build the program without configuring it first. + +Another thing that @code{configure} can do is to edit the Makefile. If +you do this, the distribution should @emph{not} contain a file named +@file{Makefile}. Instead, it should include a file @file{Makefile.in} which +contains the input used for editing. Once again, this is so that people +won't be able to build the program without configuring it first. + +If @code{configure} does write the @file{Makefile}, then @file{Makefile} +should have a target named @file{Makefile} which causes @code{configure} +to be rerun, setting up the same configuration that was set up last +time. The files that @code{configure} reads should be listed as +dependencies of @file{Makefile}. + +All the files which are output from the @code{configure} script should +have comments at the beginning explaining that they were generated +automatically using @code{configure}. This is so that users won't think +of trying to edit them by hand. + +The @code{configure} script should write a file named @file{config.status} +which describes which configuration options were specified when the +program was last configured. This file should be a shell script which, +if run, will recreate the same configuration. + +The @code{configure} script should accept an option of the form +@samp{--srcdir=@var{dirname}} to specify the directory where sources are found +(if it is not the current directory). This makes it possible to build +the program in a separate directory, so that the actual source directory +is not modified. + +If the user does not specify @samp{--srcdir}, then @code{configure} should +check both @file{.} and @file{..} to see if it can find the sources. If +it finds the sources in one of these places, it should use them from +there. Otherwise, it should report that it cannot find the sources, and +should exit with nonzero status. + +Usually the easy way to support @samp{--srcdir} is by editing a +definition of @code{VPATH} into the Makefile. Some rules may need to +refer explicitly to the specified source directory. To make this +possible, @code{configure} can add to the Makefile a variable named +@code{srcdir} whose value is precisely the specified directory. + +The @code{configure} script should also take an argument which specifies the +type of system to build the program for. This argument should look like +this: + +@example +@var{cpu}-@var{company}-@var{system} +@end example + +For example, an Athlon-based GNU/Linux system might be +@samp{i686-pc-linux-gnu}. + +The @code{configure} script needs to be able to decode all plausible +alternatives for how to describe a machine. Thus, +@samp{athlon-pc-gnu/linux} would be a valid alias. +There is a shell script called +@uref{ftp://ftp.gnu.org/gnu/config/config.sub, @file{config.sub}} +that you can use +as a subroutine to validate system types and canonicalize aliases. + +The @code{configure} script should also take the option +@option{--build=@var{buildtype}}, which should be equivalent to a +plain @var{buildtype} argument. For example, @samp{configure +--build=i686-pc-linux-gnu} is equivalent to @samp{configure +i686-pc-linux-gnu}. When the build type is not specified by an option +or argument, the @code{configure} script should normally guess it +using the shell script +@uref{ftp://ftp.gnu.org/gnu/config/config.guess, @file{config.guess}}. + +@cindex optional features, configure-time +Other options are permitted to specify in more detail the software +or hardware present on the machine, and include or exclude optional +parts of the package: + +@table @samp +@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} +Configure the package to build and install an optional user-level +facility called @var{feature}. This allows users to choose which +optional features to include. Giving an optional @var{parameter} of +@samp{no} should omit @var{feature}, if it is built by default. + +No @samp{--enable} option should @strong{ever} cause one feature to +replace another. No @samp{--enable} option should ever substitute one +useful behavior for another useful behavior. The only proper use for +@samp{--enable} is for questions of whether to build part of the program +or exclude it. + +@item --with-@var{package} +@c @r{[}=@var{parameter}@r{]} +The package @var{package} will be installed, so configure this package +to work with @var{package}. + +@c Giving an optional @var{parameter} of +@c @samp{no} should omit @var{package}, if it is used by default. + +Possible values of @var{package} include +@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, +@samp{gdb}, +@samp{x}, +and +@samp{x-toolkit}. + +Do not use a @samp{--with} option to specify the file name to use to +find certain files. That is outside the scope of what @samp{--with} +options are for. +@end table + +All @code{configure} scripts should accept all of these ``detail'' +options, whether or not they make any difference to the particular +package at hand. In particular, they should accept any option that +starts with @samp{--with-} or @samp{--enable-}. This is so users will +be able to configure an entire GNU source tree at once with a single set +of options. + +You will note that the categories @samp{--with-} and @samp{--enable-} +are narrow: they @strong{do not} provide a place for any sort of option +you might think of. That is deliberate. We want to limit the possible +configuration options in GNU software. We do not want GNU programs to +have idiosyncratic configuration options. + +Packages that perform part of the compilation process may support +cross-compilation. In such a case, the host and target machines for the +program may be different. + +The @code{configure} script should normally treat the specified type of +system as both the host and the target, thus producing a program which +works for the same type of machine that it runs on. + +To compile a program to run on a host type that differs from the build +type, use the configure option @option{--host=@var{hosttype}}, where +@var{hosttype} uses the same syntax as @var{buildtype}. The host type +normally defaults to the build type. + +To configure a cross-compiler, cross-assembler, or what have you, you +should specify a target different from the host, using the configure +option @samp{--target=@var{targettype}}. The syntax for +@var{targettype} is the same as for the host type. So the command would +look like this: + +@example +./configure --host=@var{hosttype} --target=@var{targettype} +@end example + +The target type normally defaults to the host type. +Programs for which cross-operation is not meaningful need not accept the +@samp{--target} option, because configuring an entire operating system for +cross-operation is not a meaningful operation. + +Some programs have ways of configuring themselves automatically. If +your program is set up to do this, your @code{configure} script can simply +ignore most of its arguments. + +@comment The makefile standards are in a separate file that is also +@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. +@comment For this document, turn chapters into sections, etc. +@lowersections +@include make-stds.texi +@raisesections + +@node Releases +@section Making Releases +@cindex packaging + +You should identify each release with a pair of version numbers, a +major version and a minor. We have no objection to using more than +two numbers, but it is very unlikely that you really need them. + +Package the distribution of @code{Foo version 69.96} up in a gzipped tar +file with the name @file{foo-69.96.tar.gz}. It should unpack into a +subdirectory named @file{foo-69.96}. + +Building and installing the program should never modify any of the files +contained in the distribution. This means that all the files that form +part of the program in any way must be classified into @dfn{source +files} and @dfn{non-source files}. Source files are written by humans +and never changed automatically; non-source files are produced from +source files by programs under the control of the Makefile. + +@cindex @file{README} file +The distribution should contain a file named @file{README} which gives +the name of the package, and a general description of what it does. It +is also good to explain the purpose of each of the first-level +subdirectories in the package, if there are any. The @file{README} file +should either state the version number of the package, or refer to where +in the package it can be found. + +The @file{README} file should refer to the file @file{INSTALL}, which +should contain an explanation of the installation procedure. + +The @file{README} file should also refer to the file which contains the +copying conditions. The GNU GPL, if used, should be in a file called +@file{COPYING}. If the GNU LGPL is used, it should be in a file called +@file{COPYING.LIB}. + +Naturally, all the source files must be in the distribution. It is okay +to include non-source files in the distribution, provided they are +up-to-date and machine-independent, so that building the distribution +normally will never modify them. We commonly include non-source files +produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid +unnecessary dependencies between our distributions, so that users can +install whichever packages they want to install. + +Non-source files that might actually be modified by building and +installing the program should @strong{never} be included in the +distribution. So if you do distribute non-source files, always make +sure they are up to date when you make a new distribution. + +Make sure that the directory into which the distribution unpacks (as +well as any subdirectories) are all world-writable (octal mode 777). +This is so that old versions of @code{tar} which preserve the +ownership and permissions of the files from the tar archive will be +able to extract all the files even if the user is unprivileged. + +Make sure that all the files in the distribution are world-readable. + +Don't include any symbolic links in the distribution itself. If the tar +file contains symbolic links, then people cannot even unpack it on +systems that don't support symbolic links. Also, don't use multiple +names for one file in different directories, because certain file +systems cannot handle this and that prevents unpacking the +distribution. + +Try to make sure that all the file names will be unique on MS-DOS. A +name on MS-DOS consists of up to 8 characters, optionally followed by a +period and up to three characters. MS-DOS will truncate extra +characters both before and after the period. Thus, +@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they +are truncated to @file{foobarha.c} and @file{foobarha.o}, which are +distinct. + +@cindex @file{texinfo.tex}, in a distribution +Include in your distribution a copy of the @file{texinfo.tex} you used +to test print any @file{*.texinfo} or @file{*.texi} files. + +Likewise, if your program uses small GNU software packages like regex, +getopt, obstack, or termcap, include them in the distribution file. +Leaving them out would make the distribution file a little smaller at +the expense of possible inconvenience to a user who doesn't know what +other files to get. + +@node References +@chapter References to Non-Free Software and Documentation +@cindex references to non-free material + +A GNU program should not recommend use of any non-free program. We +can't stop some people from writing proprietary programs, or stop +other people from using them, but we can and should refuse to +advertise them to new potential customers. Proprietary software is a +social and ethical problem, and the point of GNU is to solve that +problem. + +The GNU definition of free software is found in +@url{http://www.gnu.org/philosophy/free-sw.html}, with a list of +important licenses and whether they qualify as free in +@url{http://www.gnu.org/licenses/license-list.html}. The terms +``free'' and ``non-free'', used in this document, refer to that +definition. If it is not clear whether a license qualifies as free +under this definition, please ask the GNU Project by writing to +@email{licensing@@gnu.org}. We will answer, and if the license is an +important one, we will add it to the list. + +When a non-free program or system is well known, you can mention it in +passing---that is harmless, since users who might want to use it +probably already know about it. For instance, it is fine to explain +how to build your package on top of some widely used non-free +operating system, or how to use it together with some widely used +non-free program. + +However, you should give only the necessary information to help those +who already use the non-free program to use your program with +it---don't give, or refer to, any further information about the +proprietary program, and don't imply that the proprietary program +enhances your program, or that its existence is in any way a good +thing. The goal should be that people already using the proprietary +program will get the advice they need about how to use your free +program with it, while people who don't already use the proprietary +program will not see anything to lead them to take an interest in it. + +If a non-free program or system is obscure in your program's domain, +your program should not mention or support it at all, since doing so +would tend to popularize the non-free program more than it popularizes +your program. (You cannot hope to find many additional users among +the users of Foobar if the users of Foobar are few.) + +Sometimes a program is free software in itself but depends on a +non-free platform in order to run. For instance, many Java programs +depend on Sun's Java implementation, and won't run on the GNU Java +Compiler (which does not yet have all the features) or won't run with +the GNU Java libraries. To recommend that program is inherently to +recommend the non-free platform as well; if you should not do the +latter, then don't do the former. + +A GNU package should not refer the user to any non-free documentation +for free software. Free documentation that can be included in free +operating systems is essential for completing the GNU system, or any +free operating system, so it is a major focus of the GNU Project; to +recommend use of documentation that we are not allowed to use in GNU +would weaken the impetus for the community to produce documentation +that we can include. So GNU packages should never recommend non-free +documentation. + +By contrast, it is ok to refer to journal articles and textbooks in +the comments of a program for explanation of how it functions, even +though they be non-free. This is because we don't include such things +in the GNU system even if we are allowed to--they are outside the +scope of an operating system project. + +Referring to a web site that describes or recommends a non-free +program is in effect promoting that software, so please do not make +links (or mention by name) web sites that contain such material. This +policy is relevant particulary for the web pages for a GNU package. + +Following links from nearly any web site can lead to non-free +software; this is an inescapable aspect of the nature of the web, and +in itself is no objection to linking to a site. As long as the site +does not itself recommend a non-free program, there is no need be +concerned about the sites it links to for other reasons. + +Thus, for example, you should not make a link to AT&T's web site, +because that recommends AT&T's non-free software packages; you should +not make a link to a site that links to AT&T's site saying it is a +place to get a non-free program; but if a site you want to link to +refers to AT&T's web site in some other context (such as long-distance +telephone service), that is not a problem. + +@node Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual +@end menu + +@include fdl.texi + +@node Index +@unnumbered Index +@printindex cp + +@bye + +Local variables: +eval: (add-hook 'write-file-hooks 'time-stamp) +time-stamp-start: "@set lastupdate " +time-stamp-end: "$" +time-stamp-format: "%:b %:d, %:y" +compile-command: "make just-standards" +End: