OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [binutils-2.20.1/] [etc/] [standards.texi] - Blame information for rev 818

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 205 julius
\input texinfo @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename standards.info
4
@settitle GNU Coding Standards
5
@c This date is automagically updated when you save this file:
6
@set lastupdate July 22, 2007
7
@c %**end of header
8
 
9
@dircategory GNU organization
10
@direntry
11
* Standards: (standards).         GNU coding standards.
12
@end direntry
13
 
14
@c @setchapternewpage odd
15
@setchapternewpage off
16
 
17
@c Put everything in one index (arbitrarily chosen to be the concept index).
18
@syncodeindex fn cp
19
@syncodeindex ky cp
20
@syncodeindex pg cp
21
@syncodeindex vr cp
22
 
23
@c This is used by a cross ref in make-stds.texi
24
@set CODESTD  1
25
@iftex
26
@set CHAPTER chapter
27
@end iftex
28
@ifinfo
29
@set CHAPTER node
30
@end ifinfo
31
 
32
@copying
33
The GNU coding standards, last updated @value{lastupdate}.
34
 
35
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
36
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
37
Foundation, Inc.
38
 
39
Permission is granted to copy, distribute and/or modify this document
40
under the terms of the GNU Free Documentation License, Version 1.2
41
or any later version published by the Free Software Foundation;
42
with no Invariant Sections, with no
43
Front-Cover Texts, and with no Back-Cover Texts.
44
A copy of the license is included in the section entitled ``GNU
45
Free Documentation License''.
46
@end copying
47
 
48
@titlepage
49
@title GNU Coding Standards
50
@author Richard Stallman, et al.
51
@author last updated @value{lastupdate}
52
@page
53
@vskip 0pt plus 1filll
54
@insertcopying
55
@end titlepage
56
 
57
@contents
58
 
59
@ifnottex
60
@node Top, Preface, (dir), (dir)
61
@top Version
62
 
63
@insertcopying
64
@end ifnottex
65
 
66
@menu
67
* Preface::                     About the GNU Coding Standards.
68
* Legal Issues::                Keeping free software free.
69
* Design Advice::               General program design.
70
* Program Behavior::            Program behavior for all programs
71
* Writing C::                   Making the best use of C.
72
* Documentation::               Documenting programs.
73
* Managing Releases::           The release process.
74
* References::                  Mentioning non-free software or documentation.
75
* GNU Free Documentation License::  Copying and sharing this manual.
76
* Index::
77
 
78
@end menu
79
 
80
@node Preface
81
@chapter About the GNU Coding Standards
82
 
83
The GNU Coding Standards were written by Richard Stallman and other GNU
84
Project volunteers.  Their purpose is to make the GNU system clean,
85
consistent, and easy to install.  This document can also be read as a
86
guide to writing portable, robust and reliable programs.  It focuses on
87
programs written in C, but many of the rules and principles are useful
88
even if you write in another programming language.  The rules often
89
state reasons for writing in a certain way.
90
 
91
This release of the GNU Coding Standards was last updated
92
@value{lastupdate}.
93
 
94
@cindex where to obtain @code{standards.texi}
95
@cindex downloading this manual
96
If you did not obtain this file directly from the GNU project and
97
recently, please check for a newer version.  You can get the GNU
98
Coding Standards from the GNU web server in many
99
different formats, including the Texinfo source, PDF, HTML, DVI, plain
100
text, and more, at: @uref{http://www.gnu.org/prep/standards/}.
101
 
102
Corrections or suggestions for this document should be sent to
103
@email{bug-standards@@gnu.org}.  If you make a suggestion, please include a
104
suggested new wording for it; our time is limited.  We prefer a context
105
diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
106
you don't have those files, please mail your suggestion anyway.
107
 
108
These standards cover the minimum of what is important when writing a
109
GNU package.  Likely, the need for additional standards will come up.
110
Sometimes, you might suggest that such standards be added to this
111
document.  If you think your standards would be generally useful, please
112
do suggest them.
113
 
114
You should also set standards for your package on many questions not
115
addressed or not firmly specified here.  The most important point is to
116
be self-consistent---try to stick to the conventions you pick, and try
117
to document them as much as possible.  That way, your program will be
118
more maintainable by others.
119
 
120
The GNU Hello program serves as an example of how to follow the GNU
121
coding standards for a trivial program.
122
@uref{http://www.gnu.org/software/hello/hello.html}.
123
 
124
@node Legal Issues
125
@chapter Keeping Free Software Free
126
@cindex legal aspects
127
 
128
This chapter discusses how you can make sure that GNU software
129
avoids legal difficulties, and other related issues.
130
 
131
@menu
132
* Reading Non-Free Code::       Referring to proprietary programs.
133
* Contributions::               Accepting contributions.
134
* Trademarks::                  How we deal with trademark issues.
135
@end menu
136
 
137
@node Reading Non-Free Code
138
@section Referring to Proprietary Programs
139
@cindex proprietary programs
140
@cindex avoiding proprietary code
141
 
142
Don't in any circumstances refer to Unix source code for or during
143
your work on GNU!  (Or to any other proprietary programs.)
144
 
145
If you have a vague recollection of the internals of a Unix program,
146
this does not absolutely mean you can't write an imitation of it, but
147
do try to organize the imitation internally along different lines,
148
because this is likely to make the details of the Unix version
149
irrelevant and dissimilar to your results.
150
 
151
For example, Unix utilities were generally optimized to minimize
152
memory use; if you go for speed instead, your program will be very
153
different.  You could keep the entire input file in memory and scan it
154
there instead of using stdio.  Use a smarter algorithm discovered more
155
recently than the Unix program.  Eliminate use of temporary files.  Do
156
it in one pass instead of two (we did this in the assembler).
157
 
158
Or, on the contrary, emphasize simplicity instead of speed.  For some
159
applications, the speed of today's computers makes simpler algorithms
160
adequate.
161
 
162
Or go for generality.  For example, Unix programs often have static
163
tables or fixed-size strings, which make for arbitrary limits; use
164
dynamic allocation instead.  Make sure your program handles NULs and
165
other funny characters in the input files.  Add a programming language
166
for extensibility and write part of the program in that language.
167
 
168
Or turn some parts of the program into independently usable libraries.
169
Or use a simple garbage collector instead of tracking precisely when
170
to free memory, or use a new GNU facility such as obstacks.
171
 
172
@node Contributions
173
@section Accepting Contributions
174
@cindex legal papers
175
@cindex accepting contributions
176
 
177
If the program you are working on is copyrighted by the Free Software
178
Foundation, then when someone else sends you a piece of code to add to
179
the program, we need legal papers to use it---just as we asked you to
180
sign papers initially.  @emph{Each} person who makes a nontrivial
181
contribution to a program must sign some sort of legal papers in order
182
for us to have clear title to the program; the main author alone is not
183
enough.
184
 
185
So, before adding in any contributions from other people, please tell
186
us, so we can arrange to get the papers.  Then wait until we tell you
187
that we have received the signed papers, before you actually use the
188
contribution.
189
 
190
This applies both before you release the program and afterward.  If
191
you receive diffs to fix a bug, and they make significant changes, we
192
need legal papers for that change.
193
 
194
This also applies to comments and documentation files.  For copyright
195
law, comments and code are just text.  Copyright applies to all kinds of
196
text, so we need legal papers for all kinds.
197
 
198
We know it is frustrating to ask for legal papers; it's frustrating for
199
us as well.  But if you don't wait, you are going out on a limb---for
200
example, what if the contributor's employer won't sign a disclaimer?
201
You might have to take that code out again!
202
 
203
You don't need papers for changes of a few lines here or there, since
204
they are not significant for copyright purposes.  Also, you don't need
205
papers if all you get from the suggestion is some ideas, not actual code
206
which you use.  For example, if someone sent you one implementation, but
207
you write a different implementation of the same idea, you don't need to
208
get papers.
209
 
210
The very worst thing is if you forget to tell us about the other
211
contributor.  We could be very embarrassed in court some day as a
212
result.
213
 
214
We have more detailed advice for maintainers of programs; if you have
215
reached the stage of actually maintaining a program for GNU (whether
216
released or not), please ask us for a copy.  It is also available
217
online for your perusal: @uref{http://www.gnu.org/prep/maintain/}.
218
 
219
@node Trademarks
220
@section Trademarks
221
@cindex trademarks
222
 
223
Please do not include any trademark acknowledgements in GNU software
224
packages or documentation.
225
 
226
Trademark acknowledgements are the statements that such-and-such is a
227
trademark of so-and-so.  The GNU Project has no objection to the basic
228
idea of trademarks, but these acknowledgements feel like kowtowing,
229
and there is no legal requirement for them, so we don't use them.
230
 
231
What is legally required, as regards other people's trademarks, is to
232
avoid using them in ways which a reader might reasonably understand as
233
naming or labeling our own programs or activities.  For example, since
234
``Objective C'' is (or at least was) a trademark, we made sure to say
235
that we provide a ``compiler for the Objective C language'' rather
236
than an ``Objective C compiler''.  The latter would have been meant as
237
a shorter way of saying the former, but it does not explicitly state
238
the relationship, so it could be misinterpreted as using ``Objective
239
C'' as a label for the compiler rather than for the language.
240
 
241
Please don't use ``win'' as an abbreviation for Microsoft Windows in
242
GNU software or documentation.  In hacker terminology, calling
243
something a ``win'' is a form of praise.  If you wish to praise
244
Microsoft Windows when speaking on your own, by all means do so, but
245
not in GNU software.  Usually we write the name ``Windows'' in full,
246
but when brevity is very important (as in file names and sometimes
247
symbol names), we abbreviate it to ``w''.  For instance, the files and
248
functions in Emacs that deal with Windows start with @samp{w32}.
249
 
250
@node Design Advice
251
@chapter General Program Design
252
@cindex program design
253
 
254
This chapter discusses some of the issues you should take into
255
account when designing your program.
256
 
257
@c                         Standard or ANSI C
258
@c
259
@c In 1989 the American National Standards Institute (ANSI) standardized
260
@c C   as  standard  X3.159-1989.    In  December   of  that   year  the
261
@c International Standards Organization ISO  adopted the ANSI C standard
262
@c making  minor changes.   In 1990  ANSI then  re-adopted  ISO standard
263
@c C. This version of C is known as either ANSI C or Standard C.
264
 
265
@c A major revision of the C Standard appeared in 1999.
266
 
267
@menu
268
* Source Language::             Which languages to use.
269
* Compatibility::               Compatibility with other implementations.
270
* Using Extensions::            Using non-standard features.
271
* Standard C::                  Using standard C features.
272
* Conditional Compilation::     Compiling code only if a conditional is true.
273
@end menu
274
 
275
@node Source Language
276
@section Which Languages to Use
277
@cindex programming languages
278
 
279
When you want to use a language that gets compiled and runs at high
280
speed, the best language to use is C.  Using another language is like
281
using a non-standard feature: it will cause trouble for users.  Even if
282
GCC supports the other language, users may find it inconvenient to have
283
to install the compiler for that other language in order to build your
284
program.  For example, if you write your program in C++, people will
285
have to install the GNU C++ compiler in order to compile your program.
286
 
287
C has one other advantage over C++ and other compiled languages: more
288
people know C, so more people will find it easy to read and modify the
289
program if it is written in C.
290
 
291
So in general it is much better to use C, rather than the
292
comparable alternatives.
293
 
294
But there are two exceptions to that conclusion:
295
 
296
@itemize @bullet
297
@item
298
It is no problem to use another language to write a tool specifically
299
intended for use with that language.  That is because the only people
300
who want to build the tool will be those who have installed the other
301
language anyway.
302
 
303
@item
304
If an application is of interest only to a narrow part of the community,
305
then the question of which language it is written in has less effect on
306
other people, so you may as well please yourself.
307
@end itemize
308
 
309
Many programs are designed to be extensible: they include an interpreter
310
for a language that is higher level than C.  Often much of the program
311
is written in that language, too.  The Emacs editor pioneered this
312
technique.
313
 
314
@cindex GUILE
315
The standard extensibility interpreter for GNU software is GUILE
316
(@uref{http://www.gnu.org/software/guile/}), which implements the
317
language Scheme (an especially clean and simple dialect of Lisp).  We
318
don't reject programs written in other ``scripting languages'' such as
319
Perl and Python, but using GUILE is very important for the overall
320
consistency of the GNU system.
321
 
322
@node Compatibility
323
@section Compatibility with Other Implementations
324
@cindex compatibility with C and @sc{posix} standards
325
@cindex @sc{posix} compatibility
326
 
327
With occasional exceptions, utility programs and libraries for GNU
328
should be upward compatible with those in Berkeley Unix, and upward
329
compatible with Standard C if Standard C specifies their
330
behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
331
their behavior.
332
 
333
When these standards conflict, it is useful to offer compatibility
334
modes for each of them.
335
 
336
@cindex options for compatibility
337
Standard C and @sc{posix} prohibit many kinds of extensions.  Feel
338
free to make the extensions anyway, and include a @samp{--ansi},
339
@samp{--posix}, or @samp{--compatible} option to turn them off.
340
However, if the extension has a significant chance of breaking any real
341
programs or scripts, then it is not really upward compatible.  So you
342
should try to redesign its interface to make it upward compatible.
343
 
344
@cindex @code{POSIXLY_CORRECT}, environment variable
345
Many GNU programs suppress extensions that conflict with @sc{posix} if the
346
environment variable @code{POSIXLY_CORRECT} is defined (even if it is
347
defined with a null value).  Please make your program recognize this
348
variable if appropriate.
349
 
350
When a feature is used only by users (not by programs or command
351
files), and it is done poorly in Unix, feel free to replace it
352
completely with something totally different and better.  (For example,
353
@code{vi} is replaced with Emacs.)  But it is nice to offer a compatible
354
feature as well.  (There is a free @code{vi} clone, so we offer it.)
355
 
356
Additional useful features are welcome regardless of whether
357
there is any precedent for them.
358
 
359
@node Using Extensions
360
@section Using Non-standard Features
361
@cindex non-standard extensions
362
 
363
Many GNU facilities that already exist support a number of convenient
364
extensions over the comparable Unix facilities.  Whether to use these
365
extensions in implementing your program is a difficult question.
366
 
367
On the one hand, using the extensions can make a cleaner program.
368
On the other hand, people will not be able to build the program
369
unless the other GNU tools are available.  This might cause the
370
program to work on fewer kinds of machines.
371
 
372
With some extensions, it might be easy to provide both alternatives.
373
For example, you can define functions with a ``keyword'' @code{INLINE}
374
and define that as a macro to expand into either @code{inline} or
375
nothing, depending on the compiler.
376
 
377
In general, perhaps it is best not to use the extensions if you can
378
straightforwardly do without them, but to use the extensions if they
379
are a big improvement.
380
 
381
An exception to this rule are the large, established programs (such as
382
Emacs) which run on a great variety of systems.  Using GNU extensions in
383
such programs would make many users unhappy, so we don't do that.
384
 
385
Another exception is for programs that are used as part of compilation:
386
anything that must be compiled with other compilers in order to
387
bootstrap the GNU compilation facilities.  If these require the GNU
388
compiler, then no one can compile them without having them installed
389
already.  That would be extremely troublesome in certain cases.
390
 
391
@node Standard C
392
@section Standard C and Pre-Standard C
393
@cindex @sc{ansi} C standard
394
 
395
1989 Standard C is widespread enough now that it is ok to use its
396
features in new programs.  There is one exception: do not ever use the
397
``trigraph'' feature of Standard C.
398
 
399
1999 Standard C is not widespread yet, so please do not require its
400
features in programs.  It is ok to use its features if they are present.
401
 
402
However, it is easy to support pre-standard compilers in most programs,
403
so if you know how to do that, feel free.  If a program you are
404
maintaining has such support, you should try to keep it working.
405
 
406
@cindex function prototypes
407
To support pre-standard C, instead of writing function definitions in
408
standard prototype form,
409
 
410
@example
411
int
412
foo (int x, int y)
413
@dots{}
414
@end example
415
 
416
@noindent
417
write the definition in pre-standard style like this,
418
 
419
@example
420
int
421
foo (x, y)
422
     int x, y;
423
@dots{}
424
@end example
425
 
426
@noindent
427
and use a separate declaration to specify the argument prototype:
428
 
429
@example
430
int foo (int, int);
431
@end example
432
 
433
You need such a declaration anyway, in a header file, to get the benefit
434
of prototypes in all the files where the function is called.  And once
435
you have the declaration, you normally lose nothing by writing the
436
function definition in the pre-standard style.
437
 
438
This technique does not work for integer types narrower than @code{int}.
439
If you think of an argument as being of a type narrower than @code{int},
440
declare it as @code{int} instead.
441
 
442
There are a few special cases where this technique is hard to use.  For
443
example, if a function argument needs to hold the system type
444
@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
445
@code{int} on some machines; but you cannot use @code{int} instead,
446
because @code{dev_t} is wider than @code{int} on some machines.  There
447
is no type you can safely use on all machines in a non-standard
448
definition.  The only way to support non-standard C and pass such an
449
argument is to check the width of @code{dev_t} using Autoconf and choose
450
the argument type accordingly.  This may not be worth the trouble.
451
 
452
In order to support pre-standard compilers that do not recognize
453
prototypes, you may want to use a preprocessor macro like this:
454
 
455
@example
456
/* Declare the prototype for a general external function.  */
457
#if defined (__STDC__) || defined (WINDOWSNT)
458
#define P_(proto) proto
459
#else
460
#define P_(proto) ()
461
#endif
462
@end example
463
 
464
@node Conditional Compilation
465
@section Conditional Compilation
466
 
467
When supporting configuration options already known when building your
468
program we prefer using @code{if (... )} over conditional compilation,
469
as in the former case the compiler is able to perform more extensive
470
checking of all possible code paths.
471
 
472
For example, please write
473
 
474
@smallexample
475
  if (HAS_FOO)
476
    ...
477
  else
478
    ...
479
@end smallexample
480
 
481
@noindent
482
instead of:
483
 
484
@smallexample
485
  #ifdef HAS_FOO
486
    ...
487
  #else
488
    ...
489
  #endif
490
@end smallexample
491
 
492
A modern compiler such as GCC will generate exactly the same code in
493
both cases, and we have been using similar techniques with good success
494
in several projects.  Of course, the former method assumes that
495
@code{HAS_FOO} is defined as either 0 or 1.
496
 
497
While this is not a silver bullet solving all portability problems,
498
and is not always appropriate, following this policy would have saved
499
GCC developers many hours, or even days, per year.
500
 
501
In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
502
GCC which cannot be simply used in @code{if( ...)} statements, there is
503
an easy workaround.  Simply introduce another macro
504
@code{HAS_REVERSIBLE_CC_MODE} as in the following example:
505
 
506
@smallexample
507
  #ifdef REVERSIBLE_CC_MODE
508
  #define HAS_REVERSIBLE_CC_MODE 1
509
  #else
510
  #define HAS_REVERSIBLE_CC_MODE 0
511
  #endif
512
@end smallexample
513
 
514
@node Program Behavior
515
@chapter Program Behavior for All Programs
516
 
517
This chapter describes conventions for writing robust
518
software.  It also describes general standards for error messages, the
519
command line interface, and how libraries should behave.
520
 
521
@menu
522
* Non-GNU Standards::           We consider standards such as POSIX;
523
                                  we don't "obey" them.
524
* Semantics::                   Writing robust programs.
525
* Libraries::                   Library behavior.
526
* Errors::                      Formatting error messages.
527
* User Interfaces::             Standards about interfaces generally.
528
* Graphical Interfaces::        Standards for graphical interfaces.
529
* Command-Line Interfaces::     Standards for command line interfaces.
530
* Option Table::                Table of long options.
531
* Memory Usage::                When and how to care about memory needs.
532
* File Usage::                  Which files to use, and where.
533
@end menu
534
 
535
@node Non-GNU Standards
536
@section Non-GNU Standards
537
 
538
The GNU Project regards standards published by other organizations as
539
suggestions, not orders.  We consider those standards, but we do not
540
``obey'' them.  In developing a GNU program, you should implement
541
an outside standard's specifications when that makes the GNU system
542
better overall in an objective sense.  When it doesn't, you shouldn't.
543
 
544
In most cases, following published standards is convenient for
545
users---it means that their programs or scripts will work more
546
portably.  For instance, GCC implements nearly all the features of
547
Standard C as specified by that standard.  C program developers would
548
be unhappy if it did not.  And GNU utilities mostly follow
549
specifications of POSIX.2; shell script writers and users would be
550
unhappy if our programs were incompatible.
551
 
552
But we do not follow either of these specifications rigidly, and there
553
are specific points on which we decided not to follow them, so as to
554
make the GNU system better for users.
555
 
556
For instance, Standard C says that nearly all extensions to C are
557
prohibited.  How silly!  GCC implements many extensions, some of which
558
were later adopted as part of the standard.  If you want these
559
constructs to give an error message as ``required'' by the standard,
560
you must specify @samp{--pedantic}, which was implemented only so that
561
we can say ``GCC is a 100% implementation of the standard,'' not
562
because there is any reason to actually use it.
563
 
564
POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by
565
default in units of 512 bytes.  What users want is units of 1k, so
566
that is what we do by default.  If you want the ridiculous behavior
567
``required'' by POSIX, you must set the environment variable
568
@samp{POSIXLY_CORRECT} (which was originally going to be named
569
@samp{POSIX_ME_HARDER}).
570
 
571
GNU utilities also depart from the letter of the POSIX.2 specification
572
when they support long-named command-line options, and intermixing
573
options with ordinary arguments.  This minor incompatibility with
574
POSIX is never a problem in practice, and it is very useful.
575
 
576
In particular, don't reject a new feature, or remove an old one,
577
merely because a standard says it is ``forbidden'' or ``deprecated.''
578
 
579
@node Semantics
580
@section Writing Robust Programs
581
 
582
@cindex arbitrary limits on data
583
Avoid arbitrary limits on the length or number of @emph{any} data
584
structure, including file names, lines, files, and symbols, by allocating
585
all data structures dynamically.  In most Unix utilities, ``long lines
586
are silently truncated''.  This is not acceptable in a GNU utility.
587
 
588
@cindex @code{NUL} characters
589
Utilities reading files should not drop NUL characters, or any other
590
nonprinting characters @emph{including those with codes above 0177}.
591
The only sensible exceptions would be utilities specifically intended
592
for interface to certain types of terminals or printers
593
that can't handle those characters.
594
Whenever possible, try to make programs work properly with
595
sequences of bytes that represent multibyte characters, using encodings
596
such as UTF-8 and others.
597
 
598
@cindex error messages
599
Check every system call for an error return, unless you know you wish to
600
ignore errors.  Include the system error text (from @code{perror} or
601
equivalent) in @emph{every} error message resulting from a failing
602
system call, as well as the name of the file if any and the name of the
603
utility.  Just ``cannot open foo.c'' or ``stat failed'' is not
604
sufficient.
605
 
606
@cindex @code{malloc} return value
607
@cindex memory allocation failure
608
Check every call to @code{malloc} or @code{realloc} to see if it
609
returned zero.  Check @code{realloc} even if you are making the block
610
smaller; in a system that rounds block sizes to a power of 2,
611
@code{realloc} may get a different block if you ask for less space.
612
 
613
In Unix, @code{realloc} can destroy the storage block if it returns
614
zero.  GNU @code{realloc} does not have this bug: if it fails, the
615
original block is unchanged.  Feel free to assume the bug is fixed.  If
616
you wish to run your program on Unix, and wish to avoid lossage in this
617
case, you can use the GNU @code{malloc}.
618
 
619
You must expect @code{free} to alter the contents of the block that was
620
freed.  Anything you want to fetch from the block, you must fetch before
621
calling @code{free}.
622
 
623
If @code{malloc} fails in a noninteractive program, make that a fatal
624
error.  In an interactive program (one that reads commands from the
625
user), it is better to abort the command and return to the command
626
reader loop.  This allows the user to kill other processes to free up
627
virtual memory, and then try the command again.
628
 
629
@cindex command-line arguments, decoding
630
Use @code{getopt_long} to decode arguments, unless the argument syntax
631
makes this unreasonable.
632
 
633
When static storage is to be written in during program execution, use
634
explicit C code to initialize it.  Reserve C initialized declarations
635
for data that will not be changed.
636
@c ADR: why?
637
 
638
Try to avoid low-level interfaces to obscure Unix data structures (such
639
as file directories, utmp, or the layout of kernel memory), since these
640
are less likely to work compatibly.  If you need to find all the files
641
in a directory, use @code{readdir} or some other high-level interface.
642
These are supported compatibly by GNU.
643
 
644
@cindex signal handling
645
The preferred signal handling facilities are the BSD variant of
646
@code{signal}, and the @sc{posix} @code{sigaction} function; the
647
alternative USG @code{signal} interface is an inferior design.
648
 
649
Nowadays, using the @sc{posix} signal functions may be the easiest way
650
to make a program portable.  If you use @code{signal}, then on GNU/Linux
651
systems running GNU libc version 1, you should include
652
@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
653
behavior.  It is up to you whether to support systems where
654
@code{signal} has only the USG behavior, or give up on them.
655
 
656
@cindex impossible conditions
657
In error checks that detect ``impossible'' conditions, just abort.
658
There is usually no point in printing any message.  These checks
659
indicate the existence of bugs.  Whoever wants to fix the bugs will have
660
to read the source code and run a debugger.  So explain the problem with
661
comments in the source.  The relevant data will be in variables, which
662
are easy to examine with the debugger, so there is no point moving them
663
elsewhere.
664
 
665
Do not use a count of errors as the exit status for a program.
666
@emph{That does not work}, because exit status values are limited to 8
667
bits (0 through 255).  A single run of the program might have 256
668
errors; if you try to return 256 as the exit status, the parent process
669
will see 0 as the status, and it will appear that the program succeeded.
670
 
671
@cindex temporary files
672
@cindex @code{TMPDIR} environment variable
673
If you make temporary files, check the @code{TMPDIR} environment
674
variable; if that variable is defined, use the specified directory
675
instead of @file{/tmp}.
676
 
677
In addition, be aware that there is a possible security problem when
678
creating temporary files in world-writable directories.  In C, you can
679
avoid this problem by creating temporary files in this manner:
680
 
681
@example
682
fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
683
@end example
684
 
685
@noindent
686
or by using the @code{mkstemps} function from libiberty.
687
 
688
In bash, use @code{set -C} to avoid this problem.
689
 
690
@node Libraries
691
@section Library Behavior
692
@cindex libraries
693
 
694
Try to make library functions reentrant.  If they need to do dynamic
695
storage allocation, at least try to avoid any nonreentrancy aside from
696
that of @code{malloc} itself.
697
 
698
Here are certain name conventions for libraries, to avoid name
699
conflicts.
700
 
701
Choose a name prefix for the library, more than two characters long.
702
All external function and variable names should start with this
703
prefix.  In addition, there should only be one of these in any given
704
library member.  This usually means putting each one in a separate
705
source file.
706
 
707
An exception can be made when two external symbols are always used
708
together, so that no reasonable program could use one without the
709
other; then they can both go in the same file.
710
 
711
External symbols that are not documented entry points for the user
712
should have names beginning with @samp{_}.  The @samp{_} should be
713
followed by the chosen name prefix for the library, to prevent
714
collisions with other libraries.  These can go in the same files with
715
user entry points if you like.
716
 
717
Static functions and variables can be used as you like and need not
718
fit any naming convention.
719
 
720
@node Errors
721
@section Formatting Error Messages
722
@cindex formatting error messages
723
@cindex error messages, formatting
724
 
725
Error messages from compilers should look like this:
726
 
727
@example
728
@var{source-file-name}:@var{lineno}: @var{message}
729
@end example
730
 
731
@noindent
732
If you want to mention the column number, use one of these formats:
733
 
734
@example
735
@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
736
@var{source-file-name}:@var{lineno}.@var{column}: @var{message}
737
 
738
@end example
739
 
740
@noindent
741
Line numbers should start from 1 at the beginning of the file, and
742
column numbers should start from 1 at the beginning of the line.  (Both
743
of these conventions are chosen for compatibility.)  Calculate column
744
numbers assuming that space and all ASCII printing characters have
745
equal width, and assuming tab stops every 8 columns.
746
 
747
The error message can also give both the starting and ending positions
748
of the erroneous text.  There are several formats so that you can
749
avoid redundant information such as a duplicate line number.
750
Here are the possible formats:
751
 
752
@example
753
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
754
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
755
@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
756
@end example
757
 
758
@noindent
759
When an error is spread over several files, you can use this format:
760
 
761
@example
762
@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
763
@end example
764
 
765
Error messages from other noninteractive programs should look like this:
766
 
767
@example
768
@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
769
@end example
770
 
771
@noindent
772
when there is an appropriate source file, or like this:
773
 
774
@example
775
@var{program}: @var{message}
776
@end example
777
 
778
@noindent
779
when there is no relevant source file.
780
 
781
If you want to mention the column number, use this format:
782
 
783
@example
784
@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
785
@end example
786
 
787
In an interactive program (one that is reading commands from a
788
terminal), it is better not to include the program name in an error
789
message.  The place to indicate which program is running is in the
790
prompt or with the screen layout.  (When the same program runs with
791
input from a source other than a terminal, it is not interactive and
792
would do best to print error messages using the noninteractive style.)
793
 
794
The string @var{message} should not begin with a capital letter when
795
it follows a program name and/or file name, because that isn't the
796
beginning of a sentence.  (The sentence conceptually starts at the
797
beginning of the line.)  Also, it should not end with a period.
798
 
799
Error messages from interactive programs, and other messages such as
800
usage messages, should start with a capital letter.  But they should not
801
end with a period.
802
 
803
@node User Interfaces
804
@section Standards for Interfaces Generally
805
 
806
@cindex program name and its behavior
807
@cindex behavior, dependent on program's name
808
Please don't make the behavior of a utility depend on the name used
809
to invoke it.  It is useful sometimes to make a link to a utility
810
with a different name, and that should not change what it does.
811
 
812
Instead, use a run time option or a compilation switch or both
813
to select among the alternate behaviors.
814
 
815
@cindex output device and program's behavior
816
Likewise, please don't make the behavior of the program depend on the
817
type of output device it is used with.  Device independence is an
818
important principle of the system's design; do not compromise it merely
819
to save someone from typing an option now and then.  (Variation in error
820
message syntax when using a terminal is ok, because that is a side issue
821
that people do not depend on.)
822
 
823
If you think one behavior is most useful when the output is to a
824
terminal, and another is most useful when the output is a file or a
825
pipe, then it is usually best to make the default behavior the one that
826
is useful with output to a terminal, and have an option for the other
827
behavior.
828
 
829
Compatibility requires certain programs to depend on the type of output
830
device.  It would be disastrous if @code{ls} or @code{sh} did not do so
831
in the way all users expect.  In some of these cases, we supplement the
832
program with a preferred alternate version that does not depend on the
833
output device type.  For example, we provide a @code{dir} program much
834
like @code{ls} except that its default output format is always
835
multi-column format.
836
 
837
 
838
@node Graphical Interfaces
839
@section Standards for Graphical Interfaces
840
@cindex graphical user interface
841
 
842
@cindex gtk+
843
When you write a program that provides a graphical user interface,
844
please make it work with X Windows and the GTK+ toolkit unless the
845
functionality specifically requires some alternative (for example,
846
``displaying jpeg images while in console mode'').
847
 
848
In addition, please provide a command-line interface to control the
849
functionality.  (In many cases, the graphical user interface can be a
850
separate program which invokes the command-line program.)  This is
851
so that the same jobs can be done from scripts.
852
 
853
@cindex corba
854
@cindex gnome
855
Please also consider providing a CORBA interface (for use from GNOME), a
856
library interface (for use from C), and perhaps a keyboard-driven
857
console interface (for use by users from console mode).  Once you are
858
doing the work to provide the functionality and the graphical interface,
859
these won't be much extra work.
860
 
861
 
862
@node Command-Line Interfaces
863
@section Standards for Command Line Interfaces
864
@cindex command-line interface
865
 
866
@findex getopt
867
It is a good idea to follow the @sc{posix} guidelines for the
868
command-line options of a program.  The easiest way to do this is to use
869
@code{getopt} to parse them.  Note that the GNU version of @code{getopt}
870
will normally permit options anywhere among the arguments unless the
871
special argument @samp{--} is used.  This is not what @sc{posix}
872
specifies; it is a GNU extension.
873
 
874
@cindex long-named options
875
Please define long-named options that are equivalent to the
876
single-letter Unix-style options.  We hope to make GNU more user
877
friendly this way.  This is easy to do with the GNU function
878
@code{getopt_long}.
879
 
880
One of the advantages of long-named options is that they can be
881
consistent from program to program.  For example, users should be able
882
to expect the ``verbose'' option of any GNU program which has one, to be
883
spelled precisely @samp{--verbose}.  To achieve this uniformity, look at
884
the table of common long-option names when you choose the option names
885
for your program (@pxref{Option Table}).
886
 
887
It is usually a good idea for file names given as ordinary arguments to
888
be input files only; any output files would be specified using options
889
(preferably @samp{-o} or @samp{--output}).  Even if you allow an output
890
file name as an ordinary argument for compatibility, try to provide an
891
option as another way to specify it.  This will lead to more consistency
892
among GNU utilities, and fewer idiosyncrasies for users to remember.
893
 
894
@cindex standard command-line options
895
@cindex options, standard command-line
896
@cindex CGI programs, standard options for
897
@cindex PATH_INFO, specifying standard options as
898
All programs should support two standard options: @samp{--version}
899
and @samp{--help}.  CGI programs should accept these as command-line
900
options, and also if given as the @env{PATH_INFO}; for instance,
901
visiting @url{http://example.org/p.cgi/--help} in a browser should
902
output the same information as invoking @samp{p.cgi --help} from the
903
command line.
904
 
905
@menu
906
* --version::       The standard output for --version.
907
* --help::          The standard output for --help.
908
@end menu
909
 
910
@node --version
911
@subsection @option{--version}
912
 
913
@cindex @samp{--version} output
914
 
915
The standard @code{--version} option should direct the program to
916
print information about its name, version, origin and legal status,
917
all on standard output, and then exit successfully.  Other options and
918
arguments should be ignored once this is seen, and the program should
919
not perform its normal function.
920
 
921
@cindex canonical name of a program
922
@cindex program's canonical name
923
The first line is meant to be easy for a program to parse; the version
924
number proper starts after the last space.  In addition, it contains
925
the canonical name for this program, in this format:
926
 
927
@example
928
GNU Emacs 19.30
929
@end example
930
 
931
@noindent
932
The program's name should be a constant string; @emph{don't} compute it
933
from @code{argv[0]}.  The idea is to state the standard or canonical
934
name for the program, not its file name.  There are other ways to find
935
out the precise file name where a command is found in @code{PATH}.
936
 
937
If the program is a subsidiary part of a larger package, mention the
938
package name in parentheses, like this:
939
 
940
@example
941
emacsserver (GNU Emacs) 19.30
942
@end example
943
 
944
@noindent
945
If the package has a version number which is different from this
946
program's version number, you can mention the package version number
947
just before the close-parenthesis.
948
 
949
If you @emph{need} to mention the version numbers of libraries which
950
are distributed separately from the package which contains this program,
951
you can do so by printing an additional line of version info for each
952
library you want to mention.  Use the same format for these lines as for
953
the first line.
954
 
955
Please do not mention all of the libraries that the program uses ``just
956
for completeness''---that would produce a lot of unhelpful clutter.
957
Please mention library version numbers only if you find in practice that
958
they are very important to you in debugging.
959
 
960
The following line, after the version number line or lines, should be a
961
copyright notice.  If more than one copyright notice is called for, put
962
each on a separate line.
963
 
964
Next should follow a line stating the license, preferably using one of
965
abbrevations below, and a brief statement that the program is free
966
software, and that users are free to copy and change it.  Also mention
967
that there is no warranty, to the extent permitted by law.  See
968
recommended wording below.
969
 
970
It is ok to finish the output with a list of the major authors of the
971
program, as a way of giving credit.
972
 
973
Here's an example of output that follows these rules:
974
 
975
@smallexample
976
GNU hello 2.3
977
Copyright (C) 2007 Free Software Foundation, Inc.
978
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
979
This is free software: you are free to change and redistribute it.
980
There is NO WARRANTY, to the extent permitted by law.
981
@end smallexample
982
 
983
You should adapt this to your program, of course, filling in the proper
984
year, copyright holder, name of program, and the references to
985
distribution terms, and changing the rest of the wording as necessary.
986
 
987
This copyright notice only needs to mention the most recent year in
988
which changes were made---there's no need to list the years for previous
989
versions' changes.  You don't have to mention the name of the program in
990
these notices, if that is inconvenient, since it appeared in the first
991
line.  (The rules are different for copyright notices in source files;
992
@pxref{Copyright Notices,,,maintain,Information for GNU Maintainers}.)
993
 
994
Translations of the above lines must preserve the validity of the
995
copyright notices (@pxref{Internationalization}).  If the translation's
996
character set supports it, the @samp{(C)} should be replaced with the
997
copyright symbol, as follows:
998
 
999
@ifinfo
1000
(the official copyright symbol, which is the letter C in a circle);
1001
@end ifinfo
1002
@ifnotinfo
1003
@copyright{}
1004
@end ifnotinfo
1005
 
1006
Write the word ``Copyright'' exactly like that, in English.  Do not
1007
translate it into another language.  International treaties recognize
1008
the English word ``Copyright''; translations into other languages do not
1009
have legal significance.
1010
 
1011
Finally, here is the table of our suggested license abbreviations.
1012
Any abbreviation can be followed by @samp{v@var{version}[+]}, meaning
1013
that particular version, or later versions with the @samp{+}, as shown
1014
above.
1015
 
1016
In the case of exceptions for extra permissions with the GPL, we use
1017
@samp{/} for a separator; the version number can follow the license
1018
abbreviation as usual, as in the examples below.
1019
 
1020
@table @asis
1021
@item GPL
1022
GNU General Public License, @url{http://www.gnu.org/licenses/gpl.html}.
1023
 
1024
@item LGPL
1025
GNU Lesser General Public License, @url{http://www.gnu.org/licenses/lgpl.html}.
1026
 
1027
@item GPL/Guile
1028
GNU GPL with the exception for Guile; for example, GPLv3+/Guile means
1029
the GNU GPL version 3 or later, with the extra exception for Guile.
1030
 
1031
GNU GPL with the exception for Ada.
1032
 
1033
@item Apache
1034
The Apache Software Foundation license,
1035
@url{http://www.apache.org/licenses}.
1036
 
1037
@item Artistic
1038
The Artistic license used for Perl, @url{http://www.perlfoundation.org/legal}.
1039
 
1040
@item Expat
1041
The Expat license, @url{http://www.jclark.com/xml/copying.txt}.
1042
 
1043
@item MPL
1044
The Mozilla Public License, @url{http://www.mozilla.org/MPL/}.
1045
 
1046
@item OBSD
1047
The original (4-clause) BSD license, incompatible with the GNU GPL
1048
@url{http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6}.
1049
 
1050
@item PHP
1051
The license used for PHP, @url{http://www.php.net/license/}.
1052
 
1053
@item public domain
1054
The non-license that is being in the public domain,
1055
@url{http://www.gnu.org/licenses/license-list.html#PublicDomain}.
1056
 
1057
@item Python
1058
The license for Python, @url{http://www.python.org/2.0.1/license.html}.
1059
 
1060
@item RBSD
1061
The revised (3-clause) BSD, compatible with the GNU GPL,
1062
@url{http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5}.
1063
 
1064
@item X11
1065
The simple non-copyleft license used for most versions of the X Window
1066
system, @url{http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3}.
1067
 
1068
@item Zlib
1069
The license for Zlib, @url{http://www.gzip.org/zlib/zlib_license.html}.
1070
 
1071
@end table
1072
 
1073
More information about these licenses and many more are on the GNU
1074
licensing web pages,
1075
@url{http://www.gnu.org/licenses/license-list.html}.
1076
 
1077
 
1078
@node --help
1079
@subsection @option{--help}
1080
 
1081
@cindex @samp{--help} output
1082
 
1083
The standard @code{--help} option should output brief documentation
1084
for how to invoke the program, on standard output, then exit
1085
successfully.  Other options and arguments should be ignored once this
1086
is seen, and the program should not perform its normal function.
1087
 
1088
@cindex address for bug reports
1089
@cindex bug reports
1090
Near the end of the @samp{--help} option's output there should be a line
1091
that says where to mail bug reports.  It should have this format:
1092
 
1093
@example
1094
Report bugs to @var{mailing-address}.
1095
@end example
1096
 
1097
 
1098
@node Option Table
1099
@section Table of Long Options
1100
@cindex long option names
1101
@cindex table of long options
1102
 
1103
Here is a table of long options used by GNU programs.  It is surely
1104
incomplete, but we aim to list all the options that a new program might
1105
want to be compatible with.  If you use names not already in the table,
1106
please send @email{bug-standards@@gnu.org} a list of them, with their
1107
meanings, so we can update the table.
1108
 
1109
@c Please leave newlines between items in this table; it's much easier
1110
@c to update when it isn't completely squashed together and unreadable.
1111
@c When there is more than one short option for a long option name, put
1112
@c a semicolon between the lists of the programs that use them, not a
1113
@c period.   --friedman
1114
 
1115
@table @samp
1116
@item after-date
1117
@samp{-N} in @code{tar}.
1118
 
1119
@item all
1120
@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
1121
and @code{unexpand}.
1122
 
1123
@item all-text
1124
@samp{-a} in @code{diff}.
1125
 
1126
@item almost-all
1127
@samp{-A} in @code{ls}.
1128
 
1129
@item append
1130
@samp{-a} in @code{etags}, @code{tee}, @code{time};
1131
@samp{-r} in @code{tar}.
1132
 
1133
@item archive
1134
@samp{-a} in @code{cp}.
1135
 
1136
@item archive-name
1137
@samp{-n} in @code{shar}.
1138
 
1139
@item arglength
1140
@samp{-l} in @code{m4}.
1141
 
1142
@item ascii
1143
@samp{-a} in @code{diff}.
1144
 
1145
@item assign
1146
@samp{-v} in @code{gawk}.
1147
 
1148
@item assume-new
1149
@samp{-W} in Make.
1150
 
1151
@item assume-old
1152
@samp{-o} in Make.
1153
 
1154
@item auto-check
1155
@samp{-a} in @code{recode}.
1156
 
1157
@item auto-pager
1158
@samp{-a} in @code{wdiff}.
1159
 
1160
@item auto-reference
1161
@samp{-A} in @code{ptx}.
1162
 
1163
@item avoid-wraps
1164
@samp{-n} in @code{wdiff}.
1165
 
1166
@item background
1167
For server programs, run in the background.
1168
 
1169
@item backward-search
1170
@samp{-B} in @code{ctags}.
1171
 
1172
@item basename
1173
@samp{-f} in @code{shar}.
1174
 
1175
@item batch
1176
Used in GDB.
1177
 
1178
@item baud
1179
Used in GDB.
1180
 
1181
@item before
1182
@samp{-b} in @code{tac}.
1183
 
1184
@item binary
1185
@samp{-b} in @code{cpio} and @code{diff}.
1186
 
1187
@item bits-per-code
1188
@samp{-b} in @code{shar}.
1189
 
1190
@item block-size
1191
Used in @code{cpio} and @code{tar}.
1192
 
1193
@item blocks
1194
@samp{-b} in @code{head} and @code{tail}.
1195
 
1196
@item break-file
1197
@samp{-b} in @code{ptx}.
1198
 
1199
@item brief
1200
Used in various programs to make output shorter.
1201
 
1202
@item bytes
1203
@samp{-c} in @code{head}, @code{split}, and @code{tail}.
1204
 
1205
@item c@t{++}
1206
@samp{-C} in @code{etags}.
1207
 
1208
@item catenate
1209
@samp{-A} in @code{tar}.
1210
 
1211
@item cd
1212
Used in various programs to specify the directory to use.
1213
 
1214
@item changes
1215
@samp{-c} in @code{chgrp} and @code{chown}.
1216
 
1217
@item classify
1218
@samp{-F} in @code{ls}.
1219
 
1220
@item colons
1221
@samp{-c} in @code{recode}.
1222
 
1223
@item command
1224
@samp{-c} in @code{su};
1225
@samp{-x} in GDB.
1226
 
1227
@item compare
1228
@samp{-d} in @code{tar}.
1229
 
1230
@item compat
1231
Used in @code{gawk}.
1232
 
1233
@item compress
1234
@samp{-Z} in @code{tar} and @code{shar}.
1235
 
1236
@item concatenate
1237
@samp{-A} in @code{tar}.
1238
 
1239
@item confirmation
1240
@samp{-w} in @code{tar}.
1241
 
1242
@item context
1243
Used in @code{diff}.
1244
 
1245
@item copyleft
1246
@samp{-W copyleft} in @code{gawk}.
1247
 
1248
@item copyright
1249
@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
1250
@samp{-W copyright} in @code{gawk}.
1251
 
1252
@item core
1253
Used in GDB.
1254
 
1255
@item count
1256
@samp{-q} in @code{who}.
1257
 
1258
@item count-links
1259
@samp{-l} in @code{du}.
1260
 
1261
@item create
1262
Used in @code{tar} and @code{cpio}.
1263
 
1264
@item cut-mark
1265
@samp{-c} in @code{shar}.
1266
 
1267
@item cxref
1268
@samp{-x} in @code{ctags}.
1269
 
1270
@item date
1271
@samp{-d} in @code{touch}.
1272
 
1273
@item debug
1274
@samp{-d} in Make and @code{m4};
1275
@samp{-t} in Bison.
1276
 
1277
@item define
1278
@samp{-D} in @code{m4}.
1279
 
1280
@item defines
1281
@samp{-d} in Bison and @code{ctags}.
1282
 
1283
@item delete
1284
@samp{-D} in @code{tar}.
1285
 
1286
@item dereference
1287
@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
1288
@code{ls}, and @code{tar}.
1289
 
1290
@item dereference-args
1291
@samp{-D} in @code{du}.
1292
 
1293
@item device
1294
Specify an I/O device (special file name).
1295
 
1296
@item diacritics
1297
@samp{-d} in @code{recode}.
1298
 
1299
@item dictionary-order
1300
@samp{-d} in @code{look}.
1301
 
1302
@item diff
1303
@samp{-d} in @code{tar}.
1304
 
1305
@item digits
1306
@samp{-n} in @code{csplit}.
1307
 
1308
@item directory
1309
Specify the directory to use, in various programs.  In @code{ls}, it
1310
means to show directories themselves rather than their contents.  In
1311
@code{rm} and @code{ln}, it means to not treat links to directories
1312
specially.
1313
 
1314
@item discard-all
1315
@samp{-x} in @code{strip}.
1316
 
1317
@item discard-locals
1318
@samp{-X} in @code{strip}.
1319
 
1320
@item dry-run
1321
@samp{-n} in Make.
1322
 
1323
@item ed
1324
@samp{-e} in @code{diff}.
1325
 
1326
@item elide-empty-files
1327
@samp{-z} in @code{csplit}.
1328
 
1329
@item end-delete
1330
@samp{-x} in @code{wdiff}.
1331
 
1332
@item end-insert
1333
@samp{-z} in @code{wdiff}.
1334
 
1335
@item entire-new-file
1336
@samp{-N} in @code{diff}.
1337
 
1338
@item environment-overrides
1339
@samp{-e} in Make.
1340
 
1341
@item eof
1342
@samp{-e} in @code{xargs}.
1343
 
1344
@item epoch
1345
Used in GDB.
1346
 
1347
@item error-limit
1348
Used in @code{makeinfo}.
1349
 
1350
@item error-output
1351
@samp{-o} in @code{m4}.
1352
 
1353
@item escape
1354
@samp{-b} in @code{ls}.
1355
 
1356
@item exclude-from
1357
@samp{-X} in @code{tar}.
1358
 
1359
@item exec
1360
Used in GDB.
1361
 
1362
@item exit
1363
@samp{-x} in @code{xargs}.
1364
 
1365
@item exit-0
1366
@samp{-e} in @code{unshar}.
1367
 
1368
@item expand-tabs
1369
@samp{-t} in @code{diff}.
1370
 
1371
@item expression
1372
@samp{-e} in @code{sed}.
1373
 
1374
@item extern-only
1375
@samp{-g} in @code{nm}.
1376
 
1377
@item extract
1378
@samp{-i} in @code{cpio};
1379
@samp{-x} in @code{tar}.
1380
 
1381
@item faces
1382
@samp{-f} in @code{finger}.
1383
 
1384
@item fast
1385
@samp{-f} in @code{su}.
1386
 
1387
@item fatal-warnings
1388
@samp{-E} in @code{m4}.
1389
 
1390
@item file
1391
@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};
1392
@samp{-n} in @code{sed};
1393
@samp{-r} in @code{touch}.
1394
 
1395
@item field-separator
1396
@samp{-F} in @code{gawk}.
1397
 
1398
@item file-prefix
1399
@samp{-b} in Bison.
1400
 
1401
@item file-type
1402
@samp{-F} in @code{ls}.
1403
 
1404
@item files-from
1405
@samp{-T} in @code{tar}.
1406
 
1407
@item fill-column
1408
Used in @code{makeinfo}.
1409
 
1410
@item flag-truncation
1411
@samp{-F} in @code{ptx}.
1412
 
1413
@item fixed-output-files
1414
@samp{-y} in Bison.
1415
 
1416
@item follow
1417
@samp{-f} in @code{tail}.
1418
 
1419
@item footnote-style
1420
Used in @code{makeinfo}.
1421
 
1422
@item force
1423
@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
1424
 
1425
@item force-prefix
1426
@samp{-F} in @code{shar}.
1427
 
1428
@item foreground
1429
For server programs, run in the foreground;
1430
in other words, don't do anything special to run the server
1431
in the background.
1432
 
1433
@item format
1434
Used in @code{ls}, @code{time}, and @code{ptx}.
1435
 
1436
@item freeze-state
1437
@samp{-F} in @code{m4}.
1438
 
1439
@item fullname
1440
Used in GDB.
1441
 
1442
@item gap-size
1443
@samp{-g} in @code{ptx}.
1444
 
1445
@item get
1446
@samp{-x} in @code{tar}.
1447
 
1448
@item graphic
1449
@samp{-i} in @code{ul}.
1450
 
1451
@item graphics
1452
@samp{-g} in @code{recode}.
1453
 
1454
@item group
1455
@samp{-g} in @code{install}.
1456
 
1457
@item gzip
1458
@samp{-z} in @code{tar} and @code{shar}.
1459
 
1460
@item hashsize
1461
@samp{-H} in @code{m4}.
1462
 
1463
@item header
1464
@samp{-h} in @code{objdump} and @code{recode}
1465
 
1466
@item heading
1467
@samp{-H} in @code{who}.
1468
 
1469
@item help
1470
Used to ask for brief usage information.
1471
 
1472
@item here-delimiter
1473
@samp{-d} in @code{shar}.
1474
 
1475
@item hide-control-chars
1476
@samp{-q} in @code{ls}.
1477
 
1478
@item html
1479
In @code{makeinfo}, output HTML.
1480
 
1481
@item idle
1482
@samp{-u} in @code{who}.
1483
 
1484
@item ifdef
1485
@samp{-D} in @code{diff}.
1486
 
1487
@item ignore
1488
@samp{-I} in @code{ls};
1489
@samp{-x} in @code{recode}.
1490
 
1491
@item ignore-all-space
1492
@samp{-w} in @code{diff}.
1493
 
1494
@item ignore-backups
1495
@samp{-B} in @code{ls}.
1496
 
1497
@item ignore-blank-lines
1498
@samp{-B} in @code{diff}.
1499
 
1500
@item ignore-case
1501
@samp{-f} in @code{look} and @code{ptx};
1502
@samp{-i} in @code{diff} and @code{wdiff}.
1503
 
1504
@item ignore-errors
1505
@samp{-i} in Make.
1506
 
1507
@item ignore-file
1508
@samp{-i} in @code{ptx}.
1509
 
1510
@item ignore-indentation
1511
@samp{-I} in @code{etags}.
1512
 
1513
@item ignore-init-file
1514
@samp{-f} in Oleo.
1515
 
1516
@item ignore-interrupts
1517
@samp{-i} in @code{tee}.
1518
 
1519
@item ignore-matching-lines
1520
@samp{-I} in @code{diff}.
1521
 
1522
@item ignore-space-change
1523
@samp{-b} in @code{diff}.
1524
 
1525
@item ignore-zeros
1526
@samp{-i} in @code{tar}.
1527
 
1528
@item include
1529
@samp{-i} in @code{etags};
1530
@samp{-I} in @code{m4}.
1531
 
1532
@item include-dir
1533
@samp{-I} in Make.
1534
 
1535
@item incremental
1536
@samp{-G} in @code{tar}.
1537
 
1538
@item info
1539
@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
1540
 
1541
@item init-file
1542
In some programs, specify the name of the file to read as the user's
1543
init file.
1544
 
1545
@item initial
1546
@samp{-i} in @code{expand}.
1547
 
1548
@item initial-tab
1549
@samp{-T} in @code{diff}.
1550
 
1551
@item inode
1552
@samp{-i} in @code{ls}.
1553
 
1554
@item interactive
1555
@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
1556
@samp{-e} in @code{m4};
1557
@samp{-p} in @code{xargs};
1558
@samp{-w} in @code{tar}.
1559
 
1560
@item intermix-type
1561
@samp{-p} in @code{shar}.
1562
 
1563
@item iso-8601
1564
Used in @code{date}
1565
 
1566
@item jobs
1567
@samp{-j} in Make.
1568
 
1569
@item just-print
1570
@samp{-n} in Make.
1571
 
1572
@item keep-going
1573
@samp{-k} in Make.
1574
 
1575
@item keep-files
1576
@samp{-k} in @code{csplit}.
1577
 
1578
@item kilobytes
1579
@samp{-k} in @code{du} and @code{ls}.
1580
 
1581
@item language
1582
@samp{-l} in @code{etags}.
1583
 
1584
@item less-mode
1585
@samp{-l} in @code{wdiff}.
1586
 
1587
@item level-for-gzip
1588
@samp{-g} in @code{shar}.
1589
 
1590
@item line-bytes
1591
@samp{-C} in @code{split}.
1592
 
1593
@item lines
1594
Used in @code{split}, @code{head}, and @code{tail}.
1595
 
1596
@item link
1597
@samp{-l} in @code{cpio}.
1598
 
1599
@item lint
1600
@itemx lint-old
1601
Used in @code{gawk}.
1602
 
1603
@item list
1604
@samp{-t} in @code{cpio};
1605
@samp{-l} in @code{recode}.
1606
 
1607
@item list
1608
@samp{-t} in @code{tar}.
1609
 
1610
@item literal
1611
@samp{-N} in @code{ls}.
1612
 
1613
@item load-average
1614
@samp{-l} in Make.
1615
 
1616
@item login
1617
Used in @code{su}.
1618
 
1619
@item machine
1620
Used in @code{uname}.
1621
 
1622
@item macro-name
1623
@samp{-M} in @code{ptx}.
1624
 
1625
@item mail
1626
@samp{-m} in @code{hello} and @code{uname}.
1627
 
1628
@item make-directories
1629
@samp{-d} in @code{cpio}.
1630
 
1631
@item makefile
1632
@samp{-f} in Make.
1633
 
1634
@item mapped
1635
Used in GDB.
1636
 
1637
@item max-args
1638
@samp{-n} in @code{xargs}.
1639
 
1640
@item max-chars
1641
@samp{-n} in @code{xargs}.
1642
 
1643
@item max-lines
1644
@samp{-l} in @code{xargs}.
1645
 
1646
@item max-load
1647
@samp{-l} in Make.
1648
 
1649
@item max-procs
1650
@samp{-P} in @code{xargs}.
1651
 
1652
@item mesg
1653
@samp{-T} in @code{who}.
1654
 
1655
@item message
1656
@samp{-T} in @code{who}.
1657
 
1658
@item minimal
1659
@samp{-d} in @code{diff}.
1660
 
1661
@item mixed-uuencode
1662
@samp{-M} in @code{shar}.
1663
 
1664
@item mode
1665
@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
1666
 
1667
@item modification-time
1668
@samp{-m} in @code{tar}.
1669
 
1670
@item multi-volume
1671
@samp{-M} in @code{tar}.
1672
 
1673
@item name-prefix
1674
@samp{-a} in Bison.
1675
 
1676
@item nesting-limit
1677
@samp{-L} in @code{m4}.
1678
 
1679
@item net-headers
1680
@samp{-a} in @code{shar}.
1681
 
1682
@item new-file
1683
@samp{-W} in Make.
1684
 
1685
@item no-builtin-rules
1686
@samp{-r} in Make.
1687
 
1688
@item no-character-count
1689
@samp{-w} in @code{shar}.
1690
 
1691
@item no-check-existing
1692
@samp{-x} in @code{shar}.
1693
 
1694
@item no-common
1695
@samp{-3} in @code{wdiff}.
1696
 
1697
@item no-create
1698
@samp{-c} in @code{touch}.
1699
 
1700
@item no-defines
1701
@samp{-D} in @code{etags}.
1702
 
1703
@item no-deleted
1704
@samp{-1} in @code{wdiff}.
1705
 
1706
@item no-dereference
1707
@samp{-d} in @code{cp}.
1708
 
1709
@item no-inserted
1710
@samp{-2} in @code{wdiff}.
1711
 
1712
@item no-keep-going
1713
@samp{-S} in Make.
1714
 
1715
@item no-lines
1716
@samp{-l} in Bison.
1717
 
1718
@item no-piping
1719
@samp{-P} in @code{shar}.
1720
 
1721
@item no-prof
1722
@samp{-e} in @code{gprof}.
1723
 
1724
@item no-regex
1725
@samp{-R} in @code{etags}.
1726
 
1727
@item no-sort
1728
@samp{-p} in @code{nm}.
1729
 
1730
@item no-splash
1731
Don't print a startup splash screen.
1732
 
1733
@item no-split
1734
Used in @code{makeinfo}.
1735
 
1736
@item no-static
1737
@samp{-a} in @code{gprof}.
1738
 
1739
@item no-time
1740
@samp{-E} in @code{gprof}.
1741
 
1742
@item no-timestamp
1743
@samp{-m} in @code{shar}.
1744
 
1745
@item no-validate
1746
Used in @code{makeinfo}.
1747
 
1748
@item no-wait
1749
Used in @code{emacsclient}.
1750
 
1751
@item no-warn
1752
Used in various programs to inhibit warnings.
1753
 
1754
@item node
1755
@samp{-n} in @code{info}.
1756
 
1757
@item nodename
1758
@samp{-n} in @code{uname}.
1759
 
1760
@item nonmatching
1761
@samp{-f} in @code{cpio}.
1762
 
1763
@item nstuff
1764
@samp{-n} in @code{objdump}.
1765
 
1766
@item null
1767
@samp{-0} in @code{xargs}.
1768
 
1769
@item number
1770
@samp{-n} in @code{cat}.
1771
 
1772
@item number-nonblank
1773
@samp{-b} in @code{cat}.
1774
 
1775
@item numeric-sort
1776
@samp{-n} in @code{nm}.
1777
 
1778
@item numeric-uid-gid
1779
@samp{-n} in @code{cpio} and @code{ls}.
1780
 
1781
@item nx
1782
Used in GDB.
1783
 
1784
@item old-archive
1785
@samp{-o} in @code{tar}.
1786
 
1787
@item old-file
1788
@samp{-o} in Make.
1789
 
1790
@item one-file-system
1791
@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
1792
 
1793
@item only-file
1794
@samp{-o} in @code{ptx}.
1795
 
1796
@item only-prof
1797
@samp{-f} in @code{gprof}.
1798
 
1799
@item only-time
1800
@samp{-F} in @code{gprof}.
1801
 
1802
@item options
1803
@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
1804
@code{fdmountd}, and @code{fdumount}.
1805
 
1806
@item output
1807
In various programs, specify the output file name.
1808
 
1809
@item output-prefix
1810
@samp{-o} in @code{shar}.
1811
 
1812
@item override
1813
@samp{-o} in @code{rm}.
1814
 
1815
@item overwrite
1816
@samp{-c} in @code{unshar}.
1817
 
1818
@item owner
1819
@samp{-o} in @code{install}.
1820
 
1821
@item paginate
1822
@samp{-l} in @code{diff}.
1823
 
1824
@item paragraph-indent
1825
Used in @code{makeinfo}.
1826
 
1827
@item parents
1828
@samp{-p} in @code{mkdir} and @code{rmdir}.
1829
 
1830
@item pass-all
1831
@samp{-p} in @code{ul}.
1832
 
1833
@item pass-through
1834
@samp{-p} in @code{cpio}.
1835
 
1836
@item port
1837
@samp{-P} in @code{finger}.
1838
 
1839
@item portability
1840
@samp{-c} in @code{cpio} and @code{tar}.
1841
 
1842
@item posix
1843
Used in @code{gawk}.
1844
 
1845
@item prefix-builtins
1846
@samp{-P} in @code{m4}.
1847
 
1848
@item prefix
1849
@samp{-f} in @code{csplit}.
1850
 
1851
@item preserve
1852
Used in @code{tar} and @code{cp}.
1853
 
1854
@item preserve-environment
1855
@samp{-p} in @code{su}.
1856
 
1857
@item preserve-modification-time
1858
@samp{-m} in @code{cpio}.
1859
 
1860
@item preserve-order
1861
@samp{-s} in @code{tar}.
1862
 
1863
@item preserve-permissions
1864
@samp{-p} in @code{tar}.
1865
 
1866
@item print
1867
@samp{-l} in @code{diff}.
1868
 
1869
@item print-chars
1870
@samp{-L} in @code{cmp}.
1871
 
1872
@item print-data-base
1873
@samp{-p} in Make.
1874
 
1875
@item print-directory
1876
@samp{-w} in Make.
1877
 
1878
@item print-file-name
1879
@samp{-o} in @code{nm}.
1880
 
1881
@item print-symdefs
1882
@samp{-s} in @code{nm}.
1883
 
1884
@item printer
1885
@samp{-p} in @code{wdiff}.
1886
 
1887
@item prompt
1888
@samp{-p} in @code{ed}.
1889
 
1890
@item proxy
1891
Specify an HTTP proxy.
1892
 
1893
@item query-user
1894
@samp{-X} in @code{shar}.
1895
 
1896
@item question
1897
@samp{-q} in Make.
1898
 
1899
@item quiet
1900
Used in many programs to inhibit the usual output.  Every
1901
program accepting @samp{--quiet} should accept @samp{--silent} as a
1902
synonym.
1903
 
1904
@item quiet-unshar
1905
@samp{-Q} in @code{shar}
1906
 
1907
@item quote-name
1908
@samp{-Q} in @code{ls}.
1909
 
1910
@item rcs
1911
@samp{-n} in @code{diff}.
1912
 
1913
@item re-interval
1914
Used in @code{gawk}.
1915
 
1916
@item read-full-blocks
1917
@samp{-B} in @code{tar}.
1918
 
1919
@item readnow
1920
Used in GDB.
1921
 
1922
@item recon
1923
@samp{-n} in Make.
1924
 
1925
@item record-number
1926
@samp{-R} in @code{tar}.
1927
 
1928
@item recursive
1929
Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
1930
and @code{rm}.
1931
 
1932
@item reference-limit
1933
Used in @code{makeinfo}.
1934
 
1935
@item references
1936
@samp{-r} in @code{ptx}.
1937
 
1938
@item regex
1939
@samp{-r} in @code{tac} and @code{etags}.
1940
 
1941
@item release
1942
@samp{-r} in @code{uname}.
1943
 
1944
@item reload-state
1945
@samp{-R} in @code{m4}.
1946
 
1947
@item relocation
1948
@samp{-r} in @code{objdump}.
1949
 
1950
@item rename
1951
@samp{-r} in @code{cpio}.
1952
 
1953
@item replace
1954
@samp{-i} in @code{xargs}.
1955
 
1956
@item report-identical-files
1957
@samp{-s} in @code{diff}.
1958
 
1959
@item reset-access-time
1960
@samp{-a} in @code{cpio}.
1961
 
1962
@item reverse
1963
@samp{-r} in @code{ls} and @code{nm}.
1964
 
1965
@item reversed-ed
1966
@samp{-f} in @code{diff}.
1967
 
1968
@item right-side-defs
1969
@samp{-R} in @code{ptx}.
1970
 
1971
@item same-order
1972
@samp{-s} in @code{tar}.
1973
 
1974
@item same-permissions
1975
@samp{-p} in @code{tar}.
1976
 
1977
@item save
1978
@samp{-g} in @code{stty}.
1979
 
1980
@item se
1981
Used in GDB.
1982
 
1983
@item sentence-regexp
1984
@samp{-S} in @code{ptx}.
1985
 
1986
@item separate-dirs
1987
@samp{-S} in @code{du}.
1988
 
1989
@item separator
1990
@samp{-s} in @code{tac}.
1991
 
1992
@item sequence
1993
Used by @code{recode} to chose files or pipes for sequencing passes.
1994
 
1995
@item shell
1996
@samp{-s} in @code{su}.
1997
 
1998
@item show-all
1999
@samp{-A} in @code{cat}.
2000
 
2001
@item show-c-function
2002
@samp{-p} in @code{diff}.
2003
 
2004
@item show-ends
2005
@samp{-E} in @code{cat}.
2006
 
2007
@item show-function-line
2008
@samp{-F} in @code{diff}.
2009
 
2010
@item show-tabs
2011
@samp{-T} in @code{cat}.
2012
 
2013
@item silent
2014
Used in many programs to inhibit the usual output.
2015
Every program accepting
2016
@samp{--silent} should accept @samp{--quiet} as a synonym.
2017
 
2018
@item size
2019
@samp{-s} in @code{ls}.
2020
 
2021
@item socket
2022
Specify a file descriptor for a network server to use for its socket,
2023
instead of opening and binding a new socket.  This provides a way to
2024
run, in a non-privileged process, a server that normally needs a
2025
reserved port number.
2026
 
2027
@item sort
2028
Used in @code{ls}.
2029
 
2030
@item source
2031
@samp{-W source} in @code{gawk}.
2032
 
2033
@item sparse
2034
@samp{-S} in @code{tar}.
2035
 
2036
@item speed-large-files
2037
@samp{-H} in @code{diff}.
2038
 
2039
@item split-at
2040
@samp{-E} in @code{unshar}.
2041
 
2042
@item split-size-limit
2043
@samp{-L} in @code{shar}.
2044
 
2045
@item squeeze-blank
2046
@samp{-s} in @code{cat}.
2047
 
2048
@item start-delete
2049
@samp{-w} in @code{wdiff}.
2050
 
2051
@item start-insert
2052
@samp{-y} in @code{wdiff}.
2053
 
2054
@item starting-file
2055
Used in @code{tar} and @code{diff} to specify which file within
2056
a directory to start processing with.
2057
 
2058
@item statistics
2059
@samp{-s} in @code{wdiff}.
2060
 
2061
@item stdin-file-list
2062
@samp{-S} in @code{shar}.
2063
 
2064
@item stop
2065
@samp{-S} in Make.
2066
 
2067
@item strict
2068
@samp{-s} in @code{recode}.
2069
 
2070
@item strip
2071
@samp{-s} in @code{install}.
2072
 
2073
@item strip-all
2074
@samp{-s} in @code{strip}.
2075
 
2076
@item strip-debug
2077
@samp{-S} in @code{strip}.
2078
 
2079
@item submitter
2080
@samp{-s} in @code{shar}.
2081
 
2082
@item suffix
2083
@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
2084
 
2085
@item suffix-format
2086
@samp{-b} in @code{csplit}.
2087
 
2088
@item sum
2089
@samp{-s} in @code{gprof}.
2090
 
2091
@item summarize
2092
@samp{-s} in @code{du}.
2093
 
2094
@item symbolic
2095
@samp{-s} in @code{ln}.
2096
 
2097
@item symbols
2098
Used in GDB and @code{objdump}.
2099
 
2100
@item synclines
2101
@samp{-s} in @code{m4}.
2102
 
2103
@item sysname
2104
@samp{-s} in @code{uname}.
2105
 
2106
@item tabs
2107
@samp{-t} in @code{expand} and @code{unexpand}.
2108
 
2109
@item tabsize
2110
@samp{-T} in @code{ls}.
2111
 
2112
@item terminal
2113
@samp{-T} in @code{tput} and @code{ul}.
2114
@samp{-t} in @code{wdiff}.
2115
 
2116
@item text
2117
@samp{-a} in @code{diff}.
2118
 
2119
@item text-files
2120
@samp{-T} in @code{shar}.
2121
 
2122
@item time
2123
Used in @code{ls} and @code{touch}.
2124
 
2125
@item timeout
2126
Specify how long to wait before giving up on some operation.
2127
 
2128
@item to-stdout
2129
@samp{-O} in @code{tar}.
2130
 
2131
@item total
2132
@samp{-c} in @code{du}.
2133
 
2134
@item touch
2135
@samp{-t} in Make, @code{ranlib}, and @code{recode}.
2136
 
2137
@item trace
2138
@samp{-t} in @code{m4}.
2139
 
2140
@item traditional
2141
@samp{-t} in @code{hello};
2142
@samp{-W traditional} in @code{gawk};
2143
@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
2144
 
2145
@item tty
2146
Used in GDB.
2147
 
2148
@item typedefs
2149
@samp{-t} in @code{ctags}.
2150
 
2151
@item typedefs-and-c++
2152
@samp{-T} in @code{ctags}.
2153
 
2154
@item typeset-mode
2155
@samp{-t} in @code{ptx}.
2156
 
2157
@item uncompress
2158
@samp{-z} in @code{tar}.
2159
 
2160
@item unconditional
2161
@samp{-u} in @code{cpio}.
2162
 
2163
@item undefine
2164
@samp{-U} in @code{m4}.
2165
 
2166
@item undefined-only
2167
@samp{-u} in @code{nm}.
2168
 
2169
@item update
2170
@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
2171
 
2172
@item usage
2173
Used in @code{gawk}; same as @samp{--help}.
2174
 
2175
@item uuencode
2176
@samp{-B} in @code{shar}.
2177
 
2178
@item vanilla-operation
2179
@samp{-V} in @code{shar}.
2180
 
2181
@item verbose
2182
Print more information about progress.  Many programs support this.
2183
 
2184
@item verify
2185
@samp{-W} in @code{tar}.
2186
 
2187
@item version
2188
Print the version number.
2189
 
2190
@item version-control
2191
@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
2192
 
2193
@item vgrind
2194
@samp{-v} in @code{ctags}.
2195
 
2196
@item volume
2197
@samp{-V} in @code{tar}.
2198
 
2199
@item what-if
2200
@samp{-W} in Make.
2201
 
2202
@item whole-size-limit
2203
@samp{-l} in @code{shar}.
2204
 
2205
@item width
2206
@samp{-w} in @code{ls} and @code{ptx}.
2207
 
2208
@item word-regexp
2209
@samp{-W} in @code{ptx}.
2210
 
2211
@item writable
2212
@samp{-T} in @code{who}.
2213
 
2214
@item zeros
2215
@samp{-z} in @code{gprof}.
2216
@end table
2217
 
2218
@node Memory Usage
2219
@section Memory Usage
2220
@cindex memory usage
2221
 
2222
If a program typically uses just a few meg of memory, don't bother making any
2223
effort to reduce memory usage.  For example, if it is impractical for
2224
other reasons to operate on files more than a few meg long, it is
2225
reasonable to read entire input files into memory to operate on them.
2226
 
2227
However, for programs such as @code{cat} or @code{tail}, that can
2228
usefully operate on very large files, it is important to avoid using a
2229
technique that would artificially limit the size of files it can handle.
2230
If a program works by lines and could be applied to arbitrary
2231
user-supplied input files, it should keep only a line in memory, because
2232
this is not very hard and users will want to be able to operate on input
2233
files that are bigger than will fit in memory all at once.
2234
 
2235
If your program creates complicated data structures, just make them in
2236
memory and give a fatal error if @code{malloc} returns zero.
2237
 
2238
@node File Usage
2239
@section File Usage
2240
@cindex file usage
2241
 
2242
Programs should be prepared to operate when @file{/usr} and @file{/etc}
2243
are read-only file systems.  Thus, if the program manages log files,
2244
lock files, backup files, score files, or any other files which are
2245
modified for internal purposes, these files should not be stored in
2246
@file{/usr} or @file{/etc}.
2247
 
2248
There are two exceptions.  @file{/etc} is used to store system
2249
configuration information; it is reasonable for a program to modify
2250
files in @file{/etc} when its job is to update the system configuration.
2251
Also, if the user explicitly asks to modify one file in a directory, it
2252
is reasonable for the program to store other files in the same
2253
directory.
2254
 
2255
@node Writing C
2256
@chapter Making The Best Use of C
2257
 
2258
This chapter provides advice on how best to use the C language
2259
when writing GNU software.
2260
 
2261
@menu
2262
* Formatting::                  Formatting your source code.
2263
* Comments::                    Commenting your work.
2264
* Syntactic Conventions::       Clean use of C constructs.
2265
* Names::                       Naming variables, functions, and files.
2266
* System Portability::          Portability among different operating systems.
2267
* CPU Portability::             Supporting the range of CPU types.
2268
* System Functions::            Portability and ``standard'' library functions.
2269
* Internationalization::        Techniques for internationalization.
2270
* Character Set::               Use ASCII by default.
2271
* Quote Characters::            Use `...' in the C locale.
2272
* Mmap::                        How you can safely use @code{mmap}.
2273
@end menu
2274
 
2275
@node Formatting
2276
@section Formatting Your Source Code
2277
@cindex formatting source code
2278
 
2279
@cindex open brace
2280
@cindex braces, in C source
2281
It is important to put the open-brace that starts the body of a C
2282
function in column one, so that they will start a defun.  Several
2283
tools look for open-braces in column one to find the beginnings of C
2284
functions.  These tools will not work on code not formatted that way.
2285
 
2286
Avoid putting open-brace, open-parenthesis or open-bracket in column
2287
one when they are inside a function, so that they won't start a defun.
2288
The open-brace that starts a @code{struct} body can go in column one
2289
if you find it useful to treat that definition as a defun.
2290
 
2291
It is also important for function definitions to start the name of the
2292
function in column one.  This helps people to search for function
2293
definitions, and may also help certain tools recognize them.  Thus,
2294
using Standard C syntax, the format is this:
2295
 
2296
@example
2297
static char *
2298
concat (char *s1, char *s2)
2299
@{
2300
  @dots{}
2301
@}
2302
@end example
2303
 
2304
@noindent
2305
or, if you want to use traditional C syntax, format the definition like
2306
this:
2307
 
2308
@example
2309
static char *
2310
concat (s1, s2)        /* Name starts in column one here */
2311
     char *s1, *s2;
2312
@{                     /* Open brace in column one here */
2313
  @dots{}
2314
@}
2315
@end example
2316
 
2317
In Standard C, if the arguments don't fit nicely on one line,
2318
split it like this:
2319
 
2320
@example
2321
int
2322
lots_of_args (int an_integer, long a_long, short a_short,
2323
              double a_double, float a_float)
2324
@dots{}
2325
@end example
2326
 
2327
The rest of this section gives our recommendations for other aspects of
2328
C formatting style, which is also the default style of the @code{indent}
2329
program in version 1.2 and newer.  It corresponds to the options
2330
 
2331
@smallexample
2332
-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
2333
-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
2334
@end smallexample
2335
 
2336
We don't think of these recommendations as requirements, because it
2337
causes no problems for users if two different programs have different
2338
formatting styles.
2339
 
2340
But whatever style you use, please use it consistently, since a mixture
2341
of styles within one program tends to look ugly.  If you are
2342
contributing changes to an existing program, please follow the style of
2343
that program.
2344
 
2345
For the body of the function, our recommended style looks like this:
2346
 
2347
@example
2348
if (x < foo (y, z))
2349
  haha = bar[4] + 5;
2350
else
2351
  @{
2352
    while (z)
2353
      @{
2354
        haha += foo (z, z);
2355
        z--;
2356
      @}
2357
    return ++x + bar ();
2358
  @}
2359
@end example
2360
 
2361
@cindex spaces before open-paren
2362
We find it easier to read a program when it has spaces before the
2363
open-parentheses and after the commas.  Especially after the commas.
2364
 
2365
When you split an expression into multiple lines, split it
2366
before an operator, not after one.  Here is the right way:
2367
 
2368
@cindex expressions, splitting
2369
@example
2370
if (foo_this_is_long && bar > win (x, y, z)
2371
    && remaining_condition)
2372
@end example
2373
 
2374
Try to avoid having two operators of different precedence at the same
2375
level of indentation.  For example, don't write this:
2376
 
2377
@example
2378
mode = (inmode[j] == VOIDmode
2379
        || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
2380
        ? outmode[j] : inmode[j]);
2381
@end example
2382
 
2383
Instead, use extra parentheses so that the indentation shows the nesting:
2384
 
2385
@example
2386
mode = ((inmode[j] == VOIDmode
2387
         || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
2388
        ? outmode[j] : inmode[j]);
2389
@end example
2390
 
2391
Insert extra parentheses so that Emacs will indent the code properly.
2392
For example, the following indentation looks nice if you do it by hand,
2393
 
2394
@example
2395
v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2396
    + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2397
@end example
2398
 
2399
@noindent
2400
but Emacs would alter it.  Adding a set of parentheses produces
2401
something that looks equally nice, and which Emacs will preserve:
2402
 
2403
@example
2404
v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2405
     + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2406
@end example
2407
 
2408
Format do-while statements like this:
2409
 
2410
@example
2411
do
2412
  @{
2413
    a = foo (a);
2414
  @}
2415
while (a > 0);
2416
@end example
2417
 
2418
@cindex formfeed
2419
@cindex control-L
2420
Please use formfeed characters (control-L) to divide the program into
2421
pages at logical places (but not within a function).  It does not matter
2422
just how long the pages are, since they do not have to fit on a printed
2423
page.  The formfeeds should appear alone on lines by themselves.
2424
 
2425
@node Comments
2426
@section Commenting Your Work
2427
@cindex commenting
2428
 
2429
Every program should start with a comment saying briefly what it is for.
2430
Example: @samp{fmt - filter for simple filling of text}.  This comment
2431
should be at the top of the source file containing the @samp{main}
2432
function of the program.
2433
 
2434
Also, please write a brief comment at the start of each source file,
2435
with the file name and a line or two about the overall purpose of the
2436
file.
2437
 
2438
Please write the comments in a GNU program in English, because English
2439
is the one language that nearly all programmers in all countries can
2440
read.  If you do not write English well, please write comments in
2441
English as well as you can, then ask other people to help rewrite them.
2442
If you can't write comments in English, please find someone to work with
2443
you and translate your comments into English.
2444
 
2445
Please put a comment on each function saying what the function does,
2446
what sorts of arguments it gets, and what the possible values of
2447
arguments mean and are used for.  It is not necessary to duplicate in
2448
words the meaning of the C argument declarations, if a C type is being
2449
used in its customary fashion.  If there is anything nonstandard about
2450
its use (such as an argument of type @code{char *} which is really the
2451
address of the second character of a string, not the first), or any
2452
possible values that would not work the way one would expect (such as,
2453
that strings containing newlines are not guaranteed to work), be sure
2454
to say so.
2455
 
2456
Also explain the significance of the return value, if there is one.
2457
 
2458
Please put two spaces after the end of a sentence in your comments, so
2459
that the Emacs sentence commands will work.  Also, please write
2460
complete sentences and capitalize the first word.  If a lower-case
2461
identifier comes at the beginning of a sentence, don't capitalize it!
2462
Changing the spelling makes it a different identifier.  If you don't
2463
like starting a sentence with a lower case letter, write the sentence
2464
differently (e.g., ``The identifier lower-case is @dots{}'').
2465
 
2466
The comment on a function is much clearer if you use the argument
2467
names to speak about the argument values.  The variable name itself
2468
should be lower case, but write it in upper case when you are speaking
2469
about the value rather than the variable itself.  Thus, ``the inode
2470
number NODE_NUM'' rather than ``an inode''.
2471
 
2472
There is usually no purpose in restating the name of the function in
2473
the comment before it, because the reader can see that for himself.
2474
There might be an exception when the comment is so long that the function
2475
itself would be off the bottom of the screen.
2476
 
2477
There should be a comment on each static variable as well, like this:
2478
 
2479
@example
2480
/* Nonzero means truncate lines in the display;
2481
   zero means continue them.  */
2482
int truncate_lines;
2483
@end example
2484
 
2485
@cindex conditionals, comments for
2486
@cindex @code{#endif}, commenting
2487
Every @samp{#endif} should have a comment, except in the case of short
2488
conditionals (just a few lines) that are not nested.  The comment should
2489
state the condition of the conditional that is ending, @emph{including
2490
its sense}.  @samp{#else} should have a comment describing the condition
2491
@emph{and sense} of the code that follows.  For example:
2492
 
2493
@example
2494
@group
2495
#ifdef foo
2496
  @dots{}
2497
#else /* not foo */
2498
  @dots{}
2499
#endif /* not foo */
2500
@end group
2501
@group
2502
#ifdef foo
2503
  @dots{}
2504
#endif /* foo */
2505
@end group
2506
@end example
2507
 
2508
@noindent
2509
but, by contrast, write the comments this way for a @samp{#ifndef}:
2510
 
2511
@example
2512
@group
2513
#ifndef foo
2514
  @dots{}
2515
#else /* foo */
2516
  @dots{}
2517
#endif /* foo */
2518
@end group
2519
@group
2520
#ifndef foo
2521
  @dots{}
2522
#endif /* not foo */
2523
@end group
2524
@end example
2525
 
2526
@node Syntactic Conventions
2527
@section Clean Use of C Constructs
2528
@cindex syntactic conventions
2529
 
2530
@cindex implicit @code{int}
2531
@cindex function argument, declaring
2532
Please explicitly declare the types of all objects.  For example, you
2533
should explicitly declare all arguments to functions, and you should
2534
declare functions to return @code{int} rather than omitting the
2535
@code{int}.
2536
 
2537
@cindex compiler warnings
2538
@cindex @samp{-Wall} compiler option
2539
Some programmers like to use the GCC @samp{-Wall} option, and change the
2540
code whenever it issues a warning.  If you want to do this, then do.
2541
Other programmers prefer not to use @samp{-Wall}, because it gives
2542
warnings for valid and legitimate code which they do not want to change.
2543
If you want to do this, then do.  The compiler should be your servant,
2544
not your master.
2545
 
2546
Declarations of external functions and functions to appear later in the
2547
source file should all go in one place near the beginning of the file
2548
(somewhere before the first function definition in the file), or else
2549
should go in a header file.  Don't put @code{extern} declarations inside
2550
functions.
2551
 
2552
@cindex temporary variables
2553
It used to be common practice to use the same local variables (with
2554
names like @code{tem}) over and over for different values within one
2555
function.  Instead of doing this, it is better to declare a separate local
2556
variable for each distinct purpose, and give it a name which is
2557
meaningful.  This not only makes programs easier to understand, it also
2558
facilitates optimization by good compilers.  You can also move the
2559
declaration of each local variable into the smallest scope that includes
2560
all its uses.  This makes the program even cleaner.
2561
 
2562
Don't use local variables or parameters that shadow global identifiers.
2563
 
2564
@cindex multiple variables in a line
2565
Don't declare multiple variables in one declaration that spans lines.
2566
Start a new declaration on each line, instead.  For example, instead
2567
of this:
2568
 
2569
@example
2570
@group
2571
int    foo,
2572
       bar;
2573
@end group
2574
@end example
2575
 
2576
@noindent
2577
write either this:
2578
 
2579
@example
2580
int foo, bar;
2581
@end example
2582
 
2583
@noindent
2584
or this:
2585
 
2586
@example
2587
int foo;
2588
int bar;
2589
@end example
2590
 
2591
@noindent
2592
(If they are global variables, each should have a comment preceding it
2593
anyway.)
2594
 
2595
When you have an @code{if}-@code{else} statement nested in another
2596
@code{if} statement, always put braces around the @code{if}-@code{else}.
2597
Thus, never write like this:
2598
 
2599
@example
2600
if (foo)
2601
  if (bar)
2602
    win ();
2603
  else
2604
    lose ();
2605
@end example
2606
 
2607
@noindent
2608
always like this:
2609
 
2610
@example
2611
if (foo)
2612
  @{
2613
    if (bar)
2614
      win ();
2615
    else
2616
      lose ();
2617
  @}
2618
@end example
2619
 
2620
If you have an @code{if} statement nested inside of an @code{else}
2621
statement, either write @code{else if} on one line, like this,
2622
 
2623
@example
2624
if (foo)
2625
  @dots{}
2626
else if (bar)
2627
  @dots{}
2628
@end example
2629
 
2630
@noindent
2631
with its @code{then}-part indented like the preceding @code{then}-part,
2632
or write the nested @code{if} within braces like this:
2633
 
2634
@example
2635
if (foo)
2636
  @dots{}
2637
else
2638
  @{
2639
    if (bar)
2640
      @dots{}
2641
  @}
2642
@end example
2643
 
2644
Don't declare both a structure tag and variables or typedefs in the
2645
same declaration.  Instead, declare the structure tag separately
2646
and then use it to declare the variables or typedefs.
2647
 
2648
Try to avoid assignments inside @code{if}-conditions (assignments
2649
inside @code{while}-conditions are ok).  For example, don't write
2650
this:
2651
 
2652
@example
2653
if ((foo = (char *) malloc (sizeof *foo)) == 0)
2654
  fatal ("virtual memory exhausted");
2655
@end example
2656
 
2657
@noindent
2658
instead, write this:
2659
 
2660
@example
2661
foo = (char *) malloc (sizeof *foo);
2662
if (foo == 0)
2663
  fatal ("virtual memory exhausted");
2664
@end example
2665
 
2666
@pindex lint
2667
Don't make the program ugly to placate @code{lint}.  Please don't insert any
2668
casts to @code{void}.  Zero without a cast is perfectly fine as a null
2669
pointer constant, except when calling a varargs function.
2670
 
2671
@node Names
2672
@section Naming Variables, Functions, and Files
2673
 
2674
@cindex names of variables, functions, and files
2675
The names of global variables and functions in a program serve as
2676
comments of a sort.  So don't choose terse names---instead, look for
2677
names that give useful information about the meaning of the variable or
2678
function.  In a GNU program, names should be English, like other
2679
comments.
2680
 
2681
Local variable names can be shorter, because they are used only within
2682
one context, where (presumably) comments explain their purpose.
2683
 
2684
Try to limit your use of abbreviations in symbol names.  It is ok to
2685
make a few abbreviations, explain what they mean, and then use them
2686
frequently, but don't use lots of obscure abbreviations.
2687
 
2688
Please use underscores to separate words in a name, so that the Emacs
2689
word commands can be useful within them.  Stick to lower case; reserve
2690
upper case for macros and @code{enum} constants, and for name-prefixes
2691
that follow a uniform convention.
2692
 
2693
For example, you should use names like @code{ignore_space_change_flag};
2694
don't use names like @code{iCantReadThis}.
2695
 
2696
Variables that indicate whether command-line options have been
2697
specified should be named after the meaning of the option, not after
2698
the option-letter.  A comment should state both the exact meaning of
2699
the option and its letter.  For example,
2700
 
2701
@example
2702
@group
2703
/* Ignore changes in horizontal whitespace (-b).  */
2704
int ignore_space_change_flag;
2705
@end group
2706
@end example
2707
 
2708
When you want to define names with constant integer values, use
2709
@code{enum} rather than @samp{#define}.  GDB knows about enumeration
2710
constants.
2711
 
2712
@cindex file-name limitations
2713
@pindex doschk
2714
You might want to make sure that none of the file names would conflict
2715
if the files were loaded onto an MS-DOS file system which shortens the
2716
names.  You can use the program @code{doschk} to test for this.
2717
 
2718
Some GNU programs were designed to limit themselves to file names of 14
2719
characters or less, to avoid file name conflicts if they are read into
2720
older System V systems.  Please preserve this feature in the existing
2721
GNU programs that have it, but there is no need to do this in new GNU
2722
programs.  @code{doschk} also reports file names longer than 14
2723
characters.
2724
 
2725
@node System Portability
2726
@section Portability between System Types
2727
@cindex portability, between system types
2728
 
2729
In the Unix world, ``portability'' refers to porting to different Unix
2730
versions.  For a GNU program, this kind of portability is desirable, but
2731
not paramount.
2732
 
2733
The primary purpose of GNU software is to run on top of the GNU kernel,
2734
compiled with the GNU C compiler, on various types of @sc{cpu}.  So the
2735
kinds of portability that are absolutely necessary are quite limited.
2736
But it is important to support Linux-based GNU systems, since they
2737
are the form of GNU that is popular.
2738
 
2739
Beyond that, it is good to support the other free operating systems
2740
(*BSD), and it is nice to support other Unix-like systems if you want
2741
to.  Supporting a variety of Unix-like systems is desirable, although
2742
not paramount.  It is usually not too hard, so you may as well do it.
2743
But you don't have to consider it an obligation, if it does turn out to
2744
be hard.
2745
 
2746
@pindex autoconf
2747
The easiest way to achieve portability to most Unix-like systems is to
2748
use Autoconf.  It's unlikely that your program needs to know more
2749
information about the host platform than Autoconf can provide, simply
2750
because most of the programs that need such knowledge have already been
2751
written.
2752
 
2753
Avoid using the format of semi-internal data bases (e.g., directories)
2754
when there is a higher-level alternative (@code{readdir}).
2755
 
2756
@cindex non-@sc{posix} systems, and portability
2757
As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS,
2758
and older Macintosh systems, supporting them is often a lot of work.
2759
When that is the case, it is better to spend your time adding features
2760
that will be useful on GNU and GNU/Linux, rather than on supporting
2761
other incompatible systems.
2762
 
2763
If you do support Windows, please do not abbreviate it as ``win''.  In
2764
hacker terminology, calling something a ``win'' is a form of praise.
2765
You're free to praise Microsoft Windows on your own if you want, but
2766
please don't do this in GNU packages.  Instead of abbreviating
2767
``Windows'' to ``un'', you can write it in full or abbreviate it to
2768
``woe'' or ``w''.  In GNU Emacs, for instance, we use @samp{w32} in
2769
file names of Windows-specific files, but the macro for Windows
2770
conditionals is called @code{WINDOWSNT}.
2771
 
2772
It is a good idea to define the ``feature test macro''
2773
@code{_GNU_SOURCE} when compiling your C files.  When you compile on GNU
2774
or GNU/Linux, this will enable the declarations of GNU library extension
2775
functions, and that will usually give you a compiler error message if
2776
you define the same function names in some other way in your program.
2777
(You don't have to actually @emph{use} these functions, if you prefer
2778
to make the program more portable to other systems.)
2779
 
2780
But whether or not you use these GNU extensions, you should avoid
2781
using their names for any other meanings.  Doing so would make it hard
2782
to move your code into other GNU programs.
2783
 
2784
@node CPU Portability
2785
@section Portability between @sc{cpu}s
2786
 
2787
@cindex data types, and portability
2788
@cindex portability, and data types
2789
Even GNU systems will differ because of differences among @sc{cpu}
2790
types---for example, difference in byte ordering and alignment
2791
requirements.  It is absolutely essential to handle these differences.
2792
However, don't make any effort to cater to the possibility that an
2793
@code{int} will be less than 32 bits.  We don't support 16-bit machines
2794
in GNU.
2795
 
2796
Similarly, don't make any effort to cater to the possibility that
2797
@code{long} will be smaller than predefined types like @code{size_t}.
2798
For example, the following code is ok:
2799
 
2800
@example
2801
printf ("size = %lu\n", (unsigned long) sizeof array);
2802
printf ("diff = %ld\n", (long) (pointer2 - pointer1));
2803
@end example
2804
 
2805
1989 Standard C requires this to work, and we know of only one
2806
counterexample: 64-bit programs on Microsoft Windows.  We will
2807
leave it to those who want to port GNU programs to that environment
2808
to figure out how to do it.
2809
 
2810
Predefined file-size types like @code{off_t} are an exception: they are
2811
longer than @code{long} on many platforms, so code like the above won't
2812
work with them.  One way to print an @code{off_t} value portably is to
2813
print its digits yourself, one by one.
2814
 
2815
Don't assume that the address of an @code{int} object is also the
2816
address of its least-significant byte.  This is false on big-endian
2817
machines.  Thus, don't make the following mistake:
2818
 
2819
@example
2820
int c;
2821
@dots{}
2822
while ((c = getchar ()) != EOF)
2823
  write (file_descriptor, &c, 1);
2824
@end example
2825
 
2826
@noindent Instead, use @code{unsigned char} as follows.  (The @code{unsigned}
2827
is for portability to unusual systems where @code{char} is signed and
2828
where there is integer overflow checking.)
2829
 
2830
@example
2831
int c;
2832
while ((c = getchar ()) != EOF)
2833
  @{
2834
    unsigned char u = c;
2835
    write (file_descriptor, &u, 1);
2836
  @}
2837
@end example
2838
 
2839
It used to be ok to not worry about the difference between pointers
2840
and integers when passing arguments to functions.  However, on most
2841
modern 64-bit machines pointers are wider than @code{int}.
2842
Conversely, integer types like @code{long long int} and @code{off_t}
2843
are wider than pointers on most modern 32-bit machines.  Hence it's
2844
often better nowadays to use prototypes to define functions whose
2845
argument types are not trivial.
2846
 
2847
In particular, if functions accept varying argument counts or types
2848
they should be declared using prototypes containing @samp{...} and
2849
defined using @file{stdarg.h}.  For an example of this, please see the
2850
@uref{http://www.gnu.org/software/gnulib/, Gnulib} error module, which
2851
declares and defines the following function:
2852
 
2853
@example
2854
/* Print a message with `fprintf (stderr, FORMAT, ...)';
2855
   if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
2856
   If STATUS is nonzero, terminate the program with `exit (STATUS)'.  */
2857
 
2858
void error (int status, int errnum, const char *format, ...);
2859
@end example
2860
 
2861
A simple way to use the Gnulib error module is to obtain the two
2862
source files @file{error.c} and @file{error.h} from the Gnulib library
2863
source code repository at
2864
@uref{http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/}.
2865
Here's a sample use:
2866
 
2867
@example
2868
#include "error.h"
2869
#include <errno.h>
2870
#include <stdio.h>
2871
 
2872
char *program_name = "myprogram";
2873
 
2874
FILE *
2875
xfopen (char const *name)
2876
@{
2877
  FILE *fp = fopen (name, "r");
2878
  if (! fp)
2879
    error (1, errno, "cannot read %s", name);
2880
  return fp;
2881
@}
2882
@end example
2883
 
2884
@cindex casting pointers to integers
2885
Avoid casting pointers to integers if you can.  Such casts greatly
2886
reduce portability, and in most programs they are easy to avoid.  In the
2887
cases where casting pointers to integers is essential---such as, a Lisp
2888
interpreter which stores type information as well as an address in one
2889
word---you'll have to make explicit provisions to handle different word
2890
sizes.  You will also need to make provision for systems in which the
2891
normal range of addresses you can get from @code{malloc} starts far away
2892
from zero.
2893
 
2894
@node System Functions
2895
@section Calling System Functions
2896
@cindex library functions, and portability
2897
@cindex portability, and library functions
2898
 
2899
C implementations differ substantially.  Standard C reduces but does
2900
not eliminate the incompatibilities; meanwhile, many GNU packages still
2901
support pre-standard compilers because this is not hard to do.  This
2902
chapter gives recommendations for how to use the more-or-less standard C
2903
library functions to avoid unnecessary loss of portability.
2904
 
2905
@itemize @bullet
2906
@item
2907
Don't use the return value of @code{sprintf}.  It returns the number of
2908
characters written on some systems, but not on all systems.
2909
 
2910
@item
2911
Be aware that @code{vfprintf} is not always available.
2912
 
2913
@item
2914
@code{main} should be declared to return type @code{int}.  It should
2915
terminate either by calling @code{exit} or by returning the integer
2916
status code; make sure it cannot ever return an undefined value.
2917
 
2918
@cindex declaration for system functions
2919
@item
2920
Don't declare system functions explicitly.
2921
 
2922
Almost any declaration for a system function is wrong on some system.
2923
To minimize conflicts, leave it to the system header files to declare
2924
system functions.  If the headers don't declare a function, let it
2925
remain undeclared.
2926
 
2927
While it may seem unclean to use a function without declaring it, in
2928
practice this works fine for most system library functions on the
2929
systems where this really happens; thus, the disadvantage is only
2930
theoretical.  By contrast, actual declarations have frequently caused
2931
actual conflicts.
2932
 
2933
@item
2934
If you must declare a system function, don't specify the argument types.
2935
Use an old-style declaration, not a Standard C prototype.  The more you
2936
specify about the function, the more likely a conflict.
2937
 
2938
@item
2939
In particular, don't unconditionally declare @code{malloc} or
2940
@code{realloc}.
2941
 
2942
Most GNU programs use those functions just once, in functions
2943
conventionally named @code{xmalloc} and @code{xrealloc}.  These
2944
functions call @code{malloc} and @code{realloc}, respectively, and
2945
check the results.
2946
 
2947
Because @code{xmalloc} and @code{xrealloc} are defined in your program,
2948
you can declare them in other files without any risk of type conflict.
2949
 
2950
On most systems, @code{int} is the same length as a pointer; thus, the
2951
calls to @code{malloc} and @code{realloc} work fine.  For the few
2952
exceptional systems (mostly 64-bit machines), you can use
2953
@strong{conditionalized} declarations of @code{malloc} and
2954
@code{realloc}---or put these declarations in configuration files
2955
specific to those systems.
2956
 
2957
@cindex string library functions
2958
@item
2959
The string functions require special treatment.  Some Unix systems have
2960
a header file @file{string.h}; others have @file{strings.h}.  Neither
2961
file name is portable.  There are two things you can do: use Autoconf to
2962
figure out which file to include, or don't include either file.
2963
 
2964
@item
2965
If you don't include either strings file, you can't get declarations for
2966
the string functions from the header file in the usual way.
2967
 
2968
That causes less of a problem than you might think.  The newer standard
2969
string functions should be avoided anyway because many systems still
2970
don't support them.  The string functions you can use are these:
2971
 
2972
@example
2973
strcpy   strncpy   strcat   strncat
2974
strlen   strcmp    strncmp
2975
strchr   strrchr
2976
@end example
2977
 
2978
The copy and concatenate functions work fine without a declaration as
2979
long as you don't use their values.  Using their values without a
2980
declaration fails on systems where the width of a pointer differs from
2981
the width of @code{int}, and perhaps in other cases.  It is trivial to
2982
avoid using their values, so do that.
2983
 
2984
The compare functions and @code{strlen} work fine without a declaration
2985
on most systems, possibly all the ones that GNU software runs on.
2986
You may find it necessary to declare them @strong{conditionally} on a
2987
few systems.
2988
 
2989
The search functions must be declared to return @code{char *}.  Luckily,
2990
there is no variation in the data type they return.  But there is
2991
variation in their names.  Some systems give these functions the names
2992
@code{index} and @code{rindex}; other systems use the names
2993
@code{strchr} and @code{strrchr}.  Some systems support both pairs of
2994
names, but neither pair works on all systems.
2995
 
2996
You should pick a single pair of names and use it throughout your
2997
program.  (Nowadays, it is better to choose @code{strchr} and
2998
@code{strrchr} for new programs, since those are the standard
2999
names.)  Declare both of those names as functions returning @code{char
3000
*}.  On systems which don't support those names, define them as macros
3001
in terms of the other pair.  For example, here is what to put at the
3002
beginning of your file (or in a header) if you want to use the names
3003
@code{strchr} and @code{strrchr} throughout:
3004
 
3005
@example
3006
#ifndef HAVE_STRCHR
3007
#define strchr index
3008
#endif
3009
#ifndef HAVE_STRRCHR
3010
#define strrchr rindex
3011
#endif
3012
 
3013
char *strchr ();
3014
char *strrchr ();
3015
@end example
3016
@end itemize
3017
 
3018
Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
3019
macros defined in systems where the corresponding functions exist.
3020
One way to get them properly defined is to use Autoconf.
3021
 
3022
@node Internationalization
3023
@section Internationalization
3024
@cindex internationalization
3025
 
3026
@pindex gettext
3027
GNU has a library called GNU gettext that makes it easy to translate the
3028
messages in a program into various languages.  You should use this
3029
library in every program.  Use English for the messages as they appear
3030
in the program, and let gettext provide the way to translate them into
3031
other languages.
3032
 
3033
Using GNU gettext involves putting a call to the @code{gettext} macro
3034
around each string that might need translation---like this:
3035
 
3036
@example
3037
printf (gettext ("Processing file `%s'..."));
3038
@end example
3039
 
3040
@noindent
3041
This permits GNU gettext to replace the string @code{"Processing file
3042
`%s'..."} with a translated version.
3043
 
3044
Once a program uses gettext, please make a point of writing calls to
3045
@code{gettext} when you add new strings that call for translation.
3046
 
3047
Using GNU gettext in a package involves specifying a @dfn{text domain
3048
name} for the package.  The text domain name is used to separate the
3049
translations for this package from the translations for other packages.
3050
Normally, the text domain name should be the same as the name of the
3051
package---for example, @samp{coreutils} for the GNU core utilities.
3052
 
3053
@cindex message text, and internationalization
3054
To enable gettext to work well, avoid writing code that makes
3055
assumptions about the structure of words or sentences.  When you want
3056
the precise text of a sentence to vary depending on the data, use two or
3057
more alternative string constants each containing a complete sentences,
3058
rather than inserting conditionalized words or phrases into a single
3059
sentence framework.
3060
 
3061
Here is an example of what not to do:
3062
 
3063
@smallexample
3064
printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
3065
@end smallexample
3066
 
3067
If you apply gettext to all strings, like this,
3068
 
3069
@smallexample
3070
printf (gettext ("%s is full"),
3071
        capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
3072
@end smallexample
3073
 
3074
@noindent
3075
the translator will hardly know that "disk" and "floppy disk" are meant to
3076
be substituted in the other string.  Worse, in some languages (like French)
3077
the construction will not work: the translation of the word "full" depends
3078
on the gender of the first part of the sentence; it happens to be not the
3079
same for "disk" as for "floppy disk".
3080
 
3081
Complete sentences can be translated without problems:
3082
 
3083
@example
3084
printf (capacity > 5000000 ? gettext ("disk is full")
3085
        : gettext ("floppy disk is full"));
3086
@end example
3087
 
3088
A similar problem appears at the level of sentence structure with this
3089
code:
3090
 
3091
@example
3092
printf ("#  Implicit rule search has%s been done.\n",
3093
        f->tried_implicit ? "" : " not");
3094
@end example
3095
 
3096
@noindent
3097
Adding @code{gettext} calls to this code cannot give correct results for
3098
all languages, because negation in some languages requires adding words
3099
at more than one place in the sentence.  By contrast, adding
3100
@code{gettext} calls does the job straightforwardly if the code starts
3101
out like this:
3102
 
3103
@example
3104
printf (f->tried_implicit
3105
        ? "#  Implicit rule search has been done.\n",
3106
        : "#  Implicit rule search has not been done.\n");
3107
@end example
3108
 
3109
Another example is this one:
3110
 
3111
@example
3112
printf ("%d file%s processed", nfiles,
3113
        nfiles != 1 ? "s" : "");
3114
@end example
3115
 
3116
@noindent
3117
The problem with this example is that it assumes that plurals are made
3118
by adding `s'.  If you apply gettext to the format string, like this,
3119
 
3120
@example
3121
printf (gettext ("%d file%s processed"), nfiles,
3122
        nfiles != 1 ? "s" : "");
3123
@end example
3124
 
3125
@noindent
3126
the message can use different words, but it will still be forced to use
3127
`s' for the plural.  Here is a better way, with gettext being applied to
3128
the two strings independently:
3129
 
3130
@example
3131
printf ((nfiles != 1 ? gettext ("%d files processed")
3132
         : gettext ("%d file processed")),
3133
        nfiles);
3134
@end example
3135
 
3136
@noindent
3137
But this still doesn't work for languages like Polish, which has three
3138
plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 24, ...
3139
and one for the rest.  The GNU @code{ngettext} function solves this problem:
3140
 
3141
@example
3142
printf (ngettext ("%d files processed", "%d file processed", nfiles),
3143
        nfiles);
3144
@end example
3145
 
3146
 
3147
@node Character Set
3148
@section Character Set
3149
@cindex character set
3150
@cindex encodings
3151
@cindex ASCII characters
3152
@cindex non-ASCII characters
3153
 
3154
Sticking to the ASCII character set (plain text, 7-bit characters) is
3155
preferred in GNU source code comments, text documents, and other
3156
contexts, unless there is good reason to do something else because of
3157
the application domain.  For example, if source code deals with the
3158
French Revolutionary calendar, it is OK if its literal strings contain
3159
accented characters in month names like ``Flor@'eal''.  Also, it is OK
3160
to use non-ASCII characters to represent proper names of contributors in
3161
change logs (@pxref{Change Logs}).
3162
 
3163
If you need to use non-ASCII characters, you should normally stick with
3164
one encoding, as one cannot in general mix encodings reliably.
3165
 
3166
 
3167
@node Quote Characters
3168
@section Quote Characters
3169
@cindex quote characters
3170
@cindex locale-specific quote characters
3171
@cindex left quote
3172
@cindex grave accent
3173
 
3174
In the C locale, GNU programs should stick to plain ASCII for quotation
3175
characters in messages to users: preferably 0x60 (@samp{`}) for left
3176
quotes and 0x27 (@samp{'}) for right quotes.  It is ok, but not
3177
required, to use locale-specific quotes in other locales.
3178
 
3179
The @uref{http://www.gnu.org/software/gnulib/, Gnulib} @code{quote} and
3180
@code{quotearg} modules provide a reasonably straightforward way to
3181
support locale-specific quote characters, as well as taking care of
3182
other issues, such as quoting a filename that itself contains a quote
3183
character.  See the Gnulib documentation for usage details.
3184
 
3185
In any case, the documentation for your program should clearly specify
3186
how it does quoting, if different than the preferred method of @samp{`}
3187
and @samp{'}.  This is especially important if the output of your
3188
program is ever likely to be parsed by another program.
3189
 
3190
Quotation characters are a difficult area in the computing world at
3191
this time: there are no true left or right quote characters in Latin1;
3192
the @samp{`} character we use was standardized there as a grave
3193
accent.  Moreover, Latin1 is still not universally usable.
3194
 
3195
Unicode contains the unambiguous quote characters required, and its
3196
common encoding UTF-8 is upward compatible with Latin1.  However,
3197
Unicode and UTF-8 are not universally well-supported, either.
3198
 
3199
This may change over the next few years, and then we will revisit
3200
this.
3201
 
3202
 
3203
@node Mmap
3204
@section Mmap
3205
@findex mmap
3206
 
3207
Don't assume that @code{mmap} either works on all files or fails
3208
for all files.  It may work on some files and fail on others.
3209
 
3210
The proper way to use @code{mmap} is to try it on the specific file for
3211
which you want to use it---and if @code{mmap} doesn't work, fall back on
3212
doing the job in another way using @code{read} and @code{write}.
3213
 
3214
The reason this precaution is needed is that the GNU kernel (the HURD)
3215
provides a user-extensible file system, in which there can be many
3216
different kinds of ``ordinary files.''  Many of them support
3217
@code{mmap}, but some do not.  It is important to make programs handle
3218
all these kinds of files.
3219
 
3220
@node Documentation
3221
@chapter Documenting Programs
3222
@cindex documentation
3223
 
3224
A GNU program should ideally come with full free documentation, adequate
3225
for both reference and tutorial purposes.  If the package can be
3226
programmed or extended, the documentation should cover programming or
3227
extending it, as well as just using it.
3228
 
3229
@menu
3230
* GNU Manuals::                 Writing proper manuals.
3231
* Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
3232
* Manual Structure Details::    Specific structure conventions.
3233
* License for Manuals::         Writing the distribution terms for a manual.
3234
* Manual Credits::              Giving credit to documentation contributors.
3235
* Printed Manuals::             Mentioning the printed manual.
3236
* NEWS File::                   NEWS files supplement manuals.
3237
* Change Logs::                 Recording changes.
3238
* Man Pages::                   Man pages are secondary.
3239
* Reading other Manuals::       How far you can go in learning
3240
                                from other manuals.
3241
@end menu
3242
 
3243
@node GNU Manuals
3244
@section GNU Manuals
3245
 
3246
The preferred document format for the GNU system is the Texinfo
3247
formatting language.  Every GNU package should (ideally) have
3248
documentation in Texinfo both for reference and for learners.  Texinfo
3249
makes it possible to produce a good quality formatted book, using
3250
@TeX{}, and to generate an Info file.  It is also possible to generate
3251
HTML output from Texinfo source.  See the Texinfo manual, either the
3252
hardcopy, or the on-line version available through @code{info} or the
3253
Emacs Info subsystem (@kbd{C-h i}).
3254
 
3255
Nowadays some other formats such as Docbook and Sgmltexi can be
3256
converted automatically into Texinfo.  It is ok to produce the Texinfo
3257
documentation by conversion this way, as long as it gives good results.
3258
 
3259
Make sure your manual is clear to a reader who knows nothing about the
3260
topic and reads it straight through.  This means covering basic topics
3261
at the beginning, and advanced topics only later.  This also means
3262
defining every specialized term when it is first used.
3263
 
3264
Programmers tend to carry over the structure of the program as the
3265
structure for its documentation.  But this structure is not
3266
necessarily good for explaining how to use the program; it may be
3267
irrelevant and confusing for a user.
3268
 
3269
Instead, the right way to structure documentation is according to the
3270
concepts and questions that a user will have in mind when reading it.
3271
This principle applies at every level, from the lowest (ordering
3272
sentences in a paragraph) to the highest (ordering of chapter topics
3273
within the manual).  Sometimes this structure of ideas matches the
3274
structure of the implementation of the software being documented---but
3275
often they are different.  An important part of learning to write good
3276
documentation is to learn to notice when you have unthinkingly
3277
structured the documentation like the implementation, stop yourself,
3278
and look for better alternatives.
3279
 
3280
For example, each program in the GNU system probably ought to be
3281
documented in one manual; but this does not mean each program should
3282
have its own manual.  That would be following the structure of the
3283
implementation, rather than the structure that helps the user
3284
understand.
3285
 
3286
Instead, each manual should cover a coherent @emph{topic}.  For example,
3287
instead of a manual for @code{diff} and a manual for @code{diff3}, we
3288
have one manual for ``comparison of files'' which covers both of those
3289
programs, as well as @code{cmp}.  By documenting these programs
3290
together, we can make the whole subject clearer.
3291
 
3292
The manual which discusses a program should certainly document all of
3293
the program's command-line options and all of its commands.  It should
3294
give examples of their use.  But don't organize the manual as a list
3295
of features.  Instead, organize it logically, by subtopics.  Address
3296
the questions that a user will ask when thinking about the job that
3297
the program does.  Don't just tell the reader what each feature can
3298
do---say what jobs it is good for, and show how to use it for those
3299
jobs.  Explain what is recommended usage, and what kinds of usage
3300
users should avoid.
3301
 
3302
In general, a GNU manual should serve both as tutorial and reference.
3303
It should be set up for convenient access to each topic through Info,
3304
and for reading straight through (appendixes aside).  A GNU manual
3305
should give a good introduction to a beginner reading through from the
3306
start, and should also provide all the details that hackers want.
3307
The Bison manual is a good example of this---please take a look at it
3308
to see what we mean.
3309
 
3310
That is not as hard as it first sounds.  Arrange each chapter as a
3311
logical breakdown of its topic, but order the sections, and write their
3312
text, so that reading the chapter straight through makes sense.  Do
3313
likewise when structuring the book into chapters, and when structuring a
3314
section into paragraphs.  The watchword is, @emph{at each point, address
3315
the most fundamental and important issue raised by the preceding text.}
3316
 
3317
If necessary, add extra chapters at the beginning of the manual which
3318
are purely tutorial and cover the basics of the subject.  These provide
3319
the framework for a beginner to understand the rest of the manual.  The
3320
Bison manual provides a good example of how to do this.
3321
 
3322
To serve as a reference, a manual should have an Index that list all the
3323
functions, variables, options, and important concepts that are part of
3324
the program.  One combined Index should do for a short manual, but
3325
sometimes for a complex package it is better to use multiple indices.
3326
The Texinfo manual includes advice on preparing good index entries, see
3327
@ref{Index Entries, , Making Index Entries, texinfo, GNU Texinfo}, and
3328
see @ref{Indexing Commands, , Defining the Entries of an
3329
Index, texinfo, GNU Texinfo}.
3330
 
3331
Don't use Unix man pages as a model for how to write GNU documentation;
3332
most of them are terse, badly structured, and give inadequate
3333
explanation of the underlying concepts.  (There are, of course, some
3334
exceptions.)  Also, Unix man pages use a particular format which is
3335
different from what we use in GNU manuals.
3336
 
3337
Please include an email address in the manual for where to report
3338
bugs @emph{in the text of the manual}.
3339
 
3340
Please do not use the term ``pathname'' that is used in Unix
3341
documentation; use ``file name'' (two words) instead.  We use the term
3342
``path'' only for search paths, which are lists of directory names.
3343
 
3344
Please do not use the term ``illegal'' to refer to erroneous input to
3345
a computer program.  Please use ``invalid'' for this, and reserve the
3346
term ``illegal'' for activities prohibited by law.
3347
 
3348
Please do not write @samp{()} after a function name just to indicate
3349
it is a function.  @code{foo ()} is not a function, it is a function
3350
call with no arguments.
3351
 
3352
@node Doc Strings and Manuals
3353
@section Doc Strings and Manuals
3354
 
3355
Some programming systems, such as Emacs, provide a documentation string
3356
for each function, command or variable.  You may be tempted to write a
3357
reference manual by compiling the documentation strings and writing a
3358
little additional text to go around them---but you must not do it.  That
3359
approach is a fundamental mistake.  The text of well-written
3360
documentation strings will be entirely wrong for a manual.
3361
 
3362
A documentation string needs to stand alone---when it appears on the
3363
screen, there will be no other text to introduce or explain it.
3364
Meanwhile, it can be rather informal in style.
3365
 
3366
The text describing a function or variable in a manual must not stand
3367
alone; it appears in the context of a section or subsection.  Other text
3368
at the beginning of the section should explain some of the concepts, and
3369
should often make some general points that apply to several functions or
3370
variables.  The previous descriptions of functions and variables in the
3371
section will also have given information about the topic.  A description
3372
written to stand alone would repeat some of that information; this
3373
redundancy looks bad.  Meanwhile, the informality that is acceptable in
3374
a documentation string is totally unacceptable in a manual.
3375
 
3376
The only good way to use documentation strings in writing a good manual
3377
is to use them as a source of information for writing good text.
3378
 
3379
@node Manual Structure Details
3380
@section Manual Structure Details
3381
@cindex manual structure
3382
 
3383
The title page of the manual should state the version of the programs or
3384
packages documented in the manual.  The Top node of the manual should
3385
also contain this information.  If the manual is changing more
3386
frequently than or independent of the program, also state a version
3387
number for the manual in both of these places.
3388
 
3389
Each program documented in the manual should have a node named
3390
@samp{@var{program} Invocation} or @samp{Invoking @var{program}}.  This
3391
node (together with its subnodes, if any) should describe the program's
3392
command line arguments and how to run it (the sort of information people
3393
would look for in a man page).  Start with an @samp{@@example}
3394
containing a template for all the options and arguments that the program
3395
uses.
3396
 
3397
Alternatively, put a menu item in some menu whose item name fits one of
3398
the above patterns.  This identifies the node which that item points to
3399
as the node for this purpose, regardless of the node's actual name.
3400
 
3401
The @samp{--usage} feature of the Info reader looks for such a node
3402
or menu item in order to find the relevant text, so it is essential
3403
for every Texinfo file to have one.
3404
 
3405
If one manual describes several programs, it should have such a node for
3406
each program described in the manual.
3407
 
3408
@node License for Manuals
3409
@section License for Manuals
3410
@cindex license for manuals
3411
 
3412
Please use the GNU Free Documentation License for all GNU manuals that
3413
are more than a few pages long.  Likewise for a collection of short
3414
documents---you only need one copy of the GNU FDL for the whole
3415
collection.  For a single short document, you can use a very permissive
3416
non-copyleft license, to avoid taking up space with a long license.
3417
 
3418
See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation
3419
of how to employ the GFDL.
3420
 
3421
Note that it is not obligatory to include a copy of the GNU GPL or GNU
3422
LGPL in a manual whose license is neither the GPL nor the LGPL.  It can
3423
be a good idea to include the program's license in a large manual; in a
3424
short manual, whose size would be increased considerably by including
3425
the program's license, it is probably better not to include it.
3426
 
3427
@node Manual Credits
3428
@section Manual Credits
3429
@cindex credits for manuals
3430
 
3431
Please credit the principal human writers of the manual as the authors,
3432
on the title page of the manual.  If a company sponsored the work, thank
3433
the company in a suitable place in the manual, but do not cite the
3434
company as an author.
3435
 
3436
@node Printed Manuals
3437
@section Printed Manuals
3438
 
3439
The FSF publishes some GNU manuals in printed form.  To encourage sales
3440
of these manuals, the on-line versions of the manual should mention at
3441
the very start that the printed manual is available and should point at
3442
information for getting it---for instance, with a link to the page
3443
@url{http://www.gnu.org/order/order.html}.  This should not be included
3444
in the printed manual, though, because there it is redundant.
3445
 
3446
It is also useful to explain in the on-line forms of the manual how the
3447
user can print out the manual from the sources.
3448
 
3449
@node NEWS File
3450
@section The NEWS File
3451
@cindex @file{NEWS} file
3452
 
3453
In addition to its manual, the package should have a file named
3454
@file{NEWS} which contains a list of user-visible changes worth
3455
mentioning.  In each new release, add items to the front of the file and
3456
identify the version they pertain to.  Don't discard old items; leave
3457
them in the file after the newer items.  This way, a user upgrading from
3458
any previous version can see what is new.
3459
 
3460
If the @file{NEWS} file gets very long, move some of the older items
3461
into a file named @file{ONEWS} and put a note at the end referring the
3462
user to that file.
3463
 
3464
@node Change Logs
3465
@section Change Logs
3466
@cindex change logs
3467
 
3468
Keep a change log to describe all the changes made to program source
3469
files.  The purpose of this is so that people investigating bugs in the
3470
future will know about the changes that might have introduced the bug.
3471
Often a new bug can be found by looking at what was recently changed.
3472
More importantly, change logs can help you eliminate conceptual
3473
inconsistencies between different parts of a program, by giving you a
3474
history of how the conflicting concepts arose and who they came from.
3475
 
3476
@menu
3477
* Change Log Concepts::
3478
* Style of Change Logs::
3479
* Simple Changes::
3480
* Conditional Changes::
3481
* Indicating the Part Changed::
3482
@end menu
3483
 
3484
@node Change Log Concepts
3485
@subsection Change Log Concepts
3486
 
3487
You can think of the change log as a conceptual ``undo list'' which
3488
explains how earlier versions were different from the current version.
3489
People can see the current version; they don't need the change log
3490
to tell them what is in it.  What they want from a change log is a
3491
clear explanation of how the earlier version differed.
3492
 
3493
The change log file is normally called @file{ChangeLog} and covers an
3494
entire directory.  Each directory can have its own change log, or a
3495
directory can use the change log of its parent directory--it's up to
3496
you.
3497
 
3498
Another alternative is to record change log information with a version
3499
control system such as RCS or CVS.  This can be converted automatically
3500
to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
3501
@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
3502
 
3503
There's no need to describe the full purpose of the changes or how they
3504
work together.  If you think that a change calls for explanation, you're
3505
probably right.  Please do explain it---but please put the explanation
3506
in comments in the code, where people will see it whenever they see the
3507
code.  For example, ``New function'' is enough for the change log when
3508
you add a function, because there should be a comment before the
3509
function definition to explain what it does.
3510
 
3511
In the past, we recommended not mentioning changes in non-software
3512
files (manuals, help files, etc.) in change logs.  However, we've been
3513
advised that it is a good idea to include them, for the sake of
3514
copyright records.
3515
 
3516
However, sometimes it is useful to write one line to describe the
3517
overall purpose of a batch of changes.
3518
 
3519
The easiest way to add an entry to @file{ChangeLog} is with the Emacs
3520
command @kbd{M-x add-change-log-entry}.  An entry should have an
3521
asterisk, the name of the changed file, and then in parentheses the name
3522
of the changed functions, variables or whatever, followed by a colon.
3523
Then describe the changes you made to that function or variable.
3524
 
3525
@node Style of Change Logs
3526
@subsection Style of Change Logs
3527
@cindex change logs, style
3528
 
3529
Here are some simple examples of change log entries, starting with the
3530
header line that says who made the change and when it was installed,
3531
followed by descriptions of specific changes.  (These examples are
3532
drawn from Emacs and GCC.)
3533
 
3534
@example
3535
1998-08-17  Richard Stallman  <rms@@gnu.org>
3536
 
3537
* register.el (insert-register): Return nil.
3538
(jump-to-register): Likewise.
3539
 
3540
* sort.el (sort-subr): Return nil.
3541
 
3542
* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3543
Restart the tex shell if process is gone or stopped.
3544
(tex-shell-running): New function.
3545
 
3546
* expr.c (store_one_arg): Round size up for move_block_to_reg.
3547
(expand_call): Round up when emitting USE insns.
3548
* stmt.c (assign_parms): Round size up for move_block_from_reg.
3549
@end example
3550
 
3551
It's important to name the changed function or variable in full.  Don't
3552
abbreviate function or variable names, and don't combine them.
3553
Subsequent maintainers will often search for a function name to find all
3554
the change log entries that pertain to it; if you abbreviate the name,
3555
they won't find it when they search.
3556
 
3557
For example, some people are tempted to abbreviate groups of function
3558
names by writing @samp{* register.el (@{insert,jump-to@}-register)};
3559
this is not a good idea, since searching for @code{jump-to-register} or
3560
@code{insert-register} would not find that entry.
3561
 
3562
Separate unrelated change log entries with blank lines.  When two
3563
entries represent parts of the same change, so that they work together,
3564
then don't put blank lines between them.  Then you can omit the file
3565
name and the asterisk when successive entries are in the same file.
3566
 
3567
Break long lists of function names by closing continued lines with
3568
@samp{)}, rather than @samp{,}, and opening the continuation with
3569
@samp{(} as in this example:
3570
 
3571
@example
3572
* keyboard.c (menu_bar_items, tool_bar_items)
3573
(Fexecute_extended_command): Deal with `keymap' property.
3574
@end example
3575
 
3576
When you install someone else's changes, put the contributor's name in
3577
the change log entry rather than in the text of the entry.  In other
3578
words, write this:
3579
 
3580
@example
3581
2002-07-14  John Doe  <jdoe@@gnu.org>
3582
 
3583
        * sewing.c: Make it sew.
3584
@end example
3585
 
3586
@noindent
3587
rather than this:
3588
 
3589
@example
3590
2002-07-14  Usual Maintainer  <usual@@gnu.org>
3591
 
3592
        * sewing.c: Make it sew.  Patch by jdoe@@gnu.org.
3593
@end example
3594
 
3595
As for the date, that should be the date you applied the change.
3596
 
3597
@node Simple Changes
3598
@subsection Simple Changes
3599
 
3600
Certain simple kinds of changes don't need much detail in the change
3601
log.
3602
 
3603
When you change the calling sequence of a function in a simple fashion,
3604
and you change all the callers of the function to use the new calling
3605
sequence, there is no need to make individual entries for all the
3606
callers that you changed.  Just write in the entry for the function
3607
being called, ``All callers changed''---like this:
3608
 
3609
@example
3610
* keyboard.c (Fcommand_execute): New arg SPECIAL.
3611
All callers changed.
3612
@end example
3613
 
3614
When you change just comments or doc strings, it is enough to write an
3615
entry for the file, without mentioning the functions.  Just ``Doc
3616
fixes'' is enough for the change log.
3617
 
3618
There's no technical need to make change log entries for documentation
3619
files.  This is because documentation is not susceptible to bugs that
3620
are hard to fix.  Documentation does not consist of parts that must
3621
interact in a precisely engineered fashion.  To correct an error, you
3622
need not know the history of the erroneous passage; it is enough to
3623
compare what the documentation says with the way the program actually
3624
works.
3625
 
3626
However, you should keep change logs for documentation files when the
3627
project gets copyright assignments from its contributors, so as to
3628
make the records of authorship more accurate.
3629
 
3630
@node Conditional Changes
3631
@subsection Conditional Changes
3632
@cindex conditional changes, and change logs
3633
@cindex change logs, conditional changes
3634
 
3635
C programs often contain compile-time @code{#if} conditionals.  Many
3636
changes are conditional; sometimes you add a new definition which is
3637
entirely contained in a conditional.  It is very useful to indicate in
3638
the change log the conditions for which the change applies.
3639
 
3640
Our convention for indicating conditional changes is to use square
3641
brackets around the name of the condition.
3642
 
3643
Here is a simple example, describing a change which is conditional but
3644
does not have a function or entity name associated with it:
3645
 
3646
@example
3647
* xterm.c [SOLARIS2]: Include string.h.
3648
@end example
3649
 
3650
Here is an entry describing a new definition which is entirely
3651
conditional.  This new definition for the macro @code{FRAME_WINDOW_P} is
3652
used only when @code{HAVE_X_WINDOWS} is defined:
3653
 
3654
@example
3655
* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3656
@end example
3657
 
3658
Here is an entry for a change within the function @code{init_display},
3659
whose definition as a whole is unconditional, but the changes themselves
3660
are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
3661
 
3662
@example
3663
* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3664
@end example
3665
 
3666
Here is an entry for a change that takes affect only when
3667
a certain macro is @emph{not} defined:
3668
 
3669
@example
3670
(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3671
@end example
3672
 
3673
@node Indicating the Part Changed
3674
@subsection Indicating the Part Changed
3675
 
3676
Indicate the part of a function which changed by using angle brackets
3677
enclosing an indication of what the changed part does.  Here is an entry
3678
for a change in the part of the function @code{sh-while-getopts} that
3679
deals with @code{sh} commands:
3680
 
3681
@example
3682
* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
3683
user-specified option string is empty.
3684
@end example
3685
 
3686
 
3687
@node Man Pages
3688
@section Man Pages
3689
@cindex man pages
3690
 
3691
In the GNU project, man pages are secondary.  It is not necessary or
3692
expected for every GNU program to have a man page, but some of them do.
3693
It's your choice whether to include a man page in your program.
3694
 
3695
When you make this decision, consider that supporting a man page
3696
requires continual effort each time the program is changed.  The time
3697
you spend on the man page is time taken away from more useful work.
3698
 
3699
For a simple program which changes little, updating the man page may be
3700
a small job.  Then there is little reason not to include a man page, if
3701
you have one.
3702
 
3703
For a large program that changes a great deal, updating a man page may
3704
be a substantial burden.  If a user offers to donate a man page, you may
3705
find this gift costly to accept.  It may be better to refuse the man
3706
page unless the same person agrees to take full responsibility for
3707
maintaining it---so that you can wash your hands of it entirely.  If
3708
this volunteer later ceases to do the job, then don't feel obliged to
3709
pick it up yourself; it may be better to withdraw the man page from the
3710
distribution until someone else agrees to update it.
3711
 
3712
When a program changes only a little, you may feel that the
3713
discrepancies are small enough that the man page remains useful without
3714
updating.  If so, put a prominent note near the beginning of the man
3715
page explaining that you don't maintain it and that the Texinfo manual
3716
is more authoritative.  The note should say how to access the Texinfo
3717
documentation.
3718
 
3719
Be sure that man pages include a copyright statement and free
3720
license.  The simple all-permissive license is appropriate for simple
3721
man pages:
3722
 
3723
@example
3724
Copying and distribution of this file, with or without modification,
3725
are permitted in any medium without royalty provided the copyright
3726
notice and this notice are preserved.
3727
@end example
3728
 
3729
For long man pages, with enough explanation and documentation that
3730
they can be considered true manuals, use the GFDL (@pxref{License for
3731
Manuals}).
3732
 
3733
Finally, the GNU help2man program
3734
(@uref{http://www.gnu.org/software/help2man/}) is one way to automate
3735
generation of a man page, in this case from @option{--help} output.
3736
This is sufficient in many cases.
3737
 
3738
@node Reading other Manuals
3739
@section Reading other Manuals
3740
 
3741
There may be non-free books or documentation files that describe the
3742
program you are documenting.
3743
 
3744
It is ok to use these documents for reference, just as the author of a
3745
new algebra textbook can read other books on algebra.  A large portion
3746
of any non-fiction book consists of facts, in this case facts about how
3747
a certain program works, and these facts are necessarily the same for
3748
everyone who writes about the subject.  But be careful not to copy your
3749
outline structure, wording, tables or examples from preexisting non-free
3750
documentation.  Copying from free documentation may be ok; please check
3751
with the FSF about the individual case.
3752
 
3753
@node Managing Releases
3754
@chapter The Release Process
3755
@cindex releasing
3756
 
3757
Making a release is more than just bundling up your source files in a
3758
tar file and putting it up for FTP.  You should set up your software so
3759
that it can be configured to run on a variety of systems.  Your Makefile
3760
should conform to the GNU standards described below, and your directory
3761
layout should also conform to the standards discussed below.  Doing so
3762
makes it easy to include your package into the larger framework of
3763
all GNU software.
3764
 
3765
@menu
3766
* Configuration::               How configuration of GNU packages should work.
3767
* Makefile Conventions::        Makefile conventions.
3768
* Releases::                    Making releases
3769
@end menu
3770
 
3771
@node Configuration
3772
@section How Configuration Should Work
3773
@cindex program configuration
3774
 
3775
@pindex configure
3776
Each GNU distribution should come with a shell script named
3777
@code{configure}.  This script is given arguments which describe the
3778
kind of machine and system you want to compile the program for.
3779
 
3780
The @code{configure} script must record the configuration options so
3781
that they affect compilation.
3782
 
3783
One way to do this is to make a link from a standard name such as
3784
@file{config.h} to the proper configuration file for the chosen system.
3785
If you use this technique, the distribution should @emph{not} contain a
3786
file named @file{config.h}.  This is so that people won't be able to
3787
build the program without configuring it first.
3788
 
3789
Another thing that @code{configure} can do is to edit the Makefile.  If
3790
you do this, the distribution should @emph{not} contain a file named
3791
@file{Makefile}.  Instead, it should include a file @file{Makefile.in} which
3792
contains the input used for editing.  Once again, this is so that people
3793
won't be able to build the program without configuring it first.
3794
 
3795
If @code{configure} does write the @file{Makefile}, then @file{Makefile}
3796
should have a target named @file{Makefile} which causes @code{configure}
3797
to be rerun, setting up the same configuration that was set up last
3798
time.  The files that @code{configure} reads should be listed as
3799
dependencies of @file{Makefile}.
3800
 
3801
All the files which are output from the @code{configure} script should
3802
have comments at the beginning explaining that they were generated
3803
automatically using @code{configure}.  This is so that users won't think
3804
of trying to edit them by hand.
3805
 
3806
The @code{configure} script should write a file named @file{config.status}
3807
which describes which configuration options were specified when the
3808
program was last configured.  This file should be a shell script which,
3809
if run, will recreate the same configuration.
3810
 
3811
The @code{configure} script should accept an option of the form
3812
@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
3813
(if it is not the current directory).  This makes it possible to build
3814
the program in a separate directory, so that the actual source directory
3815
is not modified.
3816
 
3817
If the user does not specify @samp{--srcdir}, then @code{configure} should
3818
check both @file{.} and @file{..} to see if it can find the sources.  If
3819
it finds the sources in one of these places, it should use them from
3820
there.  Otherwise, it should report that it cannot find the sources, and
3821
should exit with nonzero status.
3822
 
3823
Usually the easy way to support @samp{--srcdir} is by editing a
3824
definition of @code{VPATH} into the Makefile.  Some rules may need to
3825
refer explicitly to the specified source directory.  To make this
3826
possible, @code{configure} can add to the Makefile a variable named
3827
@code{srcdir} whose value is precisely the specified directory.
3828
 
3829
The @code{configure} script should also take an argument which specifies the
3830
type of system to build the program for.  This argument should look like
3831
this:
3832
 
3833
@example
3834
@var{cpu}-@var{company}-@var{system}
3835
@end example
3836
 
3837
For example, an Athlon-based GNU/Linux system might be
3838
@samp{i686-pc-linux-gnu}.
3839
 
3840
The @code{configure} script needs to be able to decode all plausible
3841
alternatives for how to describe a machine.  Thus,
3842
@samp{athlon-pc-gnu/linux} would be a valid alias.  There is a shell
3843
script called
3844
@uref{http://savannah.gnu.org/@/cgi-bin/@/viewcvs/@/*checkout*/@/config/@/config/@/config.sub,
3845
@file{config.sub}} that you can use as a subroutine to validate system
3846
types and canonicalize aliases.
3847
 
3848
The @code{configure} script should also take the option
3849
@option{--build=@var{buildtype}}, which should be equivalent to a
3850
plain @var{buildtype} argument.  For example, @samp{configure
3851
--build=i686-pc-linux-gnu} is equivalent to @samp{configure
3852
i686-pc-linux-gnu}.  When the build type is not specified by an option
3853
or argument, the @code{configure} script should normally guess it using
3854
the shell script
3855
@uref{http://savannah.gnu.org/@/cgi-bin/@/viewcvs/@/*checkout*/@/config/@/config/@/config.guess,
3856
@file{config.guess}}.
3857
 
3858
@cindex optional features, configure-time
3859
Other options are permitted to specify in more detail the software
3860
or hardware present on the machine, to include or exclude optional parts
3861
of the package, or to adjust the name of some tools or arguments to them:
3862
 
3863
@table @samp
3864
@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
3865
Configure the package to build and install an optional user-level
3866
facility called @var{feature}.  This allows users to choose which
3867
optional features to include.  Giving an optional @var{parameter} of
3868
@samp{no} should omit @var{feature}, if it is built by default.
3869
 
3870
No @samp{--enable} option should @strong{ever} cause one feature to
3871
replace another.  No @samp{--enable} option should ever substitute one
3872
useful behavior for another useful behavior.  The only proper use for
3873
@samp{--enable} is for questions of whether to build part of the program
3874
or exclude it.
3875
 
3876
@item --with-@var{package}
3877
@c @r{[}=@var{parameter}@r{]}
3878
The package @var{package} will be installed, so configure this package
3879
to work with @var{package}.
3880
 
3881
@c  Giving an optional @var{parameter} of
3882
@c @samp{no} should omit @var{package}, if it is used by default.
3883
 
3884
Possible values of @var{package} include
3885
@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
3886
@samp{gdb},
3887
@samp{x},
3888
and
3889
@samp{x-toolkit}.
3890
 
3891
Do not use a @samp{--with} option to specify the file name to use to
3892
find certain files.  That is outside the scope of what @samp{--with}
3893
options are for.
3894
 
3895
@item @var{variable}=@var{value}
3896
Set the value of the variable @var{variable} to @var{value}.  This is
3897
used to override the default values of commands or arguments in the
3898
build process.  For example, the user could issue @samp{configure
3899
CFLAGS=-g CXXFLAGS=-g} to build with debugging information and without
3900
the default optimization.
3901
 
3902
Specifying variables as arguments to @code{configure}, like this:
3903
@example
3904
./configure CC=gcc
3905
@end example
3906
is preferable to setting them in environment variables:
3907
@example
3908
CC=gcc ./configure
3909
@end example
3910
as it helps to recreate the same configuration later with
3911
@file{config.status}.
3912
@end table
3913
 
3914
All @code{configure} scripts should accept all of the ``detail''
3915
options and the variable settings, whether or not they make any
3916
difference to the particular package at hand.  In particular, they
3917
should accept any option that starts with @samp{--with-} or
3918
@samp{--enable-}.  This is so users will be able to configure an
3919
entire GNU source tree at once with a single set of options.
3920
 
3921
You will note that the categories @samp{--with-} and @samp{--enable-}
3922
are narrow: they @strong{do not} provide a place for any sort of option
3923
you might think of.  That is deliberate.  We want to limit the possible
3924
configuration options in GNU software.  We do not want GNU programs to
3925
have idiosyncratic configuration options.
3926
 
3927
Packages that perform part of the compilation process may support
3928
cross-compilation.  In such a case, the host and target machines for the
3929
program may be different.
3930
 
3931
The @code{configure} script should normally treat the specified type of
3932
system as both the host and the target, thus producing a program which
3933
works for the same type of machine that it runs on.
3934
 
3935
To compile a program to run on a host type that differs from the build
3936
type, use the configure option @option{--host=@var{hosttype}}, where
3937
@var{hosttype} uses the same syntax as @var{buildtype}.  The host type
3938
normally defaults to the build type.
3939
 
3940
To configure a cross-compiler, cross-assembler, or what have you, you
3941
should specify a target different from the host, using the configure
3942
option @samp{--target=@var{targettype}}.  The syntax for
3943
@var{targettype} is the same as for the host type.  So the command would
3944
look like this:
3945
 
3946
@example
3947
./configure --host=@var{hosttype} --target=@var{targettype}
3948
@end example
3949
 
3950
The target type normally defaults to the host type.
3951
Programs for which cross-operation is not meaningful need not accept the
3952
@samp{--target} option, because configuring an entire operating system for
3953
cross-operation is not a meaningful operation.
3954
 
3955
Some programs have ways of configuring themselves automatically.  If
3956
your program is set up to do this, your @code{configure} script can simply
3957
ignore most of its arguments.
3958
 
3959
@comment The makefile standards are in a separate file that is also
3960
@comment included by make.texinfo.  Done by roland@gnu.ai.mit.edu on 1/6/93.
3961
@comment For this document, turn chapters into sections, etc.
3962
@lowersections
3963
@include make-stds.texi
3964
@raisesections
3965
 
3966
@node Releases
3967
@section Making Releases
3968
@cindex packaging
3969
 
3970
You should identify each release with a pair of version numbers, a
3971
major version and a minor.  We have no objection to using more than
3972
two numbers, but it is very unlikely that you really need them.
3973
 
3974
Package the distribution of @code{Foo version 69.96} up in a gzipped tar
3975
file with the name @file{foo-69.96.tar.gz}.  It should unpack into a
3976
subdirectory named @file{foo-69.96}.
3977
 
3978
Building and installing the program should never modify any of the files
3979
contained in the distribution.  This means that all the files that form
3980
part of the program in any way must be classified into @dfn{source
3981
files} and @dfn{non-source files}.  Source files are written by humans
3982
and never changed automatically; non-source files are produced from
3983
source files by programs under the control of the Makefile.
3984
 
3985
@cindex @file{README} file
3986
The distribution should contain a file named @file{README} which gives
3987
the name of the package, and a general description of what it does.  It
3988
is also good to explain the purpose of each of the first-level
3989
subdirectories in the package, if there are any.  The @file{README} file
3990
should either state the version number of the package, or refer to where
3991
in the package it can be found.
3992
 
3993
The @file{README} file should refer to the file @file{INSTALL}, which
3994
should contain an explanation of the installation procedure.
3995
 
3996
The @file{README} file should also refer to the file which contains the
3997
copying conditions.  The GNU GPL, if used, should be in a file called
3998
@file{COPYING}.  If the GNU LGPL is used, it should be in a file called
3999
@file{COPYING.LIB}.
4000
 
4001
Naturally, all the source files must be in the distribution.  It is okay
4002
to include non-source files in the distribution, provided they are
4003
up-to-date and machine-independent, so that building the distribution
4004
normally will never modify them.  We commonly include non-source files
4005
produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
4006
unnecessary dependencies between our distributions, so that users can
4007
install whichever packages they want to install.
4008
 
4009
Non-source files that might actually be modified by building and
4010
installing the program should @strong{never} be included in the
4011
distribution.  So if you do distribute non-source files, always make
4012
sure they are up to date when you make a new distribution.
4013
 
4014
Make sure that the directory into which the distribution unpacks (as
4015
well as any subdirectories) are all world-writable (octal mode 777).
4016
This is so that old versions of @code{tar} which preserve the
4017
ownership and permissions of the files from the tar archive will be
4018
able to extract all the files even if the user is unprivileged.
4019
 
4020
Make sure that all the files in the distribution are world-readable.
4021
 
4022
Don't include any symbolic links in the distribution itself.  If the tar
4023
file contains symbolic links, then people cannot even unpack it on
4024
systems that don't support symbolic links.  Also, don't use multiple
4025
names for one file in different directories, because certain file
4026
systems cannot handle this and that prevents unpacking the
4027
distribution.
4028
 
4029
Try to make sure that all the file names will be unique on MS-DOS.  A
4030
name on MS-DOS consists of up to 8 characters, optionally followed by a
4031
period and up to three characters.  MS-DOS will truncate extra
4032
characters both before and after the period.  Thus,
4033
@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
4034
are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
4035
distinct.
4036
 
4037
@cindex @file{texinfo.tex}, in a distribution
4038
Include in your distribution a copy of the @file{texinfo.tex} you used
4039
to test print any @file{*.texinfo} or @file{*.texi} files.
4040
 
4041
Likewise, if your program uses small GNU software packages like regex,
4042
getopt, obstack, or termcap, include them in the distribution file.
4043
Leaving them out would make the distribution file a little smaller at
4044
the expense of possible inconvenience to a user who doesn't know what
4045
other files to get.
4046
 
4047
@node References
4048
@chapter References to Non-Free Software and Documentation
4049
@cindex references to non-free material
4050
 
4051
A GNU program should not recommend use of any non-free program.  We
4052
can't stop some people from writing proprietary programs, or stop
4053
other people from using them, but we can and should refuse to
4054
advertise them to new potential customers.  Proprietary software is a
4055
social and ethical problem, and the point of GNU is to solve that
4056
problem.
4057
 
4058
The GNU definition of free software is found on the GNU web site at
4059
@url{http://www.gnu.org/philosophy/free-sw.html}, and the definition
4060
of free documentation is found at
4061
@url{http://www.gnu.org/philosophy/free-doc.html}.  A list of
4062
important licenses and whether they qualify as free is in
4063
@url{http://www.gnu.org/@/licenses/@/license-list.html}.  The terms
4064
``free'' and ``non-free'', used in this document, refer to that
4065
definition.  If it is not clear whether a license qualifies as free
4066
under this definition, please ask the GNU Project by writing to
4067
@email{licensing@@gnu.org}.  We will answer, and if the license is an
4068
important one, we will add it to the list.
4069
 
4070
When a non-free program or system is well known, you can mention it in
4071
passing---that is harmless, since users who might want to use it
4072
probably already know about it.  For instance, it is fine to explain
4073
how to build your package on top of some widely used non-free
4074
operating system, or how to use it together with some widely used
4075
non-free program.
4076
 
4077
However, you should give only the necessary information to help those
4078
who already use the non-free program to use your program with
4079
it---don't give, or refer to, any further information about the
4080
proprietary program, and don't imply that the proprietary program
4081
enhances your program, or that its existence is in any way a good
4082
thing.  The goal should be that people already using the proprietary
4083
program will get the advice they need about how to use your free
4084
program with it, while people who don't already use the proprietary
4085
program will not see anything to lead them to take an interest in it.
4086
 
4087
If a non-free program or system is obscure in your program's domain,
4088
your program should not mention or support it at all, since doing so
4089
would tend to popularize the non-free program more than it popularizes
4090
your program.  (You cannot hope to find many additional users among
4091
the users of Foobar if the users of Foobar are few.)
4092
 
4093
Sometimes a program is free software in itself but depends on a
4094
non-free platform in order to run.  For instance, many Java programs
4095
depend on the parts of Sun's Java implementation which are not yet
4096
free software, and won't run on the GNU Java Compiler (which does not
4097
yet have all the features) or won't run with the GNU Java libraries.
4098
We hope this particular problem will be gone in a few months, when Sun
4099
makes the standard Java libraries free software, but of course the
4100
general principle remains: you should not recommend programs that
4101
depend on non-free software to run.
4102
 
4103
Some free programs encourage the use of non-free software.  A typical
4104
example is @command{mplayer}.  It is free software in itself, and the
4105
free code can handle some kinds of files.  However, @command{mplayer}
4106
recommends use of non-free codecs for other kinds of files, and users
4107
that install @command{mplayer} are very likely to install those codecs
4108
along with it.  To recommend @command{mplayer} is, in effect, to
4109
recommend the non-free codecs.  We must not do that, so we cannot
4110
recommend @command{mplayer} either.
4111
 
4112
In general, you should also not recommend programs that themselves
4113
strongly recommend the use of non-free software.
4114
 
4115
A GNU package should not refer the user to any non-free documentation
4116
for free software.  Free documentation that can be included in free
4117
operating systems is essential for completing the GNU system, or any
4118
free operating system, so it is a major focus of the GNU Project; to
4119
recommend use of documentation that we are not allowed to use in GNU
4120
would weaken the impetus for the community to produce documentation
4121
that we can include.  So GNU packages should never recommend non-free
4122
documentation.
4123
 
4124
By contrast, it is ok to refer to journal articles and textbooks in
4125
the comments of a program for explanation of how it functions, even
4126
though they be non-free.  This is because we don't include such things
4127
in the GNU system even if we are allowed to---they are outside the
4128
scope of an operating system project.
4129
 
4130
Referring to a web site that describes or recommends a non-free
4131
program is in effect promoting that software, so please do not make
4132
links (or mention by name) web sites that contain such material.  This
4133
policy is relevant particularly for the web pages for a GNU package.
4134
 
4135
Following links from nearly any web site can lead to non-free
4136
software; this is an inescapable aspect of the nature of the web, and
4137
in itself is no objection to linking to a site.  As long as the site
4138
does not itself recommend a non-free program, there is no need be
4139
concerned about the sites it links to for other reasons.
4140
 
4141
Thus, for example, you should not make a link to AT&T's web site,
4142
because that recommends AT&T's non-free software packages; you should
4143
not make a link to a site that links to AT&T's site saying it is a
4144
place to get a non-free program; but if a site you want to link to
4145
refers to AT&T's web site in some other context (such as long-distance
4146
telephone service), that is not a problem.
4147
 
4148
 
4149
@node GNU Free Documentation License
4150
@appendix GNU Free Documentation License
4151
 
4152
@cindex FDL, GNU Free Documentation License
4153
@include fdl.texi
4154
 
4155
@node Index
4156
@unnumbered Index
4157
@printindex cp
4158
 
4159
@bye
4160
 
4161
Local variables:
4162
eval: (add-hook 'write-file-hooks 'time-stamp)
4163
time-stamp-start: "@set lastupdate "
4164
time-stamp-end: "$"
4165
time-stamp-format: "%:b %:d, %:y"
4166
compile-command: "make just-standards"
4167
End:

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.