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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [gdb-7.2/] [etc/] [standards.info] - Blame information for rev 841

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 330 jeremybenn
This is standards.info, produced by makeinfo version 4.8 from
2
./standards.texi.
3
 
4
INFO-DIR-SECTION GNU organization
5
START-INFO-DIR-ENTRY
6
* Standards: (standards).       GNU coding standards.
7
END-INFO-DIR-ENTRY
8
 
9
   The GNU coding standards, last updated April 12, 2010.
10
 
11
   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
12
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
13
Foundation, Inc.
14
 
15
   Permission is granted to copy, distribute and/or modify this document
16
under the terms of the GNU Free Documentation License, Version 1.3 or
17
any later version published by the Free Software Foundation; with no
18
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
19
Texts.  A copy of the license is included in the section entitled "GNU
20
Free Documentation License".
21
 
22

23
File: standards.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
24
 
25
Version
26
*******
27
 
28
The GNU coding standards, last updated April 12, 2010.
29
 
30
   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
31
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
32
Foundation, Inc.
33
 
34
   Permission is granted to copy, distribute and/or modify this document
35
under the terms of the GNU Free Documentation License, Version 1.3 or
36
any later version published by the Free Software Foundation; with no
37
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
38
Texts.  A copy of the license is included in the section entitled "GNU
39
Free Documentation License".
40
 
41
* Menu:
42
 
43
* Preface::                     About the GNU Coding Standards.
44
* Legal Issues::                Keeping free software free.
45
* Design Advice::               General program design.
46
* Program Behavior::            Program behavior for all programs
47
* Writing C::                   Making the best use of C.
48
* Documentation::               Documenting programs.
49
* Managing Releases::           The release process.
50
* References::                  Mentioning non-free software or documentation.
51
* GNU Free Documentation License::  Copying and sharing this manual.
52
* Index::
53
 
54

55
File: standards.info,  Node: Preface,  Next: Legal Issues,  Prev: Top,  Up: Top
56
 
57
1 About the GNU Coding Standards
58
********************************
59
 
60
The GNU Coding Standards were written by Richard Stallman and other GNU
61
Project volunteers.  Their purpose is to make the GNU system clean,
62
consistent, and easy to install.  This document can also be read as a
63
guide to writing portable, robust and reliable programs.  It focuses on
64
programs written in C, but many of the rules and principles are useful
65
even if you write in another programming language.  The rules often
66
state reasons for writing in a certain way.
67
 
68
   If you did not obtain this file directly from the GNU project and
69
recently, please check for a newer version.  You can get the GNU Coding
70
Standards from the GNU web server in many different formats, including
71
the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
72
`http://www.gnu.org/prep/standards/'.
73
 
74
   If you are maintaining an official GNU package, in addition to this
75
document, please read and follow the GNU maintainer information (*note
76
Contents: (maintain)Top.).
77
 
78
   If you want to receive diffs for every change to these GNU documents,
79
join the mailing list `gnustandards-commit@gnu.org', via the web
80
interface at
81
`http://lists.gnu.org/mailman/listinfo/gnustandards-commit'.  Archives
82
are also available there.
83
 
84
   Please send corrections or suggestions for this document to
85
.  If you make a suggestion, please include a
86
suggested new wording for it, to help us consider the suggestion
87
efficiently.  We prefer a context diff to the Texinfo source, but if
88
that's difficult for you, you can make a context diff for some other
89
version of this document, or propose it in any way that makes it clear.
90
The source repository for this document can be found at
91
`http://savannah.gnu.org/projects/gnustandards'.
92
 
93
   These standards cover the minimum of what is important when writing a
94
GNU package.  Likely, the need for additional standards will come up.
95
Sometimes, you might suggest that such standards be added to this
96
document.  If you think your standards would be generally useful, please
97
do suggest them.
98
 
99
   You should also set standards for your package on many questions not
100
addressed or not firmly specified here.  The most important point is to
101
be self-consistent--try to stick to the conventions you pick, and try
102
to document them as much as possible.  That way, your program will be
103
more maintainable by others.
104
 
105
   The GNU Hello program serves as an example of how to follow the GNU
106
coding standards for a trivial program.
107
`http://www.gnu.org/software/hello/hello.html'.
108
 
109
   This release of the GNU Coding Standards was last updated April 12,
110
2010.
111
 
112

113
File: standards.info,  Node: Legal Issues,  Next: Design Advice,  Prev: Preface,  Up: Top
114
 
115
2 Keeping Free Software Free
116
****************************
117
 
118
This chapter discusses how you can make sure that GNU software avoids
119
legal difficulties, and other related issues.
120
 
121
* Menu:
122
 
123
* Reading Non-Free Code::       Referring to proprietary programs.
124
* Contributions::               Accepting contributions.
125
* Trademarks::                  How we deal with trademark issues.
126
 
127

128
File: standards.info,  Node: Reading Non-Free Code,  Next: Contributions,  Up: Legal Issues
129
 
130
2.1 Referring to Proprietary Programs
131
=====================================
132
 
133
Don't in any circumstances refer to Unix source code for or during your
134
work on GNU!  (Or to any other proprietary programs.)
135
 
136
   If you have a vague recollection of the internals of a Unix program,
137
this does not absolutely mean you can't write an imitation of it, but
138
do try to organize the imitation internally along different lines,
139
because this is likely to make the details of the Unix version
140
irrelevant and dissimilar to your results.
141
 
142
   For example, Unix utilities were generally optimized to minimize
143
memory use; if you go for speed instead, your program will be very
144
different.  You could keep the entire input file in memory and scan it
145
there instead of using stdio.  Use a smarter algorithm discovered more
146
recently than the Unix program.  Eliminate use of temporary files.  Do
147
it in one pass instead of two (we did this in the assembler).
148
 
149
   Or, on the contrary, emphasize simplicity instead of speed.  For some
150
applications, the speed of today's computers makes simpler algorithms
151
adequate.
152
 
153
   Or go for generality.  For example, Unix programs often have static
154
tables or fixed-size strings, which make for arbitrary limits; use
155
dynamic allocation instead.  Make sure your program handles NULs and
156
other funny characters in the input files.  Add a programming language
157
for extensibility and write part of the program in that language.
158
 
159
   Or turn some parts of the program into independently usable
160
libraries.  Or use a simple garbage collector instead of tracking
161
precisely when to free memory, or use a new GNU facility such as
162
obstacks.
163
 
164

165
File: standards.info,  Node: Contributions,  Next: Trademarks,  Prev: Reading Non-Free Code,  Up: Legal Issues
166
 
167
2.2 Accepting Contributions
168
===========================
169
 
170
If the program you are working on is copyrighted by the Free Software
171
Foundation, then when someone else sends you a piece of code to add to
172
the program, we need legal papers to use it--just as we asked you to
173
sign papers initially.  _Each_ person who makes a nontrivial
174
contribution to a program must sign some sort of legal papers in order
175
for us to have clear title to the program; the main author alone is not
176
enough.
177
 
178
   So, before adding in any contributions from other people, please tell
179
us, so we can arrange to get the papers.  Then wait until we tell you
180
that we have received the signed papers, before you actually use the
181
contribution.
182
 
183
   This applies both before you release the program and afterward.  If
184
you receive diffs to fix a bug, and they make significant changes, we
185
need legal papers for that change.
186
 
187
   This also applies to comments and documentation files.  For copyright
188
law, comments and code are just text.  Copyright applies to all kinds of
189
text, so we need legal papers for all kinds.
190
 
191
   We know it is frustrating to ask for legal papers; it's frustrating
192
for us as well.  But if you don't wait, you are going out on a limb--for
193
example, what if the contributor's employer won't sign a disclaimer?
194
You might have to take that code out again!
195
 
196
   You don't need papers for changes of a few lines here or there, since
197
they are not significant for copyright purposes.  Also, you don't need
198
papers if all you get from the suggestion is some ideas, not actual code
199
which you use.  For example, if someone sent you one implementation, but
200
you write a different implementation of the same idea, you don't need to
201
get papers.
202
 
203
   The very worst thing is if you forget to tell us about the other
204
contributor.  We could be very embarrassed in court some day as a
205
result.
206
 
207
   We have more detailed advice for maintainers of programs; if you have
208
reached the stage of actually maintaining a program for GNU (whether
209
released or not), please ask us for a copy.  It is also available
210
online for your perusal: `http://www.gnu.org/prep/maintain/'.
211
 
212

213
File: standards.info,  Node: Trademarks,  Prev: Contributions,  Up: Legal Issues
214
 
215
2.3 Trademarks
216
==============
217
 
218
Please do not include any trademark acknowledgements in GNU software
219
packages or documentation.
220
 
221
   Trademark acknowledgements are the statements that such-and-such is a
222
trademark of so-and-so.  The GNU Project has no objection to the basic
223
idea of trademarks, but these acknowledgements feel like kowtowing, and
224
there is no legal requirement for them, so we don't use them.
225
 
226
   What is legally required, as regards other people's trademarks, is to
227
avoid using them in ways which a reader might reasonably understand as
228
naming or labeling our own programs or activities.  For example, since
229
"Objective C" is (or at least was) a trademark, we made sure to say
230
that we provide a "compiler for the Objective C language" rather than
231
an "Objective C compiler".  The latter would have been meant as a
232
shorter way of saying the former, but it does not explicitly state the
233
relationship, so it could be misinterpreted as using "Objective C" as a
234
label for the compiler rather than for the language.
235
 
236
   Please don't use "win" as an abbreviation for Microsoft Windows in
237
GNU software or documentation.  In hacker terminology, calling
238
something a "win" is a form of praise.  If you wish to praise Microsoft
239
Windows when speaking on your own, by all means do so, but not in GNU
240
software.  Usually we write the name "Windows" in full, but when
241
brevity is very important (as in file names and sometimes symbol
242
names), we abbreviate it to "w".  For instance, the files and functions
243
in Emacs that deal with Windows start with `w32'.
244
 
245

246
File: standards.info,  Node: Design Advice,  Next: Program Behavior,  Prev: Legal Issues,  Up: Top
247
 
248
3 General Program Design
249
************************
250
 
251
This chapter discusses some of the issues you should take into account
252
when designing your program.
253
 
254
* Menu:
255
 
256
* Source Language::             Which languages to use.
257
* Compatibility::               Compatibility with other implementations.
258
* Using Extensions::            Using non-standard features.
259
* Standard C::                  Using standard C features.
260
* Conditional Compilation::     Compiling code only if a conditional is true.
261
 
262

263
File: standards.info,  Node: Source Language,  Next: Compatibility,  Up: Design Advice
264
 
265
3.1 Which Languages to Use
266
==========================
267
 
268
When you want to use a language that gets compiled and runs at high
269
speed, the best language to use is C.  Using another language is like
270
using a non-standard feature: it will cause trouble for users.  Even if
271
GCC supports the other language, users may find it inconvenient to have
272
to install the compiler for that other language in order to build your
273
program.  For example, if you write your program in C++, people will
274
have to install the GNU C++ compiler in order to compile your program.
275
 
276
   C has one other advantage over C++ and other compiled languages: more
277
people know C, so more people will find it easy to read and modify the
278
program if it is written in C.
279
 
280
   So in general it is much better to use C, rather than the comparable
281
alternatives.
282
 
283
   But there are two exceptions to that conclusion:
284
 
285
   * It is no problem to use another language to write a tool
286
     specifically intended for use with that language.  That is because
287
     the only people who want to build the tool will be those who have
288
     installed the other language anyway.
289
 
290
   * If an application is of interest only to a narrow part of the
291
     community, then the question of which language it is written in
292
     has less effect on other people, so you may as well please
293
     yourself.
294
 
295
   Many programs are designed to be extensible: they include an
296
interpreter for a language that is higher level than C.  Often much of
297
the program is written in that language, too.  The Emacs editor
298
pioneered this technique.
299
 
300
   The standard extensibility interpreter for GNU software is Guile
301
(`http://www.gnu.org/software/guile/'), which implements the language
302
Scheme (an especially clean and simple dialect of Lisp).  Guile also
303
includes bindings for GTK+/GNOME, making it practical to write modern
304
GUI functionality within Guile.  We don't reject programs written in
305
other "scripting languages" such as Perl and Python, but using Guile is
306
very important for the overall consistency of the GNU system.
307
 
308

309
File: standards.info,  Node: Compatibility,  Next: Using Extensions,  Prev: Source Language,  Up: Design Advice
310
 
311
3.2 Compatibility with Other Implementations
312
============================================
313
 
314
With occasional exceptions, utility programs and libraries for GNU
315
should be upward compatible with those in Berkeley Unix, and upward
316
compatible with Standard C if Standard C specifies their behavior, and
317
upward compatible with POSIX if POSIX specifies their behavior.
318
 
319
   When these standards conflict, it is useful to offer compatibility
320
modes for each of them.
321
 
322
   Standard C and POSIX prohibit many kinds of extensions.  Feel free
323
to make the extensions anyway, and include a `--ansi', `--posix', or
324
`--compatible' option to turn them off.  However, if the extension has
325
a significant chance of breaking any real programs or scripts, then it
326
is not really upward compatible.  So you should try to redesign its
327
interface to make it upward compatible.
328
 
329
   Many GNU programs suppress extensions that conflict with POSIX if the
330
environment variable `POSIXLY_CORRECT' is defined (even if it is
331
defined with a null value).  Please make your program recognize this
332
variable if appropriate.
333
 
334
   When a feature is used only by users (not by programs or command
335
files), and it is done poorly in Unix, feel free to replace it
336
completely with something totally different and better.  (For example,
337
`vi' is replaced with Emacs.)  But it is nice to offer a compatible
338
feature as well.  (There is a free `vi' clone, so we offer it.)
339
 
340
   Additional useful features are welcome regardless of whether there
341
is any precedent for them.
342
 
343

344
File: standards.info,  Node: Using Extensions,  Next: Standard C,  Prev: Compatibility,  Up: Design Advice
345
 
346
3.3 Using Non-standard Features
347
===============================
348
 
349
Many GNU facilities that already exist support a number of convenient
350
extensions over the comparable Unix facilities.  Whether to use these
351
extensions in implementing your program is a difficult question.
352
 
353
   On the one hand, using the extensions can make a cleaner program.
354
On the other hand, people will not be able to build the program unless
355
the other GNU tools are available.  This might cause the program to
356
work on fewer kinds of machines.
357
 
358
   With some extensions, it might be easy to provide both alternatives.
359
For example, you can define functions with a "keyword" `INLINE' and
360
define that as a macro to expand into either `inline' or nothing,
361
depending on the compiler.
362
 
363
   In general, perhaps it is best not to use the extensions if you can
364
straightforwardly do without them, but to use the extensions if they
365
are a big improvement.
366
 
367
   An exception to this rule are the large, established programs (such
368
as Emacs) which run on a great variety of systems.  Using GNU
369
extensions in such programs would make many users unhappy, so we don't
370
do that.
371
 
372
   Another exception is for programs that are used as part of
373
compilation: anything that must be compiled with other compilers in
374
order to bootstrap the GNU compilation facilities.  If these require
375
the GNU compiler, then no one can compile them without having them
376
installed already.  That would be extremely troublesome in certain
377
cases.
378
 
379

380
File: standards.info,  Node: Standard C,  Next: Conditional Compilation,  Prev: Using Extensions,  Up: Design Advice
381
 
382
3.4 Standard C and Pre-Standard C
383
=================================
384
 
385
1989 Standard C is widespread enough now that it is ok to use its
386
features in new programs.  There is one exception: do not ever use the
387
"trigraph" feature of Standard C.
388
 
389
   1999 Standard C is not widespread yet, so please do not require its
390
features in programs.  It is ok to use its features if they are present.
391
 
392
   However, it is easy to support pre-standard compilers in most
393
programs, so if you know how to do that, feel free.  If a program you
394
are maintaining has such support, you should try to keep it working.
395
 
396
   To support pre-standard C, instead of writing function definitions in
397
standard prototype form,
398
 
399
     int
400
     foo (int x, int y)
401
     ...
402
 
403
write the definition in pre-standard style like this,
404
 
405
     int
406
     foo (x, y)
407
          int x, y;
408
     ...
409
 
410
and use a separate declaration to specify the argument prototype:
411
 
412
     int foo (int, int);
413
 
414
   You need such a declaration anyway, in a header file, to get the
415
benefit of prototypes in all the files where the function is called.
416
And once you have the declaration, you normally lose nothing by writing
417
the function definition in the pre-standard style.
418
 
419
   This technique does not work for integer types narrower than `int'.
420
If you think of an argument as being of a type narrower than `int',
421
declare it as `int' instead.
422
 
423
   There are a few special cases where this technique is hard to use.
424
For example, if a function argument needs to hold the system type
425
`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
426
some machines; but you cannot use `int' instead, because `dev_t' is
427
wider than `int' on some machines.  There is no type you can safely use
428
on all machines in a non-standard definition.  The only way to support
429
non-standard C and pass such an argument is to check the width of
430
`dev_t' using Autoconf and choose the argument type accordingly.  This
431
may not be worth the trouble.
432
 
433
   In order to support pre-standard compilers that do not recognize
434
prototypes, you may want to use a preprocessor macro like this:
435
 
436
     /* Declare the prototype for a general external function.  */
437
     #if defined (__STDC__) || defined (WINDOWSNT)
438
     #define P_(proto) proto
439
     #else
440
     #define P_(proto) ()
441
     #endif
442
 
443

444
File: standards.info,  Node: Conditional Compilation,  Prev: Standard C,  Up: Design Advice
445
 
446
3.5 Conditional Compilation
447
===========================
448
 
449
When supporting configuration options already known when building your
450
program we prefer using `if (... )' over conditional compilation, as in
451
the former case the compiler is able to perform more extensive checking
452
of all possible code paths.
453
 
454
   For example, please write
455
 
456
       if (HAS_FOO)
457
         ...
458
       else
459
         ...
460
 
461
instead of:
462
 
463
       #ifdef HAS_FOO
464
         ...
465
       #else
466
         ...
467
       #endif
468
 
469
   A modern compiler such as GCC will generate exactly the same code in
470
both cases, and we have been using similar techniques with good success
471
in several projects.  Of course, the former method assumes that
472
`HAS_FOO' is defined as either 0 or 1.
473
 
474
   While this is not a silver bullet solving all portability problems,
475
and is not always appropriate, following this policy would have saved
476
GCC developers many hours, or even days, per year.
477
 
478
   In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
479
which cannot be simply used in `if (...)' statements, there is an easy
480
workaround.  Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
481
in the following example:
482
 
483
       #ifdef REVERSIBLE_CC_MODE
484
       #define HAS_REVERSIBLE_CC_MODE 1
485
       #else
486
       #define HAS_REVERSIBLE_CC_MODE 0
487
       #endif
488
 
489

490
File: standards.info,  Node: Program Behavior,  Next: Writing C,  Prev: Design Advice,  Up: Top
491
 
492
4 Program Behavior for All Programs
493
***********************************
494
 
495
This chapter describes conventions for writing robust software.  It
496
also describes general standards for error messages, the command line
497
interface, and how libraries should behave.
498
 
499
* Menu:
500
 
501
* Non-GNU Standards::           We consider standards such as POSIX;
502
                                  we don't "obey" them.
503
* Semantics::                   Writing robust programs.
504
* Libraries::                   Library behavior.
505
* Errors::                      Formatting error messages.
506
* User Interfaces::             Standards about interfaces generally.
507
* Graphical Interfaces::        Standards for graphical interfaces.
508
* Command-Line Interfaces::     Standards for command line interfaces.
509
* Option Table::                Table of long options.
510
* OID Allocations::             Table of OID slots for GNU.
511
* Memory Usage::                When and how to care about memory needs.
512
* File Usage::                  Which files to use, and where.
513
 
514

515
File: standards.info,  Node: Non-GNU Standards,  Next: Semantics,  Up: Program Behavior
516
 
517
4.1 Non-GNU Standards
518
=====================
519
 
520
The GNU Project regards standards published by other organizations as
521
suggestions, not orders.  We consider those standards, but we do not
522
"obey" them.  In developing a GNU program, you should implement an
523
outside standard's specifications when that makes the GNU system better
524
overall in an objective sense.  When it doesn't, you shouldn't.
525
 
526
   In most cases, following published standards is convenient for
527
users--it means that their programs or scripts will work more portably.
528
For instance, GCC implements nearly all the features of Standard C as
529
specified by that standard.  C program developers would be unhappy if
530
it did not.  And GNU utilities mostly follow specifications of POSIX.2;
531
shell script writers and users would be unhappy if our programs were
532
incompatible.
533
 
534
   But we do not follow either of these specifications rigidly, and
535
there are specific points on which we decided not to follow them, so as
536
to make the GNU system better for users.
537
 
538
   For instance, Standard C says that nearly all extensions to C are
539
prohibited.  How silly!  GCC implements many extensions, some of which
540
were later adopted as part of the standard.  If you want these
541
constructs to give an error message as "required" by the standard, you
542
must specify `--pedantic', which was implemented only so that we can
543
say "GCC is a 100% implementation of the standard," not because there
544
is any reason to actually use it.
545
 
546
   POSIX.2 specifies that `df' and `du' must output sizes by default in
547
units of 512 bytes.  What users want is units of 1k, so that is what we
548
do by default.  If you want the ridiculous behavior "required" by
549
POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
550
was originally going to be named `POSIX_ME_HARDER').
551
 
552
   GNU utilities also depart from the letter of the POSIX.2
553
specification when they support long-named command-line options, and
554
intermixing options with ordinary arguments.  This minor
555
incompatibility with POSIX is never a problem in practice, and it is
556
very useful.
557
 
558
   In particular, don't reject a new feature, or remove an old one,
559
merely because a standard says it is "forbidden" or "deprecated."
560
 
561

562
File: standards.info,  Node: Semantics,  Next: Libraries,  Prev: Non-GNU Standards,  Up: Program Behavior
563
 
564
4.2 Writing Robust Programs
565
===========================
566
 
567
Avoid arbitrary limits on the length or number of _any_ data structure,
568
including file names, lines, files, and symbols, by allocating all data
569
structures dynamically.  In most Unix utilities, "long lines are
570
silently truncated".  This is not acceptable in a GNU utility.
571
 
572
   Utilities reading files should not drop NUL characters, or any other
573
nonprinting characters _including those with codes above 0177_.  The
574
only sensible exceptions would be utilities specifically intended for
575
interface to certain types of terminals or printers that can't handle
576
those characters.  Whenever possible, try to make programs work
577
properly with sequences of bytes that represent multibyte characters,
578
using encodings such as UTF-8 and others.
579
 
580
   Check every system call for an error return, unless you know you
581
wish to ignore errors.  Include the system error text (from `perror' or
582
equivalent) in _every_ error message resulting from a failing system
583
call, as well as the name of the file if any and the name of the
584
utility.  Just "cannot open foo.c" or "stat failed" is not sufficient.
585
 
586
   Check every call to `malloc' or `realloc' to see if it returned
587
zero.  Check `realloc' even if you are making the block smaller; in a
588
system that rounds block sizes to a power of 2, `realloc' may get a
589
different block if you ask for less space.
590
 
591
   In Unix, `realloc' can destroy the storage block if it returns zero.
592
GNU `realloc' does not have this bug: if it fails, the original block
593
is unchanged.  Feel free to assume the bug is fixed.  If you wish to
594
run your program on Unix, and wish to avoid lossage in this case, you
595
can use the GNU `malloc'.
596
 
597
   You must expect `free' to alter the contents of the block that was
598
freed.  Anything you want to fetch from the block, you must fetch before
599
calling `free'.
600
 
601
   If `malloc' fails in a noninteractive program, make that a fatal
602
error.  In an interactive program (one that reads commands from the
603
user), it is better to abort the command and return to the command
604
reader loop.  This allows the user to kill other processes to free up
605
virtual memory, and then try the command again.
606
 
607
   Use `getopt_long' to decode arguments, unless the argument syntax
608
makes this unreasonable.
609
 
610
   When static storage is to be written in during program execution, use
611
explicit C code to initialize it.  Reserve C initialized declarations
612
for data that will not be changed.
613
 
614
   Try to avoid low-level interfaces to obscure Unix data structures
615
(such as file directories, utmp, or the layout of kernel memory), since
616
these are less likely to work compatibly.  If you need to find all the
617
files in a directory, use `readdir' or some other high-level interface.
618
These are supported compatibly by GNU.
619
 
620
   The preferred signal handling facilities are the BSD variant of
621
`signal', and the POSIX `sigaction' function; the alternative USG
622
`signal' interface is an inferior design.
623
 
624
   Nowadays, using the POSIX signal functions may be the easiest way to
625
make a program portable.  If you use `signal', then on GNU/Linux
626
systems running GNU libc version 1, you should include `bsd/signal.h'
627
instead of `signal.h', so as to get BSD behavior.  It is up to you
628
whether to support systems where `signal' has only the USG behavior, or
629
give up on them.
630
 
631
   In error checks that detect "impossible" conditions, just abort.
632
There is usually no point in printing any message.  These checks
633
indicate the existence of bugs.  Whoever wants to fix the bugs will have
634
to read the source code and run a debugger.  So explain the problem with
635
comments in the source.  The relevant data will be in variables, which
636
are easy to examine with the debugger, so there is no point moving them
637
elsewhere.
638
 
639
   Do not use a count of errors as the exit status for a program.
640
_That does not work_, because exit status values are limited to 8 bits
641
(0 through 255).  A single run of the program might have 256 errors; if
642
you try to return 256 as the exit status, the parent process will see 0
643
as the status, and it will appear that the program succeeded.
644
 
645
   If you make temporary files, check the `TMPDIR' environment
646
variable; if that variable is defined, use the specified directory
647
instead of `/tmp'.
648
 
649
   In addition, be aware that there is a possible security problem when
650
creating temporary files in world-writable directories.  In C, you can
651
avoid this problem by creating temporary files in this manner:
652
 
653
     fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
654
 
655
or by using the `mkstemps' function from libiberty.
656
 
657
   In bash, use `set -C' to avoid this problem.
658
 
659

660
File: standards.info,  Node: Libraries,  Next: Errors,  Prev: Semantics,  Up: Program Behavior
661
 
662
4.3 Library Behavior
663
====================
664
 
665
Try to make library functions reentrant.  If they need to do dynamic
666
storage allocation, at least try to avoid any nonreentrancy aside from
667
that of `malloc' itself.
668
 
669
   Here are certain name conventions for libraries, to avoid name
670
conflicts.
671
 
672
   Choose a name prefix for the library, more than two characters long.
673
All external function and variable names should start with this prefix.
674
In addition, there should only be one of these in any given library
675
member.  This usually means putting each one in a separate source file.
676
 
677
   An exception can be made when two external symbols are always used
678
together, so that no reasonable program could use one without the
679
other; then they can both go in the same file.
680
 
681
   External symbols that are not documented entry points for the user
682
should have names beginning with `_'.  The `_' should be followed by
683
the chosen name prefix for the library, to prevent collisions with
684
other libraries.  These can go in the same files with user entry points
685
if you like.
686
 
687
   Static functions and variables can be used as you like and need not
688
fit any naming convention.
689
 
690

691
File: standards.info,  Node: Errors,  Next: User Interfaces,  Prev: Libraries,  Up: Program Behavior
692
 
693
4.4 Formatting Error Messages
694
=============================
695
 
696
Error messages from compilers should look like this:
697
 
698
     SOURCE-FILE-NAME:LINENO: MESSAGE
699
 
700
If you want to mention the column number, use one of these formats:
701
 
702
     SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
703
     SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE
704
 
705
Line numbers should start from 1 at the beginning of the file, and
706
column numbers should start from 1 at the beginning of the line.  (Both
707
of these conventions are chosen for compatibility.)  Calculate column
708
numbers assuming that space and all ASCII printing characters have
709
equal width, and assuming tab stops every 8 columns.
710
 
711
   The error message can also give both the starting and ending
712
positions of the erroneous text.  There are several formats so that you
713
can avoid redundant information such as a duplicate line number.  Here
714
are the possible formats:
715
 
716
     SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE
717
     SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE
718
     SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE
719
 
720
When an error is spread over several files, you can use this format:
721
 
722
     FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE
723
 
724
   Error messages from other noninteractive programs should look like
725
this:
726
 
727
     PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
728
 
729
when there is an appropriate source file, or like this:
730
 
731
     PROGRAM: MESSAGE
732
 
733
when there is no relevant source file.
734
 
735
   If you want to mention the column number, use this format:
736
 
737
     PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
738
 
739
   In an interactive program (one that is reading commands from a
740
terminal), it is better not to include the program name in an error
741
message.  The place to indicate which program is running is in the
742
prompt or with the screen layout.  (When the same program runs with
743
input from a source other than a terminal, it is not interactive and
744
would do best to print error messages using the noninteractive style.)
745
 
746
   The string MESSAGE should not begin with a capital letter when it
747
follows a program name and/or file name, because that isn't the
748
beginning of a sentence.  (The sentence conceptually starts at the
749
beginning of the line.)  Also, it should not end with a period.
750
 
751
   Error messages from interactive programs, and other messages such as
752
usage messages, should start with a capital letter.  But they should not
753
end with a period.
754
 
755

756
File: standards.info,  Node: User Interfaces,  Next: Graphical Interfaces,  Prev: Errors,  Up: Program Behavior
757
 
758
4.5 Standards for Interfaces Generally
759
======================================
760
 
761
Please don't make the behavior of a utility depend on the name used to
762
invoke it.  It is useful sometimes to make a link to a utility with a
763
different name, and that should not change what it does.
764
 
765
   Instead, use a run time option or a compilation switch or both to
766
select among the alternate behaviors.
767
 
768
   Likewise, please don't make the behavior of the program depend on the
769
type of output device it is used with.  Device independence is an
770
important principle of the system's design; do not compromise it merely
771
to save someone from typing an option now and then.  (Variation in error
772
message syntax when using a terminal is ok, because that is a side issue
773
that people do not depend on.)
774
 
775
   If you think one behavior is most useful when the output is to a
776
terminal, and another is most useful when the output is a file or a
777
pipe, then it is usually best to make the default behavior the one that
778
is useful with output to a terminal, and have an option for the other
779
behavior.
780
 
781
   Compatibility requires certain programs to depend on the type of
782
output device.  It would be disastrous if `ls' or `sh' did not do so in
783
the way all users expect.  In some of these cases, we supplement the
784
program with a preferred alternate version that does not depend on the
785
output device type.  For example, we provide a `dir' program much like
786
`ls' except that its default output format is always multi-column
787
format.
788
 
789

790
File: standards.info,  Node: Graphical Interfaces,  Next: Command-Line Interfaces,  Prev: User Interfaces,  Up: Program Behavior
791
 
792
4.6 Standards for Graphical Interfaces
793
======================================
794
 
795
When you write a program that provides a graphical user interface,
796
please make it work with the X Window System and the GTK+ toolkit
797
unless the functionality specifically requires some alternative (for
798
example, "displaying jpeg images while in console mode").
799
 
800
   In addition, please provide a command-line interface to control the
801
functionality.  (In many cases, the graphical user interface can be a
802
separate program which invokes the command-line program.)  This is so
803
that the same jobs can be done from scripts.
804
 
805
   Please also consider providing a D-bus interface for use from other
806
running programs, such as within GNOME.  (GNOME used to use CORBA for
807
this, but that is being phased out.)  In addition, consider providing a
808
library interface (for use from C), and perhaps a keyboard-driven
809
console interface (for use by users from console mode).  Once you are
810
doing the work to provide the functionality and the graphical
811
interface, these won't be much extra work.
812
 
813

814
File: standards.info,  Node: Command-Line Interfaces,  Next: Option Table,  Prev: Graphical Interfaces,  Up: Program Behavior
815
 
816
4.7 Standards for Command Line Interfaces
817
=========================================
818
 
819
It is a good idea to follow the POSIX guidelines for the command-line
820
options of a program.  The easiest way to do this is to use `getopt' to
821
parse them.  Note that the GNU version of `getopt' will normally permit
822
options anywhere among the arguments unless the special argument `--'
823
is used.  This is not what POSIX specifies; it is a GNU extension.
824
 
825
   Please define long-named options that are equivalent to the
826
single-letter Unix-style options.  We hope to make GNU more user
827
friendly this way.  This is easy to do with the GNU function
828
`getopt_long'.
829
 
830
   One of the advantages of long-named options is that they can be
831
consistent from program to program.  For example, users should be able
832
to expect the "verbose" option of any GNU program which has one, to be
833
spelled precisely `--verbose'.  To achieve this uniformity, look at the
834
table of common long-option names when you choose the option names for
835
your program (*note Option Table::).
836
 
837
   It is usually a good idea for file names given as ordinary arguments
838
to be input files only; any output files would be specified using
839
options (preferably `-o' or `--output').  Even if you allow an output
840
file name as an ordinary argument for compatibility, try to provide an
841
option as another way to specify it.  This will lead to more consistency
842
among GNU utilities, and fewer idiosyncrasies for users to remember.
843
 
844
   All programs should support two standard options: `--version' and
845
`--help'.  CGI programs should accept these as command-line options,
846
and also if given as the `PATH_INFO'; for instance, visiting
847
`http://example.org/p.cgi/--help' in a browser should output the same
848
information as invoking `p.cgi --help' from the command line.
849
 
850
* Menu:
851
 
852
* --version::       The standard output for --version.
853
* --help::          The standard output for --help.
854
 
855

856
File: standards.info,  Node: --version,  Next: --help,  Up: Command-Line Interfaces
857
 
858
4.7.1 `--version'
859
-----------------
860
 
861
The standard `--version' option should direct the program to print
862
information about its name, version, origin and legal status, all on
863
standard output, and then exit successfully.  Other options and
864
arguments should be ignored once this is seen, and the program should
865
not perform its normal function.
866
 
867
   The first line is meant to be easy for a program to parse; the
868
version number proper starts after the last space.  In addition, it
869
contains the canonical name for this program, in this format:
870
 
871
     GNU Emacs 19.30
872
 
873
The program's name should be a constant string; _don't_ compute it from
874
`argv[0]'.  The idea is to state the standard or canonical name for the
875
program, not its file name.  There are other ways to find out the
876
precise file name where a command is found in `PATH'.
877
 
878
   If the program is a subsidiary part of a larger package, mention the
879
package name in parentheses, like this:
880
 
881
     emacsserver (GNU Emacs) 19.30
882
 
883
If the package has a version number which is different from this
884
program's version number, you can mention the package version number
885
just before the close-parenthesis.
886
 
887
   If you _need_ to mention the version numbers of libraries which are
888
distributed separately from the package which contains this program,
889
you can do so by printing an additional line of version info for each
890
library you want to mention.  Use the same format for these lines as for
891
the first line.
892
 
893
   Please do not mention all of the libraries that the program uses
894
"just for completeness"--that would produce a lot of unhelpful clutter.
895
Please mention library version numbers only if you find in practice that
896
they are very important to you in debugging.
897
 
898
   The following line, after the version number line or lines, should
899
be a copyright notice.  If more than one copyright notice is called
900
for, put each on a separate line.
901
 
902
   Next should follow a line stating the license, preferably using one
903
of abbrevations below, and a brief statement that the program is free
904
software, and that users are free to copy and change it.  Also mention
905
that there is no warranty, to the extent permitted by law.  See
906
recommended wording below.
907
 
908
   It is ok to finish the output with a list of the major authors of the
909
program, as a way of giving credit.
910
 
911
   Here's an example of output that follows these rules:
912
 
913
     GNU hello 2.3
914
     Copyright (C) 2007 Free Software Foundation, Inc.
915
     License GPLv3+: GNU GPL version 3 or later 
916
     This is free software: you are free to change and redistribute it.
917
     There is NO WARRANTY, to the extent permitted by law.
918
 
919
   You should adapt this to your program, of course, filling in the
920
proper year, copyright holder, name of program, and the references to
921
distribution terms, and changing the rest of the wording as necessary.
922
 
923
   This copyright notice only needs to mention the most recent year in
924
which changes were made--there's no need to list the years for previous
925
versions' changes.  You don't have to mention the name of the program in
926
these notices, if that is inconvenient, since it appeared in the first
927
line.  (The rules are different for copyright notices in source files;
928
*note Copyright Notices: (maintain)Copyright Notices.)
929
 
930
   Translations of the above lines must preserve the validity of the
931
copyright notices (*note Internationalization::).  If the translation's
932
character set supports it, the `(C)' should be replaced with the
933
copyright symbol, as follows:
934
 
935
   (the official copyright symbol, which is the letter C in a circle);
936
 
937
   Write the word "Copyright" exactly like that, in English.  Do not
938
translate it into another language.  International treaties recognize
939
the English word "Copyright"; translations into other languages do not
940
have legal significance.
941
 
942
   Finally, here is the table of our suggested license abbreviations.
943
Any abbreviation can be followed by `vVERSION[+]', meaning that
944
particular version, or later versions with the `+', as shown above.
945
 
946
   In the case of exceptions for extra permissions with the GPL, we use
947
`/' for a separator; the version number can follow the license
948
abbreviation as usual, as in the examples below.
949
 
950
GPL
951
     GNU General Public License, `http://www.gnu.org/licenses/gpl.html'.
952
 
953
LGPL
954
     GNU Lesser General Public License,
955
     `http://www.gnu.org/licenses/lgpl.html'.
956
 
957
GPL/Ada
958
     GNU GPL with the exception for Ada.
959
 
960
Apache
961
     The Apache Software Foundation license,
962
     `http://www.apache.org/licenses'.
963
 
964
Artistic
965
     The Artistic license used for Perl,
966
     `http://www.perlfoundation.org/legal'.
967
 
968
Expat
969
     The Expat license, `http://www.jclark.com/xml/copying.txt'.
970
 
971
MPL
972
     The Mozilla Public License, `http://www.mozilla.org/MPL/'.
973
 
974
OBSD
975
     The original (4-clause) BSD license, incompatible with the GNU GPL
976
     `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'.
977
 
978
PHP
979
     The license used for PHP, `http://www.php.net/license/'.
980
 
981
public domain
982
     The non-license that is being in the public domain,
983
     `http://www.gnu.org/licenses/license-list.html#PublicDomain'.
984
 
985
Python
986
     The license for Python, `http://www.python.org/2.0.1/license.html'.
987
 
988
RBSD
989
     The revised (3-clause) BSD, compatible with the GNU GPL,
990
     `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'.
991
 
992
X11
993
     The simple non-copyleft license used for most versions of the X
994
     Window System, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'.
995
 
996
Zlib
997
     The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'.
998
 
999
 
1000
   More information about these licenses and many more are on the GNU
1001
licensing web pages, `http://www.gnu.org/licenses/license-list.html'.
1002
 
1003

1004
File: standards.info,  Node: --help,  Prev: --version,  Up: Command-Line Interfaces
1005
 
1006
4.7.2 `--help'
1007
--------------
1008
 
1009
The standard `--help' option should output brief documentation for how
1010
to invoke the program, on standard output, then exit successfully.
1011
Other options and arguments should be ignored once this is seen, and
1012
the program should not perform its normal function.
1013
 
1014
   Near the end of the `--help' option's output, please place lines
1015
giving the email address for bug reports, the package's home page
1016
(normally , and the general page for
1017
help using GNU programs.  The format should be like this:
1018
 
1019
     Report bugs to: MAILING-ADDRESS
1020
     PKG home page: 
1021
     General help using GNU software: 
1022
 
1023
   It is ok to mention other appropriate mailing lists and web pages.
1024
 
1025

1026
File: standards.info,  Node: Option Table,  Next: OID Allocations,  Prev: Command-Line Interfaces,  Up: Program Behavior
1027
 
1028
4.8 Table of Long Options
1029
=========================
1030
 
1031
Here is a table of long options used by GNU programs.  It is surely
1032
incomplete, but we aim to list all the options that a new program might
1033
want to be compatible with.  If you use names not already in the table,
1034
please send  a list of them, with their
1035
meanings, so we can update the table.
1036
 
1037
`after-date'
1038
     `-N' in `tar'.
1039
 
1040
`all'
1041
     `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
1042
 
1043
`all-text'
1044
     `-a' in `diff'.
1045
 
1046
`almost-all'
1047
     `-A' in `ls'.
1048
 
1049
`append'
1050
     `-a' in `etags', `tee', `time'; `-r' in `tar'.
1051
 
1052
`archive'
1053
     `-a' in `cp'.
1054
 
1055
`archive-name'
1056
     `-n' in `shar'.
1057
 
1058
`arglength'
1059
     `-l' in `m4'.
1060
 
1061
`ascii'
1062
     `-a' in `diff'.
1063
 
1064
`assign'
1065
     `-v' in `gawk'.
1066
 
1067
`assume-new'
1068
     `-W' in `make'.
1069
 
1070
`assume-old'
1071
     `-o' in `make'.
1072
 
1073
`auto-check'
1074
     `-a' in `recode'.
1075
 
1076
`auto-pager'
1077
     `-a' in `wdiff'.
1078
 
1079
`auto-reference'
1080
     `-A' in `ptx'.
1081
 
1082
`avoid-wraps'
1083
     `-n' in `wdiff'.
1084
 
1085
`background'
1086
     For server programs, run in the background.
1087
 
1088
`backward-search'
1089
     `-B' in `ctags'.
1090
 
1091
`basename'
1092
     `-f' in `shar'.
1093
 
1094
`batch'
1095
     Used in GDB.
1096
 
1097
`baud'
1098
     Used in GDB.
1099
 
1100
`before'
1101
     `-b' in `tac'.
1102
 
1103
`binary'
1104
     `-b' in `cpio' and `diff'.
1105
 
1106
`bits-per-code'
1107
     `-b' in `shar'.
1108
 
1109
`block-size'
1110
     Used in `cpio' and `tar'.
1111
 
1112
`blocks'
1113
     `-b' in `head' and `tail'.
1114
 
1115
`break-file'
1116
     `-b' in `ptx'.
1117
 
1118
`brief'
1119
     Used in various programs to make output shorter.
1120
 
1121
`bytes'
1122
     `-c' in `head', `split', and `tail'.
1123
 
1124
`c++'
1125
     `-C' in `etags'.
1126
 
1127
`catenate'
1128
     `-A' in `tar'.
1129
 
1130
`cd'
1131
     Used in various programs to specify the directory to use.
1132
 
1133
`changes'
1134
     `-c' in `chgrp' and `chown'.
1135
 
1136
`classify'
1137
     `-F' in `ls'.
1138
 
1139
`colons'
1140
     `-c' in `recode'.
1141
 
1142
`command'
1143
     `-c' in `su'; `-x' in GDB.
1144
 
1145
`compare'
1146
     `-d' in `tar'.
1147
 
1148
`compat'
1149
     Used in `gawk'.
1150
 
1151
`compress'
1152
     `-Z' in `tar' and `shar'.
1153
 
1154
`concatenate'
1155
     `-A' in `tar'.
1156
 
1157
`confirmation'
1158
     `-w' in `tar'.
1159
 
1160
`context'
1161
     Used in `diff'.
1162
 
1163
`copyleft'
1164
     `-W copyleft' in `gawk'.
1165
 
1166
`copyright'
1167
     `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
1168
 
1169
`core'
1170
     Used in GDB.
1171
 
1172
`count'
1173
     `-q' in `who'.
1174
 
1175
`count-links'
1176
     `-l' in `du'.
1177
 
1178
`create'
1179
     Used in `tar' and `cpio'.
1180
 
1181
`cut-mark'
1182
     `-c' in `shar'.
1183
 
1184
`cxref'
1185
     `-x' in `ctags'.
1186
 
1187
`date'
1188
     `-d' in `touch'.
1189
 
1190
`debug'
1191
     `-d' in `make' and `m4'; `-t' in Bison.
1192
 
1193
`define'
1194
     `-D' in `m4'.
1195
 
1196
`defines'
1197
     `-d' in Bison and `ctags'.
1198
 
1199
`delete'
1200
     `-D' in `tar'.
1201
 
1202
`dereference'
1203
     `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
1204
 
1205
`dereference-args'
1206
     `-D' in `du'.
1207
 
1208
`device'
1209
     Specify an I/O device (special file name).
1210
 
1211
`diacritics'
1212
     `-d' in `recode'.
1213
 
1214
`dictionary-order'
1215
     `-d' in `look'.
1216
 
1217
`diff'
1218
     `-d' in `tar'.
1219
 
1220
`digits'
1221
     `-n' in `csplit'.
1222
 
1223
`directory'
1224
     Specify the directory to use, in various programs.  In `ls', it
1225
     means to show directories themselves rather than their contents.
1226
     In `rm' and `ln', it means to not treat links to directories
1227
     specially.
1228
 
1229
`discard-all'
1230
     `-x' in `strip'.
1231
 
1232
`discard-locals'
1233
     `-X' in `strip'.
1234
 
1235
`dry-run'
1236
     `-n' in `make'.
1237
 
1238
`ed'
1239
     `-e' in `diff'.
1240
 
1241
`elide-empty-files'
1242
     `-z' in `csplit'.
1243
 
1244
`end-delete'
1245
     `-x' in `wdiff'.
1246
 
1247
`end-insert'
1248
     `-z' in `wdiff'.
1249
 
1250
`entire-new-file'
1251
     `-N' in `diff'.
1252
 
1253
`environment-overrides'
1254
     `-e' in `make'.
1255
 
1256
`eof'
1257
     `-e' in `xargs'.
1258
 
1259
`epoch'
1260
     Used in GDB.
1261
 
1262
`error-limit'
1263
     Used in `makeinfo'.
1264
 
1265
`error-output'
1266
     `-o' in `m4'.
1267
 
1268
`escape'
1269
     `-b' in `ls'.
1270
 
1271
`exclude-from'
1272
     `-X' in `tar'.
1273
 
1274
`exec'
1275
     Used in GDB.
1276
 
1277
`exit'
1278
     `-x' in `xargs'.
1279
 
1280
`exit-0'
1281
     `-e' in `unshar'.
1282
 
1283
`expand-tabs'
1284
     `-t' in `diff'.
1285
 
1286
`expression'
1287
     `-e' in `sed'.
1288
 
1289
`extern-only'
1290
     `-g' in `nm'.
1291
 
1292
`extract'
1293
     `-i' in `cpio'; `-x' in `tar'.
1294
 
1295
`faces'
1296
     `-f' in `finger'.
1297
 
1298
`fast'
1299
     `-f' in `su'.
1300
 
1301
`fatal-warnings'
1302
     `-E' in `m4'.
1303
 
1304
`file'
1305
     `-f' in `gawk', `info', `make', `mt', `sed', and `tar'.
1306
 
1307
`field-separator'
1308
     `-F' in `gawk'.
1309
 
1310
`file-prefix'
1311
     `-b' in Bison.
1312
 
1313
`file-type'
1314
     `-F' in `ls'.
1315
 
1316
`files-from'
1317
     `-T' in `tar'.
1318
 
1319
`fill-column'
1320
     Used in `makeinfo'.
1321
 
1322
`flag-truncation'
1323
     `-F' in `ptx'.
1324
 
1325
`fixed-output-files'
1326
     `-y' in Bison.
1327
 
1328
`follow'
1329
     `-f' in `tail'.
1330
 
1331
`footnote-style'
1332
     Used in `makeinfo'.
1333
 
1334
`force'
1335
     `-f' in `cp', `ln', `mv', and `rm'.
1336
 
1337
`force-prefix'
1338
     `-F' in `shar'.
1339
 
1340
`foreground'
1341
     For server programs, run in the foreground; in other words, don't
1342
     do anything special to run the server in the background.
1343
 
1344
`format'
1345
     Used in `ls', `time', and `ptx'.
1346
 
1347
`freeze-state'
1348
     `-F' in `m4'.
1349
 
1350
`fullname'
1351
     Used in GDB.
1352
 
1353
`gap-size'
1354
     `-g' in `ptx'.
1355
 
1356
`get'
1357
     `-x' in `tar'.
1358
 
1359
`graphic'
1360
     `-i' in `ul'.
1361
 
1362
`graphics'
1363
     `-g' in `recode'.
1364
 
1365
`group'
1366
     `-g' in `install'.
1367
 
1368
`gzip'
1369
     `-z' in `tar' and `shar'.
1370
 
1371
`hashsize'
1372
     `-H' in `m4'.
1373
 
1374
`header'
1375
     `-h' in `objdump' and `recode'
1376
 
1377
`heading'
1378
     `-H' in `who'.
1379
 
1380
`help'
1381
     Used to ask for brief usage information.
1382
 
1383
`here-delimiter'
1384
     `-d' in `shar'.
1385
 
1386
`hide-control-chars'
1387
     `-q' in `ls'.
1388
 
1389
`html'
1390
     In `makeinfo', output HTML.
1391
 
1392
`idle'
1393
     `-u' in `who'.
1394
 
1395
`ifdef'
1396
     `-D' in `diff'.
1397
 
1398
`ignore'
1399
     `-I' in `ls'; `-x' in `recode'.
1400
 
1401
`ignore-all-space'
1402
     `-w' in `diff'.
1403
 
1404
`ignore-backups'
1405
     `-B' in `ls'.
1406
 
1407
`ignore-blank-lines'
1408
     `-B' in `diff'.
1409
 
1410
`ignore-case'
1411
     `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
1412
 
1413
`ignore-errors'
1414
     `-i' in `make'.
1415
 
1416
`ignore-file'
1417
     `-i' in `ptx'.
1418
 
1419
`ignore-indentation'
1420
     `-I' in `etags'.
1421
 
1422
`ignore-init-file'
1423
     `-f' in Oleo.
1424
 
1425
`ignore-interrupts'
1426
     `-i' in `tee'.
1427
 
1428
`ignore-matching-lines'
1429
     `-I' in `diff'.
1430
 
1431
`ignore-space-change'
1432
     `-b' in `diff'.
1433
 
1434
`ignore-zeros'
1435
     `-i' in `tar'.
1436
 
1437
`include'
1438
     `-i' in `etags'; `-I' in `m4'.
1439
 
1440
`include-dir'
1441
     `-I' in `make'.
1442
 
1443
`incremental'
1444
     `-G' in `tar'.
1445
 
1446
`info'
1447
     `-i', `-l', and `-m' in Finger.
1448
 
1449
`init-file'
1450
     In some programs, specify the name of the file to read as the
1451
     user's init file.
1452
 
1453
`initial'
1454
     `-i' in `expand'.
1455
 
1456
`initial-tab'
1457
     `-T' in `diff'.
1458
 
1459
`inode'
1460
     `-i' in `ls'.
1461
 
1462
`interactive'
1463
     `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
1464
     `-w' in `tar'.
1465
 
1466
`intermix-type'
1467
     `-p' in `shar'.
1468
 
1469
`iso-8601'
1470
     Used in `date'
1471
 
1472
`jobs'
1473
     `-j' in `make'.
1474
 
1475
`just-print'
1476
     `-n' in `make'.
1477
 
1478
`keep-going'
1479
     `-k' in `make'.
1480
 
1481
`keep-files'
1482
     `-k' in `csplit'.
1483
 
1484
`kilobytes'
1485
     `-k' in `du' and `ls'.
1486
 
1487
`language'
1488
     `-l' in `etags'.
1489
 
1490
`less-mode'
1491
     `-l' in `wdiff'.
1492
 
1493
`level-for-gzip'
1494
     `-g' in `shar'.
1495
 
1496
`line-bytes'
1497
     `-C' in `split'.
1498
 
1499
`lines'
1500
     Used in `split', `head', and `tail'.
1501
 
1502
`link'
1503
     `-l' in `cpio'.
1504
 
1505
`lint'
1506
`lint-old'
1507
     Used in `gawk'.
1508
 
1509
`list'
1510
     `-t' in `cpio'; `-l' in `recode'.
1511
 
1512
`list'
1513
     `-t' in `tar'.
1514
 
1515
`literal'
1516
     `-N' in `ls'.
1517
 
1518
`load-average'
1519
     `-l' in `make'.
1520
 
1521
`login'
1522
     Used in `su'.
1523
 
1524
`machine'
1525
     Used in `uname'.
1526
 
1527
`macro-name'
1528
     `-M' in `ptx'.
1529
 
1530
`mail'
1531
     `-m' in `hello' and `uname'.
1532
 
1533
`make-directories'
1534
     `-d' in `cpio'.
1535
 
1536
`makefile'
1537
     `-f' in `make'.
1538
 
1539
`mapped'
1540
     Used in GDB.
1541
 
1542
`max-args'
1543
     `-n' in `xargs'.
1544
 
1545
`max-chars'
1546
     `-n' in `xargs'.
1547
 
1548
`max-lines'
1549
     `-l' in `xargs'.
1550
 
1551
`max-load'
1552
     `-l' in `make'.
1553
 
1554
`max-procs'
1555
     `-P' in `xargs'.
1556
 
1557
`mesg'
1558
     `-T' in `who'.
1559
 
1560
`message'
1561
     `-T' in `who'.
1562
 
1563
`minimal'
1564
     `-d' in `diff'.
1565
 
1566
`mixed-uuencode'
1567
     `-M' in `shar'.
1568
 
1569
`mode'
1570
     `-m' in `install', `mkdir', and `mkfifo'.
1571
 
1572
`modification-time'
1573
     `-m' in `tar'.
1574
 
1575
`multi-volume'
1576
     `-M' in `tar'.
1577
 
1578
`name-prefix'
1579
     `-a' in Bison.
1580
 
1581
`nesting-limit'
1582
     `-L' in `m4'.
1583
 
1584
`net-headers'
1585
     `-a' in `shar'.
1586
 
1587
`new-file'
1588
     `-W' in `make'.
1589
 
1590
`no-builtin-rules'
1591
     `-r' in `make'.
1592
 
1593
`no-character-count'
1594
     `-w' in `shar'.
1595
 
1596
`no-check-existing'
1597
     `-x' in `shar'.
1598
 
1599
`no-common'
1600
     `-3' in `wdiff'.
1601
 
1602
`no-create'
1603
     `-c' in `touch'.
1604
 
1605
`no-defines'
1606
     `-D' in `etags'.
1607
 
1608
`no-deleted'
1609
     `-1' in `wdiff'.
1610
 
1611
`no-dereference'
1612
     `-d' in `cp'.
1613
 
1614
`no-inserted'
1615
     `-2' in `wdiff'.
1616
 
1617
`no-keep-going'
1618
     `-S' in `make'.
1619
 
1620
`no-lines'
1621
     `-l' in Bison.
1622
 
1623
`no-piping'
1624
     `-P' in `shar'.
1625
 
1626
`no-prof'
1627
     `-e' in `gprof'.
1628
 
1629
`no-regex'
1630
     `-R' in `etags'.
1631
 
1632
`no-sort'
1633
     `-p' in `nm'.
1634
 
1635
`no-splash'
1636
     Don't print a startup splash screen.
1637
 
1638
`no-split'
1639
     Used in `makeinfo'.
1640
 
1641
`no-static'
1642
     `-a' in `gprof'.
1643
 
1644
`no-time'
1645
     `-E' in `gprof'.
1646
 
1647
`no-timestamp'
1648
     `-m' in `shar'.
1649
 
1650
`no-validate'
1651
     Used in `makeinfo'.
1652
 
1653
`no-wait'
1654
     Used in `emacsclient'.
1655
 
1656
`no-warn'
1657
     Used in various programs to inhibit warnings.
1658
 
1659
`node'
1660
     `-n' in `info'.
1661
 
1662
`nodename'
1663
     `-n' in `uname'.
1664
 
1665
`nonmatching'
1666
     `-f' in `cpio'.
1667
 
1668
`nstuff'
1669
     `-n' in `objdump'.
1670
 
1671
`null'
1672
     `-0' in `xargs'.
1673
 
1674
`number'
1675
     `-n' in `cat'.
1676
 
1677
`number-nonblank'
1678
     `-b' in `cat'.
1679
 
1680
`numeric-sort'
1681
     `-n' in `nm'.
1682
 
1683
`numeric-uid-gid'
1684
     `-n' in `cpio' and `ls'.
1685
 
1686
`nx'
1687
     Used in GDB.
1688
 
1689
`old-archive'
1690
     `-o' in `tar'.
1691
 
1692
`old-file'
1693
     `-o' in `make'.
1694
 
1695
`one-file-system'
1696
     `-l' in `tar', `cp', and `du'.
1697
 
1698
`only-file'
1699
     `-o' in `ptx'.
1700
 
1701
`only-prof'
1702
     `-f' in `gprof'.
1703
 
1704
`only-time'
1705
     `-F' in `gprof'.
1706
 
1707
`options'
1708
     `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
1709
 
1710
`output'
1711
     In various programs, specify the output file name.
1712
 
1713
`output-prefix'
1714
     `-o' in `shar'.
1715
 
1716
`override'
1717
     `-o' in `rm'.
1718
 
1719
`overwrite'
1720
     `-c' in `unshar'.
1721
 
1722
`owner'
1723
     `-o' in `install'.
1724
 
1725
`paginate'
1726
     `-l' in `diff'.
1727
 
1728
`paragraph-indent'
1729
     Used in `makeinfo'.
1730
 
1731
`parents'
1732
     `-p' in `mkdir' and `rmdir'.
1733
 
1734
`pass-all'
1735
     `-p' in `ul'.
1736
 
1737
`pass-through'
1738
     `-p' in `cpio'.
1739
 
1740
`port'
1741
     `-P' in `finger'.
1742
 
1743
`portability'
1744
     `-c' in `cpio' and `tar'.
1745
 
1746
`posix'
1747
     Used in `gawk'.
1748
 
1749
`prefix-builtins'
1750
     `-P' in `m4'.
1751
 
1752
`prefix'
1753
     `-f' in `csplit'.
1754
 
1755
`preserve'
1756
     Used in `tar' and `cp'.
1757
 
1758
`preserve-environment'
1759
     `-p' in `su'.
1760
 
1761
`preserve-modification-time'
1762
     `-m' in `cpio'.
1763
 
1764
`preserve-order'
1765
     `-s' in `tar'.
1766
 
1767
`preserve-permissions'
1768
     `-p' in `tar'.
1769
 
1770
`print'
1771
     `-l' in `diff'.
1772
 
1773
`print-chars'
1774
     `-L' in `cmp'.
1775
 
1776
`print-data-base'
1777
     `-p' in `make'.
1778
 
1779
`print-directory'
1780
     `-w' in `make'.
1781
 
1782
`print-file-name'
1783
     `-o' in `nm'.
1784
 
1785
`print-symdefs'
1786
     `-s' in `nm'.
1787
 
1788
`printer'
1789
     `-p' in `wdiff'.
1790
 
1791
`prompt'
1792
     `-p' in `ed'.
1793
 
1794
`proxy'
1795
     Specify an HTTP proxy.
1796
 
1797
`query-user'
1798
     `-X' in `shar'.
1799
 
1800
`question'
1801
     `-q' in `make'.
1802
 
1803
`quiet'
1804
     Used in many programs to inhibit the usual output.  Every program
1805
     accepting `--quiet' should accept `--silent' as a synonym.
1806
 
1807
`quiet-unshar'
1808
     `-Q' in `shar'
1809
 
1810
`quote-name'
1811
     `-Q' in `ls'.
1812
 
1813
`rcs'
1814
     `-n' in `diff'.
1815
 
1816
`re-interval'
1817
     Used in `gawk'.
1818
 
1819
`read-full-blocks'
1820
     `-B' in `tar'.
1821
 
1822
`readnow'
1823
     Used in GDB.
1824
 
1825
`recon'
1826
     `-n' in `make'.
1827
 
1828
`record-number'
1829
     `-R' in `tar'.
1830
 
1831
`recursive'
1832
     Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
1833
 
1834
`reference'
1835
     `-r' in `touch'.
1836
 
1837
`references'
1838
     `-r' in `ptx'.
1839
 
1840
`regex'
1841
     `-r' in `tac' and `etags'.
1842
 
1843
`release'
1844
     `-r' in `uname'.
1845
 
1846
`reload-state'
1847
     `-R' in `m4'.
1848
 
1849
`relocation'
1850
     `-r' in `objdump'.
1851
 
1852
`rename'
1853
     `-r' in `cpio'.
1854
 
1855
`replace'
1856
     `-i' in `xargs'.
1857
 
1858
`report-identical-files'
1859
     `-s' in `diff'.
1860
 
1861
`reset-access-time'
1862
     `-a' in `cpio'.
1863
 
1864
`reverse'
1865
     `-r' in `ls' and `nm'.
1866
 
1867
`reversed-ed'
1868
     `-f' in `diff'.
1869
 
1870
`right-side-defs'
1871
     `-R' in `ptx'.
1872
 
1873
`same-order'
1874
     `-s' in `tar'.
1875
 
1876
`same-permissions'
1877
     `-p' in `tar'.
1878
 
1879
`save'
1880
     `-g' in `stty'.
1881
 
1882
`se'
1883
     Used in GDB.
1884
 
1885
`sentence-regexp'
1886
     `-S' in `ptx'.
1887
 
1888
`separate-dirs'
1889
     `-S' in `du'.
1890
 
1891
`separator'
1892
     `-s' in `tac'.
1893
 
1894
`sequence'
1895
     Used by `recode' to chose files or pipes for sequencing passes.
1896
 
1897
`shell'
1898
     `-s' in `su'.
1899
 
1900
`show-all'
1901
     `-A' in `cat'.
1902
 
1903
`show-c-function'
1904
     `-p' in `diff'.
1905
 
1906
`show-ends'
1907
     `-E' in `cat'.
1908
 
1909
`show-function-line'
1910
     `-F' in `diff'.
1911
 
1912
`show-tabs'
1913
     `-T' in `cat'.
1914
 
1915
`silent'
1916
     Used in many programs to inhibit the usual output.  Every program
1917
     accepting `--silent' should accept `--quiet' as a synonym.
1918
 
1919
`size'
1920
     `-s' in `ls'.
1921
 
1922
`socket'
1923
     Specify a file descriptor for a network server to use for its
1924
     socket, instead of opening and binding a new socket.  This
1925
     provides a way to run, in a non-privileged process, a server that
1926
     normally needs a reserved port number.
1927
 
1928
`sort'
1929
     Used in `ls'.
1930
 
1931
`source'
1932
     `-W source' in `gawk'.
1933
 
1934
`sparse'
1935
     `-S' in `tar'.
1936
 
1937
`speed-large-files'
1938
     `-H' in `diff'.
1939
 
1940
`split-at'
1941
     `-E' in `unshar'.
1942
 
1943
`split-size-limit'
1944
     `-L' in `shar'.
1945
 
1946
`squeeze-blank'
1947
     `-s' in `cat'.
1948
 
1949
`start-delete'
1950
     `-w' in `wdiff'.
1951
 
1952
`start-insert'
1953
     `-y' in `wdiff'.
1954
 
1955
`starting-file'
1956
     Used in `tar' and `diff' to specify which file within a directory
1957
     to start processing with.
1958
 
1959
`statistics'
1960
     `-s' in `wdiff'.
1961
 
1962
`stdin-file-list'
1963
     `-S' in `shar'.
1964
 
1965
`stop'
1966
     `-S' in `make'.
1967
 
1968
`strict'
1969
     `-s' in `recode'.
1970
 
1971
`strip'
1972
     `-s' in `install'.
1973
 
1974
`strip-all'
1975
     `-s' in `strip'.
1976
 
1977
`strip-debug'
1978
     `-S' in `strip'.
1979
 
1980
`submitter'
1981
     `-s' in `shar'.
1982
 
1983
`suffix'
1984
     `-S' in `cp', `ln', `mv'.
1985
 
1986
`suffix-format'
1987
     `-b' in `csplit'.
1988
 
1989
`sum'
1990
     `-s' in `gprof'.
1991
 
1992
`summarize'
1993
     `-s' in `du'.
1994
 
1995
`symbolic'
1996
     `-s' in `ln'.
1997
 
1998
`symbols'
1999
     Used in GDB and `objdump'.
2000
 
2001
`synclines'
2002
     `-s' in `m4'.
2003
 
2004
`sysname'
2005
     `-s' in `uname'.
2006
 
2007
`tabs'
2008
     `-t' in `expand' and `unexpand'.
2009
 
2010
`tabsize'
2011
     `-T' in `ls'.
2012
 
2013
`terminal'
2014
     `-T' in `tput' and `ul'.  `-t' in `wdiff'.
2015
 
2016
`text'
2017
     `-a' in `diff'.
2018
 
2019
`text-files'
2020
     `-T' in `shar'.
2021
 
2022
`time'
2023
     Used in `ls' and `touch'.
2024
 
2025
`timeout'
2026
     Specify how long to wait before giving up on some operation.
2027
 
2028
`to-stdout'
2029
     `-O' in `tar'.
2030
 
2031
`total'
2032
     `-c' in `du'.
2033
 
2034
`touch'
2035
     `-t' in `make', `ranlib', and `recode'.
2036
 
2037
`trace'
2038
     `-t' in `m4'.
2039
 
2040
`traditional'
2041
     `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
2042
     and `ptx'.
2043
 
2044
`tty'
2045
     Used in GDB.
2046
 
2047
`typedefs'
2048
     `-t' in `ctags'.
2049
 
2050
`typedefs-and-c++'
2051
     `-T' in `ctags'.
2052
 
2053
`typeset-mode'
2054
     `-t' in `ptx'.
2055
 
2056
`uncompress'
2057
     `-z' in `tar'.
2058
 
2059
`unconditional'
2060
     `-u' in `cpio'.
2061
 
2062
`undefine'
2063
     `-U' in `m4'.
2064
 
2065
`undefined-only'
2066
     `-u' in `nm'.
2067
 
2068
`update'
2069
     `-u' in `cp', `ctags', `mv', `tar'.
2070
 
2071
`usage'
2072
     Used in `gawk'; same as `--help'.
2073
 
2074
`uuencode'
2075
     `-B' in `shar'.
2076
 
2077
`vanilla-operation'
2078
     `-V' in `shar'.
2079
 
2080
`verbose'
2081
     Print more information about progress.  Many programs support this.
2082
 
2083
`verify'
2084
     `-W' in `tar'.
2085
 
2086
`version'
2087
     Print the version number.
2088
 
2089
`version-control'
2090
     `-V' in `cp', `ln', `mv'.
2091
 
2092
`vgrind'
2093
     `-v' in `ctags'.
2094
 
2095
`volume'
2096
     `-V' in `tar'.
2097
 
2098
`what-if'
2099
     `-W' in `make'.
2100
 
2101
`whole-size-limit'
2102
     `-l' in `shar'.
2103
 
2104
`width'
2105
     `-w' in `ls' and `ptx'.
2106
 
2107
`word-regexp'
2108
     `-W' in `ptx'.
2109
 
2110
`writable'
2111
     `-T' in `who'.
2112
 
2113
`zeros'
2114
     `-z' in `gprof'.
2115
 
2116

2117
File: standards.info,  Node: OID Allocations,  Next: Memory Usage,  Prev: Option Table,  Up: Program Behavior
2118
 
2119
4.9 OID Allocations
2120
===================
2121
 
2122
The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the
2123
GNU Project (thanks to Werner Koch).  These are used for SNMP, LDAP,
2124
X.509 certificates, and so on.  The web site
2125
`http://www.alvestrand.no/objectid' has a (voluntary) listing of many
2126
OID assignments.
2127
 
2128
   If you need a new slot for your GNU package, write
2129
.  Here is a list of arcs currently assigned:
2130
 
2131
 
2132
     1.3.6.1.4.1.11591 GNU
2133
 
2134
     1.3.6.1.4.1.11591.1 GNU Radius
2135
 
2136
     1.3.6.1.4.1.11591.2 GnuPG
2137
       1.3.6.1.4.1.11591.2.1   notation
2138
       1.3.6.1.4.1.11591.2.1.1 pkaAddress
2139
 
2140
     1.3.6.1.4.1.11591.3 GNU Radar
2141
 
2142
     1.3.6.1.4.1.11591.4 GNU GSS
2143
 
2144
     1.3.6.1.4.1.11591.5 GNU Mailutils
2145
 
2146
     1.3.6.1.4.1.11591.6 GNU Shishi
2147
 
2148
     1.3.6.1.4.1.11591.7 GNU Radio
2149
 
2150
     1.3.6.1.4.1.11591.12 digestAlgorithm
2151
       1.3.6.1.4.1.11591.12.2 TIGER/192
2152
       1.3.6.1.4.1.11591.13 encryptionAlgorithm
2153
         1.3.6.1.4.1.11591.13.2 Serpent
2154
           1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB
2155
           1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC
2156
           1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB
2157
           1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB
2158
           1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB
2159
           1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC
2160
           1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB
2161
           1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB
2162
           1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB
2163
           1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC
2164
           1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB
2165
           1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB
2166
       1.3.6.1.4.1.11591.14 CRC algorithms
2167
         1.3.6.1.4.1.11591.14.1 CRC 32
2168
 
2169

2170
File: standards.info,  Node: Memory Usage,  Next: File Usage,  Prev: OID Allocations,  Up: Program Behavior
2171
 
2172
4.10 Memory Usage
2173
=================
2174
 
2175
If a program typically uses just a few meg of memory, don't bother
2176
making any effort to reduce memory usage.  For example, if it is
2177
impractical for other reasons to operate on files more than a few meg
2178
long, it is reasonable to read entire input files into memory to
2179
operate on them.
2180
 
2181
   However, for programs such as `cat' or `tail', that can usefully
2182
operate on very large files, it is important to avoid using a technique
2183
that would artificially limit the size of files it can handle.  If a
2184
program works by lines and could be applied to arbitrary user-supplied
2185
input files, it should keep only a line in memory, because this is not
2186
very hard and users will want to be able to operate on input files that
2187
are bigger than will fit in memory all at once.
2188
 
2189
   If your program creates complicated data structures, just make them
2190
in memory and give a fatal error if `malloc' returns zero.
2191
 
2192

2193
File: standards.info,  Node: File Usage,  Prev: Memory Usage,  Up: Program Behavior
2194
 
2195
4.11 File Usage
2196
===============
2197
 
2198
Programs should be prepared to operate when `/usr' and `/etc' are
2199
read-only file systems.  Thus, if the program manages log files, lock
2200
files, backup files, score files, or any other files which are modified
2201
for internal purposes, these files should not be stored in `/usr' or
2202
`/etc'.
2203
 
2204
   There are two exceptions.  `/etc' is used to store system
2205
configuration information; it is reasonable for a program to modify
2206
files in `/etc' when its job is to update the system configuration.
2207
Also, if the user explicitly asks to modify one file in a directory, it
2208
is reasonable for the program to store other files in the same
2209
directory.
2210
 
2211

2212
File: standards.info,  Node: Writing C,  Next: Documentation,  Prev: Program Behavior,  Up: Top
2213
 
2214
5 Making The Best Use of C
2215
**************************
2216
 
2217
This chapter provides advice on how best to use the C language when
2218
writing GNU software.
2219
 
2220
* Menu:
2221
 
2222
* Formatting::                  Formatting your source code.
2223
* Comments::                    Commenting your work.
2224
* Syntactic Conventions::       Clean use of C constructs.
2225
* Names::                       Naming variables, functions, and files.
2226
* System Portability::          Portability among different operating systems.
2227
* CPU Portability::             Supporting the range of CPU types.
2228
* System Functions::            Portability and ``standard'' library functions.
2229
* Internationalization::        Techniques for internationalization.
2230
* Character Set::               Use ASCII by default.
2231
* Quote Characters::            Use `...' in the C locale.
2232
* Mmap::                        How you can safely use `mmap'.
2233
 
2234

2235
File: standards.info,  Node: Formatting,  Next: Comments,  Up: Writing C
2236
 
2237
5.1 Formatting Your Source Code
2238
===============================
2239
 
2240
It is important to put the open-brace that starts the body of a C
2241
function in column one, so that they will start a defun.  Several tools
2242
look for open-braces in column one to find the beginnings of C
2243
functions.  These tools will not work on code not formatted that way.
2244
 
2245
   Avoid putting open-brace, open-parenthesis or open-bracket in column
2246
one when they are inside a function, so that they won't start a defun.
2247
The open-brace that starts a `struct' body can go in column one if you
2248
find it useful to treat that definition as a defun.
2249
 
2250
   It is also important for function definitions to start the name of
2251
the function in column one.  This helps people to search for function
2252
definitions, and may also help certain tools recognize them.  Thus,
2253
using Standard C syntax, the format is this:
2254
 
2255
     static char *
2256
     concat (char *s1, char *s2)
2257
     {
2258
       ...
2259
     }
2260
 
2261
or, if you want to use traditional C syntax, format the definition like
2262
this:
2263
 
2264
     static char *
2265
     concat (s1, s2)        /* Name starts in column one here */
2266
          char *s1, *s2;
2267
     {                     /* Open brace in column one here */
2268
       ...
2269
     }
2270
 
2271
   In Standard C, if the arguments don't fit nicely on one line, split
2272
it like this:
2273
 
2274
     int
2275
     lots_of_args (int an_integer, long a_long, short a_short,
2276
                   double a_double, float a_float)
2277
     ...
2278
 
2279
   The rest of this section gives our recommendations for other aspects
2280
of C formatting style, which is also the default style of the `indent'
2281
program in version 1.2 and newer.  It corresponds to the options
2282
 
2283
     -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
2284
     -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
2285
 
2286
   We don't think of these recommendations as requirements, because it
2287
causes no problems for users if two different programs have different
2288
formatting styles.
2289
 
2290
   But whatever style you use, please use it consistently, since a
2291
mixture of styles within one program tends to look ugly.  If you are
2292
contributing changes to an existing program, please follow the style of
2293
that program.
2294
 
2295
   For the body of the function, our recommended style looks like this:
2296
 
2297
     if (x < foo (y, z))
2298
       haha = bar[4] + 5;
2299
     else
2300
       {
2301
         while (z)
2302
           {
2303
             haha += foo (z, z);
2304
             z--;
2305
           }
2306
         return ++x + bar ();
2307
       }
2308
 
2309
   We find it easier to read a program when it has spaces before the
2310
open-parentheses and after the commas.  Especially after the commas.
2311
 
2312
   When you split an expression into multiple lines, split it before an
2313
operator, not after one.  Here is the right way:
2314
 
2315
     if (foo_this_is_long && bar > win (x, y, z)
2316
         && remaining_condition)
2317
 
2318
   Try to avoid having two operators of different precedence at the same
2319
level of indentation.  For example, don't write this:
2320
 
2321
     mode = (inmode[j] == VOIDmode
2322
             || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
2323
             ? outmode[j] : inmode[j]);
2324
 
2325
   Instead, use extra parentheses so that the indentation shows the
2326
nesting:
2327
 
2328
     mode = ((inmode[j] == VOIDmode
2329
              || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
2330
             ? outmode[j] : inmode[j]);
2331
 
2332
   Insert extra parentheses so that Emacs will indent the code properly.
2333
For example, the following indentation looks nice if you do it by hand,
2334
 
2335
     v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2336
         + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2337
 
2338
but Emacs would alter it.  Adding a set of parentheses produces
2339
something that looks equally nice, and which Emacs will preserve:
2340
 
2341
     v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2342
          + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2343
 
2344
   Format do-while statements like this:
2345
 
2346
     do
2347
       {
2348
         a = foo (a);
2349
       }
2350
     while (a > 0);
2351
 
2352
   Please use formfeed characters (control-L) to divide the program into
2353
pages at logical places (but not within a function).  It does not matter
2354
just how long the pages are, since they do not have to fit on a printed
2355
page.  The formfeeds should appear alone on lines by themselves.
2356
 
2357

2358
File: standards.info,  Node: Comments,  Next: Syntactic Conventions,  Prev: Formatting,  Up: Writing C
2359
 
2360
5.2 Commenting Your Work
2361
========================
2362
 
2363
Every program should start with a comment saying briefly what it is for.
2364
Example: `fmt - filter for simple filling of text'.  This comment
2365
should be at the top of the source file containing the `main' function
2366
of the program.
2367
 
2368
   Also, please write a brief comment at the start of each source file,
2369
with the file name and a line or two about the overall purpose of the
2370
file.
2371
 
2372
   Please write the comments in a GNU program in English, because
2373
English is the one language that nearly all programmers in all
2374
countries can read.  If you do not write English well, please write
2375
comments in English as well as you can, then ask other people to help
2376
rewrite them.  If you can't write comments in English, please find
2377
someone to work with you and translate your comments into English.
2378
 
2379
   Please put a comment on each function saying what the function does,
2380
what sorts of arguments it gets, and what the possible values of
2381
arguments mean and are used for.  It is not necessary to duplicate in
2382
words the meaning of the C argument declarations, if a C type is being
2383
used in its customary fashion.  If there is anything nonstandard about
2384
its use (such as an argument of type `char *' which is really the
2385
address of the second character of a string, not the first), or any
2386
possible values that would not work the way one would expect (such as,
2387
that strings containing newlines are not guaranteed to work), be sure
2388
to say so.
2389
 
2390
   Also explain the significance of the return value, if there is one.
2391
 
2392
   Please put two spaces after the end of a sentence in your comments,
2393
so that the Emacs sentence commands will work.  Also, please write
2394
complete sentences and capitalize the first word.  If a lower-case
2395
identifier comes at the beginning of a sentence, don't capitalize it!
2396
Changing the spelling makes it a different identifier.  If you don't
2397
like starting a sentence with a lower case letter, write the sentence
2398
differently (e.g., "The identifier lower-case is ...").
2399
 
2400
   The comment on a function is much clearer if you use the argument
2401
names to speak about the argument values.  The variable name itself
2402
should be lower case, but write it in upper case when you are speaking
2403
about the value rather than the variable itself.  Thus, "the inode
2404
number NODE_NUM" rather than "an inode".
2405
 
2406
   There is usually no purpose in restating the name of the function in
2407
the comment before it, because the reader can see that for himself.
2408
There might be an exception when the comment is so long that the
2409
function itself would be off the bottom of the screen.
2410
 
2411
   There should be a comment on each static variable as well, like this:
2412
 
2413
     /* Nonzero means truncate lines in the display;
2414
        zero means continue them.  */
2415
     int truncate_lines;
2416
 
2417
   Every `#endif' should have a comment, except in the case of short
2418
conditionals (just a few lines) that are not nested.  The comment should
2419
state the condition of the conditional that is ending, _including its
2420
sense_.  `#else' should have a comment describing the condition _and
2421
sense_ of the code that follows.  For example:
2422
 
2423
     #ifdef foo
2424
       ...
2425
     #else /* not foo */
2426
       ...
2427
     #endif /* not foo */
2428
     #ifdef foo
2429
       ...
2430
     #endif /* foo */
2431
 
2432
but, by contrast, write the comments this way for a `#ifndef':
2433
 
2434
     #ifndef foo
2435
       ...
2436
     #else /* foo */
2437
       ...
2438
     #endif /* foo */
2439
     #ifndef foo
2440
       ...
2441
     #endif /* not foo */
2442
 
2443

2444
File: standards.info,  Node: Syntactic Conventions,  Next: Names,  Prev: Comments,  Up: Writing C
2445
 
2446
5.3 Clean Use of C Constructs
2447
=============================
2448
 
2449
Please explicitly declare the types of all objects.  For example, you
2450
should explicitly declare all arguments to functions, and you should
2451
declare functions to return `int' rather than omitting the `int'.
2452
 
2453
   Some programmers like to use the GCC `-Wall' option, and change the
2454
code whenever it issues a warning.  If you want to do this, then do.
2455
Other programmers prefer not to use `-Wall', because it gives warnings
2456
for valid and legitimate code which they do not want to change.  If you
2457
want to do this, then do.  The compiler should be your servant, not
2458
your master.
2459
 
2460
   Declarations of external functions and functions to appear later in
2461
the source file should all go in one place near the beginning of the
2462
file (somewhere before the first function definition in the file), or
2463
else should go in a header file.  Don't put `extern' declarations inside
2464
functions.
2465
 
2466
   It used to be common practice to use the same local variables (with
2467
names like `tem') over and over for different values within one
2468
function.  Instead of doing this, it is better to declare a separate
2469
local variable for each distinct purpose, and give it a name which is
2470
meaningful.  This not only makes programs easier to understand, it also
2471
facilitates optimization by good compilers.  You can also move the
2472
declaration of each local variable into the smallest scope that includes
2473
all its uses.  This makes the program even cleaner.
2474
 
2475
   Don't use local variables or parameters that shadow global
2476
identifiers.
2477
 
2478
   Don't declare multiple variables in one declaration that spans lines.
2479
Start a new declaration on each line, instead.  For example, instead of
2480
this:
2481
 
2482
     int    foo,
2483
            bar;
2484
 
2485
write either this:
2486
 
2487
     int foo, bar;
2488
 
2489
or this:
2490
 
2491
     int foo;
2492
     int bar;
2493
 
2494
(If they are global variables, each should have a comment preceding it
2495
anyway.)
2496
 
2497
   When you have an `if'-`else' statement nested in another `if'
2498
statement, always put braces around the `if'-`else'.  Thus, never write
2499
like this:
2500
 
2501
     if (foo)
2502
       if (bar)
2503
         win ();
2504
       else
2505
         lose ();
2506
 
2507
always like this:
2508
 
2509
     if (foo)
2510
       {
2511
         if (bar)
2512
           win ();
2513
         else
2514
           lose ();
2515
       }
2516
 
2517
   If you have an `if' statement nested inside of an `else' statement,
2518
either write `else if' on one line, like this,
2519
 
2520
     if (foo)
2521
       ...
2522
     else if (bar)
2523
       ...
2524
 
2525
with its `then'-part indented like the preceding `then'-part, or write
2526
the nested `if' within braces like this:
2527
 
2528
     if (foo)
2529
       ...
2530
     else
2531
       {
2532
         if (bar)
2533
           ...
2534
       }
2535
 
2536
   Don't declare both a structure tag and variables or typedefs in the
2537
same declaration.  Instead, declare the structure tag separately and
2538
then use it to declare the variables or typedefs.
2539
 
2540
   Try to avoid assignments inside `if'-conditions (assignments inside
2541
`while'-conditions are ok).  For example, don't write this:
2542
 
2543
     if ((foo = (char *) malloc (sizeof *foo)) == 0)
2544
       fatal ("virtual memory exhausted");
2545
 
2546
instead, write this:
2547
 
2548
     foo = (char *) malloc (sizeof *foo);
2549
     if (foo == 0)
2550
       fatal ("virtual memory exhausted");
2551
 
2552
   Don't make the program ugly to placate `lint'.  Please don't insert
2553
any casts to `void'.  Zero without a cast is perfectly fine as a null
2554
pointer constant, except when calling a varargs function.
2555
 
2556

2557
File: standards.info,  Node: Names,  Next: System Portability,  Prev: Syntactic Conventions,  Up: Writing C
2558
 
2559
5.4 Naming Variables, Functions, and Files
2560
==========================================
2561
 
2562
The names of global variables and functions in a program serve as
2563
comments of a sort.  So don't choose terse names--instead, look for
2564
names that give useful information about the meaning of the variable or
2565
function.  In a GNU program, names should be English, like other
2566
comments.
2567
 
2568
   Local variable names can be shorter, because they are used only
2569
within one context, where (presumably) comments explain their purpose.
2570
 
2571
   Try to limit your use of abbreviations in symbol names.  It is ok to
2572
make a few abbreviations, explain what they mean, and then use them
2573
frequently, but don't use lots of obscure abbreviations.
2574
 
2575
   Please use underscores to separate words in a name, so that the Emacs
2576
word commands can be useful within them.  Stick to lower case; reserve
2577
upper case for macros and `enum' constants, and for name-prefixes that
2578
follow a uniform convention.
2579
 
2580
   For example, you should use names like `ignore_space_change_flag';
2581
don't use names like `iCantReadThis'.
2582
 
2583
   Variables that indicate whether command-line options have been
2584
specified should be named after the meaning of the option, not after
2585
the option-letter.  A comment should state both the exact meaning of
2586
the option and its letter.  For example,
2587
 
2588
     /* Ignore changes in horizontal whitespace (-b).  */
2589
     int ignore_space_change_flag;
2590
 
2591
   When you want to define names with constant integer values, use
2592
`enum' rather than `#define'.  GDB knows about enumeration constants.
2593
 
2594
   You might want to make sure that none of the file names would
2595
conflict if the files were loaded onto an MS-DOS file system which
2596
shortens the names.  You can use the program `doschk' to test for this.
2597
 
2598
   Some GNU programs were designed to limit themselves to file names of
2599
14 characters or less, to avoid file name conflicts if they are read
2600
into older System V systems.  Please preserve this feature in the
2601
existing GNU programs that have it, but there is no need to do this in
2602
new GNU programs.  `doschk' also reports file names longer than 14
2603
characters.
2604
 
2605

2606
File: standards.info,  Node: System Portability,  Next: CPU Portability,  Prev: Names,  Up: Writing C
2607
 
2608
5.5 Portability between System Types
2609
====================================
2610
 
2611
In the Unix world, "portability" refers to porting to different Unix
2612
versions.  For a GNU program, this kind of portability is desirable, but
2613
not paramount.
2614
 
2615
   The primary purpose of GNU software is to run on top of the GNU
2616
kernel, compiled with the GNU C compiler, on various types of CPU.  So
2617
the kinds of portability that are absolutely necessary are quite
2618
limited.  But it is important to support Linux-based GNU systems, since
2619
they are the form of GNU that is popular.
2620
 
2621
   Beyond that, it is good to support the other free operating systems
2622
(*BSD), and it is nice to support other Unix-like systems if you want
2623
to.  Supporting a variety of Unix-like systems is desirable, although
2624
not paramount.  It is usually not too hard, so you may as well do it.
2625
But you don't have to consider it an obligation, if it does turn out to
2626
be hard.
2627
 
2628
   The easiest way to achieve portability to most Unix-like systems is
2629
to use Autoconf.  It's unlikely that your program needs to know more
2630
information about the host platform than Autoconf can provide, simply
2631
because most of the programs that need such knowledge have already been
2632
written.
2633
 
2634
   Avoid using the format of semi-internal data bases (e.g.,
2635
directories) when there is a higher-level alternative (`readdir').
2636
 
2637
   As for systems that are not like Unix, such as MSDOS, Windows, VMS,
2638
MVS, and older Macintosh systems, supporting them is often a lot of
2639
work.  When that is the case, it is better to spend your time adding
2640
features that will be useful on GNU and GNU/Linux, rather than on
2641
supporting other incompatible systems.
2642
 
2643
   If you do support Windows, please do not abbreviate it as "win".  In
2644
hacker terminology, calling something a "win" is a form of praise.
2645
You're free to praise Microsoft Windows on your own if you want, but
2646
please don't do this in GNU packages.  Instead of abbreviating
2647
"Windows" to "win", you can write it in full or abbreviate it to "woe"
2648
or "w".  In GNU Emacs, for instance, we use `w32' in file names of
2649
Windows-specific files, but the macro for Windows conditionals is
2650
called `WINDOWSNT'.
2651
 
2652
   It is a good idea to define the "feature test macro" `_GNU_SOURCE'
2653
when compiling your C files.  When you compile on GNU or GNU/Linux,
2654
this will enable the declarations of GNU library extension functions,
2655
and that will usually give you a compiler error message if you define
2656
the same function names in some other way in your program.  (You don't
2657
have to actually _use_ these functions, if you prefer to make the
2658
program more portable to other systems.)
2659
 
2660
   But whether or not you use these GNU extensions, you should avoid
2661
using their names for any other meanings.  Doing so would make it hard
2662
to move your code into other GNU programs.
2663
 
2664

2665
File: standards.info,  Node: CPU Portability,  Next: System Functions,  Prev: System Portability,  Up: Writing C
2666
 
2667
5.6 Portability between CPUs
2668
============================
2669
 
2670
Even GNU systems will differ because of differences among CPU
2671
types--for example, difference in byte ordering and alignment
2672
requirements.  It is absolutely essential to handle these differences.
2673
However, don't make any effort to cater to the possibility that an
2674
`int' will be less than 32 bits.  We don't support 16-bit machines in
2675
GNU.
2676
 
2677
   Similarly, don't make any effort to cater to the possibility that
2678
`long' will be smaller than predefined types like `size_t'.  For
2679
example, the following code is ok:
2680
 
2681
     printf ("size = %lu\n", (unsigned long) sizeof array);
2682
     printf ("diff = %ld\n", (long) (pointer2 - pointer1));
2683
 
2684
   1989 Standard C requires this to work, and we know of only one
2685
counterexample: 64-bit programs on Microsoft Windows.  We will leave it
2686
to those who want to port GNU programs to that environment to figure
2687
out how to do it.
2688
 
2689
   Predefined file-size types like `off_t' are an exception: they are
2690
longer than `long' on many platforms, so code like the above won't work
2691
with them.  One way to print an `off_t' value portably is to print its
2692
digits yourself, one by one.
2693
 
2694
   Don't assume that the address of an `int' object is also the address
2695
of its least-significant byte.  This is false on big-endian machines.
2696
Thus, don't make the following mistake:
2697
 
2698
     int c;
2699
     ...
2700
     while ((c = getchar ()) != EOF)
2701
       write (file_descriptor, &c, 1);
2702
 
2703
Instead, use `unsigned char' as follows.  (The `unsigned' is for
2704
portability to unusual systems where `char' is signed and where there
2705
is integer overflow checking.)
2706
 
2707
     int c;
2708
     while ((c = getchar ()) != EOF)
2709
       {
2710
         unsigned char u = c;
2711
         write (file_descriptor, &u, 1);
2712
       }
2713
 
2714
   It used to be ok to not worry about the difference between pointers
2715
and integers when passing arguments to functions.  However, on most
2716
modern 64-bit machines pointers are wider than `int'.  Conversely,
2717
integer types like `long long int' and `off_t' are wider than pointers
2718
on most modern 32-bit machines.  Hence it's often better nowadays to
2719
use prototypes to define functions whose argument types are not trivial.
2720
 
2721
   In particular, if functions accept varying argument counts or types
2722
they should be declared using prototypes containing `...' and defined
2723
using `stdarg.h'.  For an example of this, please see the Gnulib
2724
(http://www.gnu.org/software/gnulib/) error module, which declares and
2725
defines the following function:
2726
 
2727
     /* Print a message with `fprintf (stderr, FORMAT, ...)';
2728
        if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
2729
        If STATUS is nonzero, terminate the program with `exit (STATUS)'.  */
2730
 
2731
     void error (int status, int errnum, const char *format, ...);
2732
 
2733
   A simple way to use the Gnulib error module is to obtain the two
2734
source files `error.c' and `error.h' from the Gnulib library source
2735
code repository at `http://git.savannah.gnu.org/gitweb/?p=gnulib.git'.
2736
Here's a sample use:
2737
 
2738
     #include "error.h"
2739
     #include 
2740
     #include 
2741
 
2742
     char *program_name = "myprogram";
2743
 
2744
     FILE *
2745
     xfopen (char const *name)
2746
     {
2747
       FILE *fp = fopen (name, "r");
2748
       if (! fp)
2749
         error (1, errno, "cannot read %s", name);
2750
       return fp;
2751
     }
2752
 
2753
   Avoid casting pointers to integers if you can.  Such casts greatly
2754
reduce portability, and in most programs they are easy to avoid.  In the
2755
cases where casting pointers to integers is essential--such as, a Lisp
2756
interpreter which stores type information as well as an address in one
2757
word--you'll have to make explicit provisions to handle different word
2758
sizes.  You will also need to make provision for systems in which the
2759
normal range of addresses you can get from `malloc' starts far away
2760
from zero.
2761
 
2762

2763
File: standards.info,  Node: System Functions,  Next: Internationalization,  Prev: CPU Portability,  Up: Writing C
2764
 
2765
5.7 Calling System Functions
2766
============================
2767
 
2768
C implementations differ substantially.  Standard C reduces but does
2769
not eliminate the incompatibilities; meanwhile, many GNU packages still
2770
support pre-standard compilers because this is not hard to do.  This
2771
chapter gives recommendations for how to use the more-or-less standard C
2772
library functions to avoid unnecessary loss of portability.
2773
 
2774
   * Don't use the return value of `sprintf'.  It returns the number of
2775
     characters written on some systems, but not on all systems.
2776
 
2777
   * Be aware that `vfprintf' is not always available.
2778
 
2779
   * `main' should be declared to return type `int'.  It should
2780
     terminate either by calling `exit' or by returning the integer
2781
     status code; make sure it cannot ever return an undefined value.
2782
 
2783
   * Don't declare system functions explicitly.
2784
 
2785
     Almost any declaration for a system function is wrong on some
2786
     system.  To minimize conflicts, leave it to the system header
2787
     files to declare system functions.  If the headers don't declare a
2788
     function, let it remain undeclared.
2789
 
2790
     While it may seem unclean to use a function without declaring it,
2791
     in practice this works fine for most system library functions on
2792
     the systems where this really happens; thus, the disadvantage is
2793
     only theoretical.  By contrast, actual declarations have
2794
     frequently caused actual conflicts.
2795
 
2796
   * If you must declare a system function, don't specify the argument
2797
     types.  Use an old-style declaration, not a Standard C prototype.
2798
     The more you specify about the function, the more likely a
2799
     conflict.
2800
 
2801
   * In particular, don't unconditionally declare `malloc' or `realloc'.
2802
 
2803
     Most GNU programs use those functions just once, in functions
2804
     conventionally named `xmalloc' and `xrealloc'.  These functions
2805
     call `malloc' and `realloc', respectively, and check the results.
2806
 
2807
     Because `xmalloc' and `xrealloc' are defined in your program, you
2808
     can declare them in other files without any risk of type conflict.
2809
 
2810
     On most systems, `int' is the same length as a pointer; thus, the
2811
     calls to `malloc' and `realloc' work fine.  For the few
2812
     exceptional systems (mostly 64-bit machines), you can use
2813
     *conditionalized* declarations of `malloc' and `realloc'--or put
2814
     these declarations in configuration files specific to those
2815
     systems.
2816
 
2817
   * The string functions require special treatment.  Some Unix systems
2818
     have a header file `string.h'; others have `strings.h'.  Neither
2819
     file name is portable.  There are two things you can do: use
2820
     Autoconf to figure out which file to include, or don't include
2821
     either file.
2822
 
2823
   * If you don't include either strings file, you can't get
2824
     declarations for the string functions from the header file in the
2825
     usual way.
2826
 
2827
     That causes less of a problem than you might think.  The newer
2828
     standard string functions should be avoided anyway because many
2829
     systems still don't support them.  The string functions you can
2830
     use are these:
2831
 
2832
          strcpy   strncpy   strcat   strncat
2833
          strlen   strcmp    strncmp
2834
          strchr   strrchr
2835
 
2836
     The copy and concatenate functions work fine without a declaration
2837
     as long as you don't use their values.  Using their values without
2838
     a declaration fails on systems where the width of a pointer
2839
     differs from the width of `int', and perhaps in other cases.  It
2840
     is trivial to avoid using their values, so do that.
2841
 
2842
     The compare functions and `strlen' work fine without a declaration
2843
     on most systems, possibly all the ones that GNU software runs on.
2844
     You may find it necessary to declare them *conditionally* on a few
2845
     systems.
2846
 
2847
     The search functions must be declared to return `char *'.  Luckily,
2848
     there is no variation in the data type they return.  But there is
2849
     variation in their names.  Some systems give these functions the
2850
     names `index' and `rindex'; other systems use the names `strchr'
2851
     and `strrchr'.  Some systems support both pairs of names, but
2852
     neither pair works on all systems.
2853
 
2854
     You should pick a single pair of names and use it throughout your
2855
     program.  (Nowadays, it is better to choose `strchr' and `strrchr'
2856
     for new programs, since those are the standard names.)  Declare
2857
     both of those names as functions returning `char *'.  On systems
2858
     which don't support those names, define them as macros in terms of
2859
     the other pair.  For example, here is what to put at the beginning
2860
     of your file (or in a header) if you want to use the names
2861
     `strchr' and `strrchr' throughout:
2862
 
2863
          #ifndef HAVE_STRCHR
2864
          #define strchr index
2865
          #endif
2866
          #ifndef HAVE_STRRCHR
2867
          #define strrchr rindex
2868
          #endif
2869
 
2870
          char *strchr ();
2871
          char *strrchr ();
2872
 
2873
   Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
2874
defined in systems where the corresponding functions exist.  One way to
2875
get them properly defined is to use Autoconf.
2876
 
2877

2878
File: standards.info,  Node: Internationalization,  Next: Character Set,  Prev: System Functions,  Up: Writing C
2879
 
2880
5.8 Internationalization
2881
========================
2882
 
2883
GNU has a library called GNU gettext that makes it easy to translate the
2884
messages in a program into various languages.  You should use this
2885
library in every program.  Use English for the messages as they appear
2886
in the program, and let gettext provide the way to translate them into
2887
other languages.
2888
 
2889
   Using GNU gettext involves putting a call to the `gettext' macro
2890
around each string that might need translation--like this:
2891
 
2892
     printf (gettext ("Processing file `%s'..."));
2893
 
2894
This permits GNU gettext to replace the string `"Processing file
2895
`%s'..."' with a translated version.
2896
 
2897
   Once a program uses gettext, please make a point of writing calls to
2898
`gettext' when you add new strings that call for translation.
2899
 
2900
   Using GNU gettext in a package involves specifying a "text domain
2901
name" for the package.  The text domain name is used to separate the
2902
translations for this package from the translations for other packages.
2903
Normally, the text domain name should be the same as the name of the
2904
package--for example, `coreutils' for the GNU core utilities.
2905
 
2906
   To enable gettext to work well, avoid writing code that makes
2907
assumptions about the structure of words or sentences.  When you want
2908
the precise text of a sentence to vary depending on the data, use two or
2909
more alternative string constants each containing a complete sentences,
2910
rather than inserting conditionalized words or phrases into a single
2911
sentence framework.
2912
 
2913
   Here is an example of what not to do:
2914
 
2915
     printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
2916
 
2917
   If you apply gettext to all strings, like this,
2918
 
2919
     printf (gettext ("%s is full"),
2920
             capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
2921
 
2922
the translator will hardly know that "disk" and "floppy disk" are meant
2923
to be substituted in the other string.  Worse, in some languages (like
2924
French) the construction will not work: the translation of the word
2925
"full" depends on the gender of the first part of the sentence; it
2926
happens to be not the same for "disk" as for "floppy disk".
2927
 
2928
   Complete sentences can be translated without problems:
2929
 
2930
     printf (capacity > 5000000 ? gettext ("disk is full")
2931
             : gettext ("floppy disk is full"));
2932
 
2933
   A similar problem appears at the level of sentence structure with
2934
this code:
2935
 
2936
     printf ("#  Implicit rule search has%s been done.\n",
2937
             f->tried_implicit ? "" : " not");
2938
 
2939
Adding `gettext' calls to this code cannot give correct results for all
2940
languages, because negation in some languages requires adding words at
2941
more than one place in the sentence.  By contrast, adding `gettext'
2942
calls does the job straightforwardly if the code starts out like this:
2943
 
2944
     printf (f->tried_implicit
2945
             ? "#  Implicit rule search has been done.\n",
2946
             : "#  Implicit rule search has not been done.\n");
2947
 
2948
   Another example is this one:
2949
 
2950
     printf ("%d file%s processed", nfiles,
2951
             nfiles != 1 ? "s" : "");
2952
 
2953
The problem with this example is that it assumes that plurals are made
2954
by adding `s'.  If you apply gettext to the format string, like this,
2955
 
2956
     printf (gettext ("%d file%s processed"), nfiles,
2957
             nfiles != 1 ? "s" : "");
2958
 
2959
the message can use different words, but it will still be forced to use
2960
`s' for the plural.  Here is a better way, with gettext being applied to
2961
the two strings independently:
2962
 
2963
     printf ((nfiles != 1 ? gettext ("%d files processed")
2964
              : gettext ("%d file processed")),
2965
             nfiles);
2966
 
2967
But this still doesn't work for languages like Polish, which has three
2968
plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23,
2969
24, ...  and one for the rest.  The GNU `ngettext' function solves this
2970
problem:
2971
 
2972
     printf (ngettext ("%d files processed", "%d file processed", nfiles),
2973
             nfiles);
2974
 
2975

2976
File: standards.info,  Node: Character Set,  Next: Quote Characters,  Prev: Internationalization,  Up: Writing C
2977
 
2978
5.9 Character Set
2979
=================
2980
 
2981
Sticking to the ASCII character set (plain text, 7-bit characters) is
2982
preferred in GNU source code comments, text documents, and other
2983
contexts, unless there is good reason to do something else because of
2984
the application domain.  For example, if source code deals with the
2985
French Revolutionary calendar, it is OK if its literal strings contain
2986
accented characters in month names like "Flore'al".  Also, it is OK to
2987
use non-ASCII characters to represent proper names of contributors in
2988
change logs (*note Change Logs::).
2989
 
2990
   If you need to use non-ASCII characters, you should normally stick
2991
with one encoding, as one cannot in general mix encodings reliably.
2992
 
2993

2994
File: standards.info,  Node: Quote Characters,  Next: Mmap,  Prev: Character Set,  Up: Writing C
2995
 
2996
5.10 Quote Characters
2997
=====================
2998
 
2999
In the C locale, GNU programs should stick to plain ASCII for quotation
3000
characters in messages to users: preferably 0x60 (``') for left quotes
3001
and 0x27 (`'') for right quotes.  It is ok, but not required, to use
3002
locale-specific quotes in other locales.
3003
 
3004
   The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and
3005
`quotearg' modules provide a reasonably straightforward way to support
3006
locale-specific quote characters, as well as taking care of other
3007
issues, such as quoting a filename that itself contains a quote
3008
character.  See the Gnulib documentation for usage details.
3009
 
3010
   In any case, the documentation for your program should clearly
3011
specify how it does quoting, if different than the preferred method of
3012
``' and `''.  This is especially important if the output of your
3013
program is ever likely to be parsed by another program.
3014
 
3015
   Quotation characters are a difficult area in the computing world at
3016
this time: there are no true left or right quote characters in Latin1;
3017
the ``' character we use was standardized there as a grave accent.
3018
Moreover, Latin1 is still not universally usable.
3019
 
3020
   Unicode contains the unambiguous quote characters required, and its
3021
common encoding UTF-8 is upward compatible with Latin1.  However,
3022
Unicode and UTF-8 are not universally well-supported, either.
3023
 
3024
   This may change over the next few years, and then we will revisit
3025
this.
3026
 
3027

3028
File: standards.info,  Node: Mmap,  Prev: Quote Characters,  Up: Writing C
3029
 
3030
5.11 Mmap
3031
=========
3032
 
3033
Don't assume that `mmap' either works on all files or fails for all
3034
files.  It may work on some files and fail on others.
3035
 
3036
   The proper way to use `mmap' is to try it on the specific file for
3037
which you want to use it--and if `mmap' doesn't work, fall back on
3038
doing the job in another way using `read' and `write'.
3039
 
3040
   The reason this precaution is needed is that the GNU kernel (the
3041
HURD) provides a user-extensible file system, in which there can be many
3042
different kinds of "ordinary files."  Many of them support `mmap', but
3043
some do not.  It is important to make programs handle all these kinds
3044
of files.
3045
 
3046

3047
File: standards.info,  Node: Documentation,  Next: Managing Releases,  Prev: Writing C,  Up: Top
3048
 
3049
6 Documenting Programs
3050
**********************
3051
 
3052
A GNU program should ideally come with full free documentation, adequate
3053
for both reference and tutorial purposes.  If the package can be
3054
programmed or extended, the documentation should cover programming or
3055
extending it, as well as just using it.
3056
 
3057
* Menu:
3058
 
3059
* GNU Manuals::                 Writing proper manuals.
3060
* Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
3061
* Manual Structure Details::    Specific structure conventions.
3062
* License for Manuals::         Writing the distribution terms for a manual.
3063
* Manual Credits::              Giving credit to documentation contributors.
3064
* Printed Manuals::             Mentioning the printed manual.
3065
* NEWS File::                   NEWS files supplement manuals.
3066
* Change Logs::                 Recording changes.
3067
* Man Pages::                   Man pages are secondary.
3068
* Reading other Manuals::       How far you can go in learning
3069
                                from other manuals.
3070
 
3071

3072
File: standards.info,  Node: GNU Manuals,  Next: Doc Strings and Manuals,  Up: Documentation
3073
 
3074
6.1 GNU Manuals
3075
===============
3076
 
3077
The preferred document format for the GNU system is the Texinfo
3078
formatting language.  Every GNU package should (ideally) have
3079
documentation in Texinfo both for reference and for learners.  Texinfo
3080
makes it possible to produce a good quality formatted book, using TeX,
3081
and to generate an Info file.  It is also possible to generate HTML
3082
output from Texinfo source.  See the Texinfo manual, either the
3083
hardcopy, or the on-line version available through `info' or the Emacs
3084
Info subsystem (`C-h i').
3085
 
3086
   Nowadays some other formats such as Docbook and Sgmltexi can be
3087
converted automatically into Texinfo.  It is ok to produce the Texinfo
3088
documentation by conversion this way, as long as it gives good results.
3089
 
3090
   Make sure your manual is clear to a reader who knows nothing about
3091
the topic and reads it straight through.  This means covering basic
3092
topics at the beginning, and advanced topics only later.  This also
3093
means defining every specialized term when it is first used.
3094
 
3095
   Programmers tend to carry over the structure of the program as the
3096
structure for its documentation.  But this structure is not necessarily
3097
good for explaining how to use the program; it may be irrelevant and
3098
confusing for a user.
3099
 
3100
   Instead, the right way to structure documentation is according to the
3101
concepts and questions that a user will have in mind when reading it.
3102
This principle applies at every level, from the lowest (ordering
3103
sentences in a paragraph) to the highest (ordering of chapter topics
3104
within the manual).  Sometimes this structure of ideas matches the
3105
structure of the implementation of the software being documented--but
3106
often they are different.  An important part of learning to write good
3107
documentation is to learn to notice when you have unthinkingly
3108
structured the documentation like the implementation, stop yourself,
3109
and look for better alternatives.
3110
 
3111
   For example, each program in the GNU system probably ought to be
3112
documented in one manual; but this does not mean each program should
3113
have its own manual.  That would be following the structure of the
3114
implementation, rather than the structure that helps the user
3115
understand.
3116
 
3117
   Instead, each manual should cover a coherent _topic_.  For example,
3118
instead of a manual for `diff' and a manual for `diff3', we have one
3119
manual for "comparison of files" which covers both of those programs,
3120
as well as `cmp'.  By documenting these programs together, we can make
3121
the whole subject clearer.
3122
 
3123
   The manual which discusses a program should certainly document all of
3124
the program's command-line options and all of its commands.  It should
3125
give examples of their use.  But don't organize the manual as a list of
3126
features.  Instead, organize it logically, by subtopics.  Address the
3127
questions that a user will ask when thinking about the job that the
3128
program does.  Don't just tell the reader what each feature can do--say
3129
what jobs it is good for, and show how to use it for those jobs.
3130
Explain what is recommended usage, and what kinds of usage users should
3131
avoid.
3132
 
3133
   In general, a GNU manual should serve both as tutorial and reference.
3134
It should be set up for convenient access to each topic through Info,
3135
and for reading straight through (appendixes aside).  A GNU manual
3136
should give a good introduction to a beginner reading through from the
3137
start, and should also provide all the details that hackers want.  The
3138
Bison manual is a good example of this--please take a look at it to see
3139
what we mean.
3140
 
3141
   That is not as hard as it first sounds.  Arrange each chapter as a
3142
logical breakdown of its topic, but order the sections, and write their
3143
text, so that reading the chapter straight through makes sense.  Do
3144
likewise when structuring the book into chapters, and when structuring a
3145
section into paragraphs.  The watchword is, _at each point, address the
3146
most fundamental and important issue raised by the preceding text._
3147
 
3148
   If necessary, add extra chapters at the beginning of the manual which
3149
are purely tutorial and cover the basics of the subject.  These provide
3150
the framework for a beginner to understand the rest of the manual.  The
3151
Bison manual provides a good example of how to do this.
3152
 
3153
   To serve as a reference, a manual should have an Index that list all
3154
the functions, variables, options, and important concepts that are part
3155
of the program.  One combined Index should do for a short manual, but
3156
sometimes for a complex package it is better to use multiple indices.
3157
The Texinfo manual includes advice on preparing good index entries, see
3158
*Note Making Index Entries: (texinfo)Index Entries, and see *Note
3159
Defining the Entries of an Index: (texinfo)Indexing Commands.
3160
 
3161
   Don't use Unix man pages as a model for how to write GNU
3162
documentation; most of them are terse, badly structured, and give
3163
inadequate explanation of the underlying concepts.  (There are, of
3164
course, some exceptions.)  Also, Unix man pages use a particular format
3165
which is different from what we use in GNU manuals.
3166
 
3167
   Please include an email address in the manual for where to report
3168
bugs _in the text of the manual_.
3169
 
3170
   Please do not use the term "pathname" that is used in Unix
3171
documentation; use "file name" (two words) instead.  We use the term
3172
"path" only for search paths, which are lists of directory names.
3173
 
3174
   Please do not use the term "illegal" to refer to erroneous input to
3175
a computer program.  Please use "invalid" for this, and reserve the
3176
term "illegal" for activities prohibited by law.
3177
 
3178
   Please do not write `()' after a function name just to indicate it
3179
is a function.  `foo ()' is not a function, it is a function call with
3180
no arguments.
3181
 
3182

3183
File: standards.info,  Node: Doc Strings and Manuals,  Next: Manual Structure Details,  Prev: GNU Manuals,  Up: Documentation
3184
 
3185
6.2 Doc Strings and Manuals
3186
===========================
3187
 
3188
Some programming systems, such as Emacs, provide a documentation string
3189
for each function, command or variable.  You may be tempted to write a
3190
reference manual by compiling the documentation strings and writing a
3191
little additional text to go around them--but you must not do it.  That
3192
approach is a fundamental mistake.  The text of well-written
3193
documentation strings will be entirely wrong for a manual.
3194
 
3195
   A documentation string needs to stand alone--when it appears on the
3196
screen, there will be no other text to introduce or explain it.
3197
Meanwhile, it can be rather informal in style.
3198
 
3199
   The text describing a function or variable in a manual must not stand
3200
alone; it appears in the context of a section or subsection.  Other text
3201
at the beginning of the section should explain some of the concepts, and
3202
should often make some general points that apply to several functions or
3203
variables.  The previous descriptions of functions and variables in the
3204
section will also have given information about the topic.  A description
3205
written to stand alone would repeat some of that information; this
3206
redundancy looks bad.  Meanwhile, the informality that is acceptable in
3207
a documentation string is totally unacceptable in a manual.
3208
 
3209
   The only good way to use documentation strings in writing a good
3210
manual is to use them as a source of information for writing good text.
3211
 
3212

3213
File: standards.info,  Node: Manual Structure Details,  Next: License for Manuals,  Prev: Doc Strings and Manuals,  Up: Documentation
3214
 
3215
6.3 Manual Structure Details
3216
============================
3217
 
3218
The title page of the manual should state the version of the programs or
3219
packages documented in the manual.  The Top node of the manual should
3220
also contain this information.  If the manual is changing more
3221
frequently than or independent of the program, also state a version
3222
number for the manual in both of these places.
3223
 
3224
   Each program documented in the manual should have a node named
3225
`PROGRAM Invocation' or `Invoking PROGRAM'.  This node (together with
3226
its subnodes, if any) should describe the program's command line
3227
arguments and how to run it (the sort of information people would look
3228
for in a man page).  Start with an `@example' containing a template for
3229
all the options and arguments that the program uses.
3230
 
3231
   Alternatively, put a menu item in some menu whose item name fits one
3232
of the above patterns.  This identifies the node which that item points
3233
to as the node for this purpose, regardless of the node's actual name.
3234
 
3235
   The `--usage' feature of the Info reader looks for such a node or
3236
menu item in order to find the relevant text, so it is essential for
3237
every Texinfo file to have one.
3238
 
3239
   If one manual describes several programs, it should have such a node
3240
for each program described in the manual.
3241
 
3242

3243
File: standards.info,  Node: License for Manuals,  Next: Manual Credits,  Prev: Manual Structure Details,  Up: Documentation
3244
 
3245
6.4 License for Manuals
3246
=======================
3247
 
3248
Please use the GNU Free Documentation License for all GNU manuals that
3249
are more than a few pages long.  Likewise for a collection of short
3250
documents--you only need one copy of the GNU FDL for the whole
3251
collection.  For a single short document, you can use a very permissive
3252
non-copyleft license, to avoid taking up space with a long license.
3253
 
3254
   See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
3255
of how to employ the GFDL.
3256
 
3257
   Note that it is not obligatory to include a copy of the GNU GPL or
3258
GNU LGPL in a manual whose license is neither the GPL nor the LGPL.  It
3259
can be a good idea to include the program's license in a large manual;
3260
in a short manual, whose size would be increased considerably by
3261
including the program's license, it is probably better not to include
3262
it.
3263
 
3264

3265
File: standards.info,  Node: Manual Credits,  Next: Printed Manuals,  Prev: License for Manuals,  Up: Documentation
3266
 
3267
6.5 Manual Credits
3268
==================
3269
 
3270
Please credit the principal human writers of the manual as the authors,
3271
on the title page of the manual.  If a company sponsored the work, thank
3272
the company in a suitable place in the manual, but do not cite the
3273
company as an author.
3274
 
3275

3276
File: standards.info,  Node: Printed Manuals,  Next: NEWS File,  Prev: Manual Credits,  Up: Documentation
3277
 
3278
6.6 Printed Manuals
3279
===================
3280
 
3281
The FSF publishes some GNU manuals in printed form.  To encourage sales
3282
of these manuals, the on-line versions of the manual should mention at
3283
the very start that the printed manual is available and should point at
3284
information for getting it--for instance, with a link to the page
3285
`http://www.gnu.org/order/order.html'.  This should not be included in
3286
the printed manual, though, because there it is redundant.
3287
 
3288
   It is also useful to explain in the on-line forms of the manual how
3289
the user can print out the manual from the sources.
3290
 
3291

3292
File: standards.info,  Node: NEWS File,  Next: Change Logs,  Prev: Printed Manuals,  Up: Documentation
3293
 
3294
6.7 The NEWS File
3295
=================
3296
 
3297
In addition to its manual, the package should have a file named `NEWS'
3298
which contains a list of user-visible changes worth mentioning.  In
3299
each new release, add items to the front of the file and identify the
3300
version they pertain to.  Don't discard old items; leave them in the
3301
file after the newer items.  This way, a user upgrading from any
3302
previous version can see what is new.
3303
 
3304
   If the `NEWS' file gets very long, move some of the older items into
3305
a file named `ONEWS' and put a note at the end referring the user to
3306
that file.
3307
 
3308

3309
File: standards.info,  Node: Change Logs,  Next: Man Pages,  Prev: NEWS File,  Up: Documentation
3310
 
3311
6.8 Change Logs
3312
===============
3313
 
3314
Keep a change log to describe all the changes made to program source
3315
files.  The purpose of this is so that people investigating bugs in the
3316
future will know about the changes that might have introduced the bug.
3317
Often a new bug can be found by looking at what was recently changed.
3318
More importantly, change logs can help you eliminate conceptual
3319
inconsistencies between different parts of a program, by giving you a
3320
history of how the conflicting concepts arose and who they came from.
3321
 
3322
* Menu:
3323
 
3324
* Change Log Concepts::
3325
* Style of Change Logs::
3326
* Simple Changes::
3327
* Conditional Changes::
3328
* Indicating the Part Changed::
3329
 
3330

3331
File: standards.info,  Node: Change Log Concepts,  Next: Style of Change Logs,  Up: Change Logs
3332
 
3333
6.8.1 Change Log Concepts
3334
-------------------------
3335
 
3336
You can think of the change log as a conceptual "undo list" which
3337
explains how earlier versions were different from the current version.
3338
People can see the current version; they don't need the change log to
3339
tell them what is in it.  What they want from a change log is a clear
3340
explanation of how the earlier version differed.
3341
 
3342
   The change log file is normally called `ChangeLog' and covers an
3343
entire directory.  Each directory can have its own change log, or a
3344
directory can use the change log of its parent directory--it's up to
3345
you.
3346
 
3347
   Another alternative is to record change log information with a
3348
version control system such as RCS or CVS.  This can be converted
3349
automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
3350
command `C-x v a' (`vc-update-change-log') does the job.
3351
 
3352
   There's no need to describe the full purpose of the changes or how
3353
they work together.  However, sometimes it is useful to write one line
3354
to describe the overall purpose of a change or a batch of changes.  If
3355
you think that a change calls for explanation, you're probably right.
3356
Please do explain it--but please put the full explanation in comments
3357
in the code, where people will see it whenever they see the code.  For
3358
example, "New function" is enough for the change log when you add a
3359
function, because there should be a comment before the function
3360
definition to explain what it does.
3361
 
3362
   In the past, we recommended not mentioning changes in non-software
3363
files (manuals, help files, etc.) in change logs.  However, we've been
3364
advised that it is a good idea to include them, for the sake of
3365
copyright records.
3366
 
3367
   The easiest way to add an entry to `ChangeLog' is with the Emacs
3368
command `M-x add-change-log-entry'.  An entry should have an asterisk,
3369
the name of the changed file, and then in parentheses the name of the
3370
changed functions, variables or whatever, followed by a colon.  Then
3371
describe the changes you made to that function or variable.
3372
 
3373

3374
File: standards.info,  Node: Style of Change Logs,  Next: Simple Changes,  Prev: Change Log Concepts,  Up: Change Logs
3375
 
3376
6.8.2 Style of Change Logs
3377
--------------------------
3378
 
3379
Here are some simple examples of change log entries, starting with the
3380
header line that says who made the change and when it was installed,
3381
followed by descriptions of specific changes.  (These examples are
3382
drawn from Emacs and GCC.)
3383
 
3384
     1998-08-17  Richard Stallman  
3385
 
3386
     * register.el (insert-register): Return nil.
3387
     (jump-to-register): Likewise.
3388
 
3389
     * sort.el (sort-subr): Return nil.
3390
 
3391
     * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3392
     Restart the tex shell if process is gone or stopped.
3393
     (tex-shell-running): New function.
3394
 
3395
     * expr.c (store_one_arg): Round size up for move_block_to_reg.
3396
     (expand_call): Round up when emitting USE insns.
3397
     * stmt.c (assign_parms): Round size up for move_block_from_reg.
3398
 
3399
   It's important to name the changed function or variable in full.
3400
Don't abbreviate function or variable names, and don't combine them.
3401
Subsequent maintainers will often search for a function name to find all
3402
the change log entries that pertain to it; if you abbreviate the name,
3403
they won't find it when they search.
3404
 
3405
   For example, some people are tempted to abbreviate groups of function
3406
names by writing `* register.el ({insert,jump-to}-register)'; this is
3407
not a good idea, since searching for `jump-to-register' or
3408
`insert-register' would not find that entry.
3409
 
3410
   Separate unrelated change log entries with blank lines.  When two
3411
entries represent parts of the same change, so that they work together,
3412
then don't put blank lines between them.  Then you can omit the file
3413
name and the asterisk when successive entries are in the same file.
3414
 
3415
   Break long lists of function names by closing continued lines with
3416
`)', rather than `,', and opening the continuation with `(' as in this
3417
example:
3418
 
3419
     * keyboard.c (menu_bar_items, tool_bar_items)
3420
     (Fexecute_extended_command): Deal with `keymap' property.
3421
 
3422
   When you install someone else's changes, put the contributor's name
3423
in the change log entry rather than in the text of the entry.  In other
3424
words, write this:
3425
 
3426
     2002-07-14  John Doe  
3427
 
3428
             * sewing.c: Make it sew.
3429
 
3430
rather than this:
3431
 
3432
     2002-07-14  Usual Maintainer  
3433
 
3434
             * sewing.c: Make it sew.  Patch by jdoe@gnu.org.
3435
 
3436
   As for the date, that should be the date you applied the change.
3437
 
3438

3439
File: standards.info,  Node: Simple Changes,  Next: Conditional Changes,  Prev: Style of Change Logs,  Up: Change Logs
3440
 
3441
6.8.3 Simple Changes
3442
--------------------
3443
 
3444
Certain simple kinds of changes don't need much detail in the change
3445
log.
3446
 
3447
   When you change the calling sequence of a function in a simple
3448
fashion, and you change all the callers of the function to use the new
3449
calling sequence, there is no need to make individual entries for all
3450
the callers that you changed.  Just write in the entry for the function
3451
being called, "All callers changed"--like this:
3452
 
3453
     * keyboard.c (Fcommand_execute): New arg SPECIAL.
3454
     All callers changed.
3455
 
3456
   When you change just comments or doc strings, it is enough to write
3457
an entry for the file, without mentioning the functions.  Just "Doc
3458
fixes" is enough for the change log.
3459
 
3460
   There's no technical need to make change log entries for
3461
documentation files.  This is because documentation is not susceptible
3462
to bugs that are hard to fix.  Documentation does not consist of parts
3463
that must interact in a precisely engineered fashion.  To correct an
3464
error, you need not know the history of the erroneous passage; it is
3465
enough to compare what the documentation says with the way the program
3466
actually works.
3467
 
3468
   However, you should keep change logs for documentation files when the
3469
project gets copyright assignments from its contributors, so as to make
3470
the records of authorship more accurate.
3471
 
3472

3473
File: standards.info,  Node: Conditional Changes,  Next: Indicating the Part Changed,  Prev: Simple Changes,  Up: Change Logs
3474
 
3475
6.8.4 Conditional Changes
3476
-------------------------
3477
 
3478
C programs often contain compile-time `#if' conditionals.  Many changes
3479
are conditional; sometimes you add a new definition which is entirely
3480
contained in a conditional.  It is very useful to indicate in the
3481
change log the conditions for which the change applies.
3482
 
3483
   Our convention for indicating conditional changes is to use square
3484
brackets around the name of the condition.
3485
 
3486
   Here is a simple example, describing a change which is conditional
3487
but does not have a function or entity name associated with it:
3488
 
3489
     * xterm.c [SOLARIS2]: Include string.h.
3490
 
3491
   Here is an entry describing a new definition which is entirely
3492
conditional.  This new definition for the macro `FRAME_WINDOW_P' is
3493
used only when `HAVE_X_WINDOWS' is defined:
3494
 
3495
     * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3496
 
3497
   Here is an entry for a change within the function `init_display',
3498
whose definition as a whole is unconditional, but the changes themselves
3499
are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
3500
 
3501
     * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3502
 
3503
   Here is an entry for a change that takes affect only when a certain
3504
macro is _not_ defined:
3505
 
3506
     (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3507
 
3508

3509
File: standards.info,  Node: Indicating the Part Changed,  Prev: Conditional Changes,  Up: Change Logs
3510
 
3511
6.8.5 Indicating the Part Changed
3512
---------------------------------
3513
 
3514
Indicate the part of a function which changed by using angle brackets
3515
enclosing an indication of what the changed part does.  Here is an entry
3516
for a change in the part of the function `sh-while-getopts' that deals
3517
with `sh' commands:
3518
 
3519
     * progmodes/sh-script.el (sh-while-getopts) : Handle case that
3520
     user-specified option string is empty.
3521
 
3522

3523
File: standards.info,  Node: Man Pages,  Next: Reading other Manuals,  Prev: Change Logs,  Up: Documentation
3524
 
3525
6.9 Man Pages
3526
=============
3527
 
3528
In the GNU project, man pages are secondary.  It is not necessary or
3529
expected for every GNU program to have a man page, but some of them do.
3530
It's your choice whether to include a man page in your program.
3531
 
3532
   When you make this decision, consider that supporting a man page
3533
requires continual effort each time the program is changed.  The time
3534
you spend on the man page is time taken away from more useful work.
3535
 
3536
   For a simple program which changes little, updating the man page may
3537
be a small job.  Then there is little reason not to include a man page,
3538
if you have one.
3539
 
3540
   For a large program that changes a great deal, updating a man page
3541
may be a substantial burden.  If a user offers to donate a man page,
3542
you may find this gift costly to accept.  It may be better to refuse
3543
the man page unless the same person agrees to take full responsibility
3544
for maintaining it--so that you can wash your hands of it entirely.  If
3545
this volunteer later ceases to do the job, then don't feel obliged to
3546
pick it up yourself; it may be better to withdraw the man page from the
3547
distribution until someone else agrees to update it.
3548
 
3549
   When a program changes only a little, you may feel that the
3550
discrepancies are small enough that the man page remains useful without
3551
updating.  If so, put a prominent note near the beginning of the man
3552
page explaining that you don't maintain it and that the Texinfo manual
3553
is more authoritative.  The note should say how to access the Texinfo
3554
documentation.
3555
 
3556
   Be sure that man pages include a copyright statement and free
3557
license.  The simple all-permissive license is appropriate for simple
3558
man pages (*note License Notices for Other Files: (maintain)License
3559
Notices for Other Files.).
3560
 
3561
   For long man pages, with enough explanation and documentation that
3562
they can be considered true manuals, use the GFDL (*note License for
3563
Manuals::).
3564
 
3565
   Finally, the GNU help2man program
3566
(`http://www.gnu.org/software/help2man/') is one way to automate
3567
generation of a man page, in this case from `--help' output.  This is
3568
sufficient in many cases.
3569
 
3570

3571
File: standards.info,  Node: Reading other Manuals,  Prev: Man Pages,  Up: Documentation
3572
 
3573
6.10 Reading other Manuals
3574
==========================
3575
 
3576
There may be non-free books or documentation files that describe the
3577
program you are documenting.
3578
 
3579
   It is ok to use these documents for reference, just as the author of
3580
a new algebra textbook can read other books on algebra.  A large portion
3581
of any non-fiction book consists of facts, in this case facts about how
3582
a certain program works, and these facts are necessarily the same for
3583
everyone who writes about the subject.  But be careful not to copy your
3584
outline structure, wording, tables or examples from preexisting non-free
3585
documentation.  Copying from free documentation may be ok; please check
3586
with the FSF about the individual case.
3587
 
3588

3589
File: standards.info,  Node: Managing Releases,  Next: References,  Prev: Documentation,  Up: Top
3590
 
3591
7 The Release Process
3592
*********************
3593
 
3594
Making a release is more than just bundling up your source files in a
3595
tar file and putting it up for FTP.  You should set up your software so
3596
that it can be configured to run on a variety of systems.  Your Makefile
3597
should conform to the GNU standards described below, and your directory
3598
layout should also conform to the standards discussed below.  Doing so
3599
makes it easy to include your package into the larger framework of all
3600
GNU software.
3601
 
3602
* Menu:
3603
 
3604
* Configuration::               How configuration of GNU packages should work.
3605
* Makefile Conventions::        Makefile conventions.
3606
* Releases::                    Making releases
3607
 
3608

3609
File: standards.info,  Node: Configuration,  Next: Makefile Conventions,  Up: Managing Releases
3610
 
3611
7.1 How Configuration Should Work
3612
=================================
3613
 
3614
Each GNU distribution should come with a shell script named
3615
`configure'.  This script is given arguments which describe the kind of
3616
machine and system you want to compile the program for.  The
3617
`configure' script must record the configuration options so that they
3618
affect compilation.
3619
 
3620
   The description here is the specification of the interface for the
3621
`configure' script in GNU packages.  Many packages implement it using
3622
GNU Autoconf (*note Introduction: (autoconf)Top.)  and/or GNU Automake
3623
(*note Introduction: (automake)Top.), but you do not have to use these
3624
tools.  You can implement it any way you like; for instance, by making
3625
`configure' be a wrapper around a completely different configuration
3626
system.
3627
 
3628
   Another way for the `configure' script to operate is to make a link
3629
from a standard name such as `config.h' to the proper configuration
3630
file for the chosen system.  If you use this technique, the
3631
distribution should _not_ contain a file named `config.h'.  This is so
3632
that people won't be able to build the program without configuring it
3633
first.
3634
 
3635
   Another thing that `configure' can do is to edit the Makefile.  If
3636
you do this, the distribution should _not_ contain a file named
3637
`Makefile'.  Instead, it should include a file `Makefile.in' which
3638
contains the input used for editing.  Once again, this is so that people
3639
won't be able to build the program without configuring it first.
3640
 
3641
   If `configure' does write the `Makefile', then `Makefile' should
3642
have a target named `Makefile' which causes `configure' to be rerun,
3643
setting up the same configuration that was set up last time.  The files
3644
that `configure' reads should be listed as dependencies of `Makefile'.
3645
 
3646
   All the files which are output from the `configure' script should
3647
have comments at the beginning explaining that they were generated
3648
automatically using `configure'.  This is so that users won't think of
3649
trying to edit them by hand.
3650
 
3651
   The `configure' script should write a file named `config.status'
3652
which describes which configuration options were specified when the
3653
program was last configured.  This file should be a shell script which,
3654
if run, will recreate the same configuration.
3655
 
3656
   The `configure' script should accept an option of the form
3657
`--srcdir=DIRNAME' to specify the directory where sources are found (if
3658
it is not the current directory).  This makes it possible to build the
3659
program in a separate directory, so that the actual source directory is
3660
not modified.
3661
 
3662
   If the user does not specify `--srcdir', then `configure' should
3663
check both `.' and `..' to see if it can find the sources.  If it finds
3664
the sources in one of these places, it should use them from there.
3665
Otherwise, it should report that it cannot find the sources, and should
3666
exit with nonzero status.
3667
 
3668
   Usually the easy way to support `--srcdir' is by editing a
3669
definition of `VPATH' into the Makefile.  Some rules may need to refer
3670
explicitly to the specified source directory.  To make this possible,
3671
`configure' can add to the Makefile a variable named `srcdir' whose
3672
value is precisely the specified directory.
3673
 
3674
   In addition, the `configure' script should take options
3675
corresponding to most of the standard directory variables (*note
3676
Directory Variables::).  Here is the list:
3677
 
3678
     --prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir
3679
     --sharedstatedir --localstatedir --libdir --includedir --oldincludedir
3680
     --datarootdir --datadir --infodir --localedir --mandir --docdir
3681
     --htmldir --dvidir --pdfdir --psdir
3682
 
3683
   The `configure' script should also take an argument which specifies
3684
the type of system to build the program for.  This argument should look
3685
like this:
3686
 
3687
     CPU-COMPANY-SYSTEM
3688
 
3689
   For example, an Athlon-based GNU/Linux system might be
3690
`i686-pc-linux-gnu'.
3691
 
3692
   The `configure' script needs to be able to decode all plausible
3693
alternatives for how to describe a machine.  Thus,
3694
`athlon-pc-gnu/linux' would be a valid alias.  There is a shell script
3695
called `config.sub'
3696
(http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD)
3697
that you can use as a subroutine to validate system types and
3698
canonicalize aliases.
3699
 
3700
   The `configure' script should also take the option
3701
`--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
3702
argument.  For example, `configure --build=i686-pc-linux-gnu' is
3703
equivalent to `configure i686-pc-linux-gnu'.  When the build type is
3704
not specified by an option or argument, the `configure' script should
3705
normally guess it using the shell script `config.guess'
3706
(http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD).
3707
 
3708
   Other options are permitted to specify in more detail the software
3709
or hardware present on the machine, to include or exclude optional parts
3710
of the package, or to adjust the name of some tools or arguments to
3711
them:
3712
 
3713
`--enable-FEATURE[=PARAMETER]'
3714
     Configure the package to build and install an optional user-level
3715
     facility called FEATURE.  This allows users to choose which
3716
     optional features to include.  Giving an optional PARAMETER of
3717
     `no' should omit FEATURE, if it is built by default.
3718
 
3719
     No `--enable' option should *ever* cause one feature to replace
3720
     another.  No `--enable' option should ever substitute one useful
3721
     behavior for another useful behavior.  The only proper use for
3722
     `--enable' is for questions of whether to build part of the program
3723
     or exclude it.
3724
 
3725
`--with-PACKAGE'
3726
     The package PACKAGE will be installed, so configure this package
3727
     to work with PACKAGE.
3728
 
3729
     Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
3730
     `gnu-libc', `gdb', `x', and `x-toolkit'.
3731
 
3732
     Do not use a `--with' option to specify the file name to use to
3733
     find certain files.  That is outside the scope of what `--with'
3734
     options are for.
3735
 
3736
`VARIABLE=VALUE'
3737
     Set the value of the variable VARIABLE to VALUE.  This is used to
3738
     override the default values of commands or arguments in the build
3739
     process.  For example, the user could issue `configure CFLAGS=-g
3740
     CXXFLAGS=-g' to build with debugging information and without the
3741
     default optimization.
3742
 
3743
     Specifying variables as arguments to `configure', like this:
3744
          ./configure CC=gcc
3745
     is preferable to setting them in environment variables:
3746
          CC=gcc ./configure
3747
     as it helps to recreate the same configuration later with
3748
     `config.status'.  However, both methods should be supported.
3749
 
3750
   All `configure' scripts should accept all of the "detail" options
3751
and the variable settings, whether or not they make any difference to
3752
the particular package at hand.  In particular, they should accept any
3753
option that starts with `--with-' or `--enable-'.  This is so users
3754
will be able to configure an entire GNU source tree at once with a
3755
single set of options.
3756
 
3757
   You will note that the categories `--with-' and `--enable-' are
3758
narrow: they *do not* provide a place for any sort of option you might
3759
think of.  That is deliberate.  We want to limit the possible
3760
configuration options in GNU software.  We do not want GNU programs to
3761
have idiosyncratic configuration options.
3762
 
3763
   Packages that perform part of the compilation process may support
3764
cross-compilation.  In such a case, the host and target machines for the
3765
program may be different.
3766
 
3767
   The `configure' script should normally treat the specified type of
3768
system as both the host and the target, thus producing a program which
3769
works for the same type of machine that it runs on.
3770
 
3771
   To compile a program to run on a host type that differs from the
3772
build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE
3773
uses the same syntax as BUILDTYPE.  The host type normally defaults to
3774
the build type.
3775
 
3776
   To configure a cross-compiler, cross-assembler, or what have you, you
3777
should specify a target different from the host, using the configure
3778
option `--target=TARGETTYPE'.  The syntax for TARGETTYPE is the same as
3779
for the host type.  So the command would look like this:
3780
 
3781
     ./configure --host=HOSTTYPE --target=TARGETTYPE
3782
 
3783
   The target type normally defaults to the host type.  Programs for
3784
which cross-operation is not meaningful need not accept the `--target'
3785
option, because configuring an entire operating system for
3786
cross-operation is not a meaningful operation.
3787
 
3788
   Some programs have ways of configuring themselves automatically.  If
3789
your program is set up to do this, your `configure' script can simply
3790
ignore most of its arguments.
3791
 
3792

3793
File: standards.info,  Node: Makefile Conventions,  Next: Releases,  Prev: Configuration,  Up: Managing Releases
3794
 
3795
7.2 Makefile Conventions
3796
========================
3797
 
3798
This node describes conventions for writing the Makefiles for GNU
3799
programs.  Using Automake will help you write a Makefile that follows
3800
these conventions.
3801
 
3802
* Menu:
3803
 
3804
* Makefile Basics::             General conventions for Makefiles.
3805
* Utilities in Makefiles::      Utilities to be used in Makefiles.
3806
* Command Variables::           Variables for specifying commands.
3807
* DESTDIR::                     Supporting staged installs.
3808
* Directory Variables::         Variables for installation directories.
3809
* Standard Targets::            Standard targets for users.
3810
* Install Command Categories::  Three categories of commands in the `install'
3811
                                  rule: normal, pre-install and post-install.
3812
 
3813

3814
File: standards.info,  Node: Makefile Basics,  Next: Utilities in Makefiles,  Up: Makefile Conventions
3815
 
3816
7.2.1 General Conventions for Makefiles
3817
---------------------------------------
3818
 
3819
Every Makefile should contain this line:
3820
 
3821
     SHELL = /bin/sh
3822
 
3823
to avoid trouble on systems where the `SHELL' variable might be
3824
inherited from the environment.  (This is never a problem with GNU
3825
`make'.)
3826
 
3827
   Different `make' programs have incompatible suffix lists and
3828
implicit rules, and this sometimes creates confusion or misbehavior.  So
3829
it is a good idea to set the suffix list explicitly using only the
3830
suffixes you need in the particular Makefile, like this:
3831
 
3832
     .SUFFIXES:
3833
     .SUFFIXES: .c .o
3834
 
3835
The first line clears out the suffix list, the second introduces all
3836
suffixes which may be subject to implicit rules in this Makefile.
3837
 
3838
   Don't assume that `.' is in the path for command execution.  When
3839
you need to run programs that are a part of your package during the
3840
make, please make sure that it uses `./' if the program is built as
3841
part of the make or `$(srcdir)/' if the file is an unchanging part of
3842
the source code.  Without one of these prefixes, the current search
3843
path is used.
3844
 
3845
   The distinction between `./' (the "build directory") and
3846
`$(srcdir)/' (the "source directory") is important because users can
3847
build in a separate directory using the `--srcdir' option to
3848
`configure'.  A rule of the form:
3849
 
3850
     foo.1 : foo.man sedscript
3851
             sed -e sedscript foo.man > foo.1
3852
 
3853
will fail when the build directory is not the source directory, because
3854
`foo.man' and `sedscript' are in the source directory.
3855
 
3856
   When using GNU `make', relying on `VPATH' to find the source file
3857
will work in the case where there is a single dependency file, since
3858
the `make' automatic variable `$<' will represent the source file
3859
wherever it is.  (Many versions of `make' set `$<' only in implicit
3860
rules.)  A Makefile target like
3861
 
3862
     foo.o : bar.c
3863
             $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
3864
 
3865
should instead be written as
3866
 
3867
     foo.o : bar.c
3868
             $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
3869
 
3870
in order to allow `VPATH' to work correctly.  When the target has
3871
multiple dependencies, using an explicit `$(srcdir)' is the easiest way
3872
to make the rule work well.  For example, the target above for `foo.1'
3873
is best written as:
3874
 
3875
     foo.1 : foo.man sedscript
3876
             sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
3877
 
3878
   GNU distributions usually contain some files which are not source
3879
files--for example, Info files, and the output from Autoconf, Automake,
3880
Bison or Flex.  Since these files normally appear in the source
3881
directory, they should always appear in the source directory, not in the
3882
build directory.  So Makefile rules to update them should put the
3883
updated files in the source directory.
3884
 
3885
   However, if a file does not appear in the distribution, then the
3886
Makefile should not put it in the source directory, because building a
3887
program in ordinary circumstances should not modify the source directory
3888
in any way.
3889
 
3890
   Try to make the build and installation targets, at least (and all
3891
their subtargets) work correctly with a parallel `make'.
3892
 
3893

3894
File: standards.info,  Node: Utilities in Makefiles,  Next: Command Variables,  Prev: Makefile Basics,  Up: Makefile Conventions
3895
 
3896
7.2.2 Utilities in Makefiles
3897
----------------------------
3898
 
3899
Write the Makefile commands (and any shell scripts, such as
3900
`configure') to run in `sh', not in `csh'.  Don't use any special
3901
features of `ksh' or `bash'.
3902
 
3903
   The `configure' script and the Makefile rules for building and
3904
installation should not use any utilities directly except these:
3905
 
3906
     cat cmp cp diff echo egrep expr false grep install-info
3907
     ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
3908
 
3909
   The compression program `gzip' can be used in the `dist' rule.
3910
 
3911
   Stick to the generally supported options for these programs.  For
3912
example, don't use `mkdir -p', convenient as it may be, because most
3913
systems don't support it.
3914
 
3915
   It is a good idea to avoid creating symbolic links in makefiles,
3916
since a few systems don't support them.
3917
 
3918
   The Makefile rules for building and installation can also use
3919
compilers and related programs, but should do so via `make' variables
3920
so that the user can substitute alternatives.  Here are some of the
3921
programs we mean:
3922
 
3923
     ar bison cc flex install ld ldconfig lex
3924
     make makeinfo ranlib texi2dvi yacc
3925
 
3926
   Use the following `make' variables to run those programs:
3927
 
3928
     $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
3929
     $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
3930
 
3931
   When you use `ranlib' or `ldconfig', you should make sure nothing
3932
bad happens if the system does not have the program in question.
3933
Arrange to ignore an error from that command, and print a message before
3934
the command to tell the user that failure of this command does not mean
3935
a problem.  (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
3936
 
3937
   If you use symbolic links, you should implement a fallback for
3938
systems that don't have symbolic links.
3939
 
3940
   Additional utilities that can be used via Make variables are:
3941
 
3942
     chgrp chmod chown mknod
3943
 
3944
   It is ok to use other utilities in Makefile portions (or scripts)
3945
intended only for particular systems where you know those utilities
3946
exist.
3947
 
3948

3949
File: standards.info,  Node: Command Variables,  Next: DESTDIR,  Prev: Utilities in Makefiles,  Up: Makefile Conventions
3950
 
3951
7.2.3 Variables for Specifying Commands
3952
---------------------------------------
3953
 
3954
Makefiles should provide variables for overriding certain commands,
3955
options, and so on.
3956
 
3957
   In particular, you should run most utility programs via variables.
3958
Thus, if you use Bison, have a variable named `BISON' whose default
3959
value is set with `BISON = bison', and refer to it with `$(BISON)'
3960
whenever you need to use Bison.
3961
 
3962
   File management utilities such as `ln', `rm', `mv', and so on, need
3963
not be referred to through variables in this way, since users don't
3964
need to replace them with other programs.
3965
 
3966
   Each program-name variable should come with an options variable that
3967
is used to supply options to the program.  Append `FLAGS' to the
3968
program-name variable name to get the options variable name--for
3969
example, `BISONFLAGS'.  (The names `CFLAGS' for the C compiler,
3970
`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
3971
but we keep them because they are standard.)  Use `CPPFLAGS' in any
3972
compilation command that runs the preprocessor, and use `LDFLAGS' in
3973
any compilation command that does linking as well as in any direct use
3974
of `ld'.
3975
 
3976
   If there are C compiler options that _must_ be used for proper
3977
compilation of certain files, do not include them in `CFLAGS'.  Users
3978
expect to be able to specify `CFLAGS' freely themselves.  Instead,
3979
arrange to pass the necessary options to the C compiler independently
3980
of `CFLAGS', by writing them explicitly in the compilation commands or
3981
by defining an implicit rule, like this:
3982
 
3983
     CFLAGS = -g
3984
     ALL_CFLAGS = -I. $(CFLAGS)
3985
     .c.o:
3986
             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
3987
 
3988
   Do include the `-g' option in `CFLAGS', because that is not
3989
_required_ for proper compilation.  You can consider it a default that
3990
is only recommended.  If the package is set up so that it is compiled
3991
with GCC by default, then you might as well include `-O' in the default
3992
value of `CFLAGS' as well.
3993
 
3994
   Put `CFLAGS' last in the compilation command, after other variables
3995
containing compiler options, so the user can use `CFLAGS' to override
3996
the others.
3997
 
3998
   `CFLAGS' should be used in every invocation of the C compiler, both
3999
those which do compilation and those which do linking.
4000
 
4001
   Every Makefile should define the variable `INSTALL', which is the
4002
basic command for installing a file into the system.
4003
 
4004
   Every Makefile should also define the variables `INSTALL_PROGRAM'
4005
and `INSTALL_DATA'.  (The default for `INSTALL_PROGRAM' should be
4006
`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
4007
644'.)  Then it should use those variables as the commands for actual
4008
installation, for executables and non-executables respectively.
4009
Minimal use of these variables is as follows:
4010
 
4011
     $(INSTALL_PROGRAM) foo $(bindir)/foo
4012
     $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
4013
 
4014
   However, it is preferable to support a `DESTDIR' prefix on the
4015
target files, as explained in the next section.
4016
 
4017
Always use a file name, not a directory name, as the second argument of
4018
the installation commands.  Use a separate command for each file to be
4019
installed.
4020
 
4021

4022
File: standards.info,  Node: DESTDIR,  Next: Directory Variables,  Prev: Command Variables,  Up: Makefile Conventions
4023
 
4024
7.2.4 `DESTDIR': support for staged installs
4025
--------------------------------------------
4026
 
4027
`DESTDIR' is a variable prepended to each installed target file, like
4028
this:
4029
 
4030
     $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
4031
     $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
4032
 
4033
   The `DESTDIR' variable is specified by the user on the `make'
4034
command line.  For example:
4035
 
4036
     make DESTDIR=/tmp/stage install
4037
 
4038
`DESTDIR' should be supported only in the `install*' and `uninstall*'
4039
targets, as those are the only targets where it is useful.
4040
 
4041
   If your installation step would normally install
4042
`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
4043
installation invoked as in the example above would install
4044
`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
4045
instead.
4046
 
4047
   Prepending the variable `DESTDIR' to each target in this way
4048
provides for "staged installs", where the installed files are not
4049
placed directly into their expected location but are instead copied
4050
into a temporary location (`DESTDIR').  However, installed files
4051
maintain their relative directory structure and any embedded file names
4052
will not be modified.
4053
 
4054
   You should not set the value of `DESTDIR' in your `Makefile' at all;
4055
then the files are installed into their expected locations by default.
4056
Also, specifying `DESTDIR' should not change the operation of the
4057
software in any way, so its value should not be included in any file
4058
contents.
4059
 
4060
   `DESTDIR' support is commonly used in package creation.  It is also
4061
helpful to users who want to understand what a given package will
4062
install where, and to allow users who don't normally have permissions
4063
to install into protected areas to build and install before gaining
4064
those permissions.  Finally, it can be useful with tools such as
4065
`stow', where code is installed in one place but made to appear to be
4066
installed somewhere else using symbolic links or special mount
4067
operations.  So, we strongly recommend GNU packages support `DESTDIR',
4068
though it is not an absolute requirement.
4069
 
4070

4071
File: standards.info,  Node: Directory Variables,  Next: Standard Targets,  Prev: DESTDIR,  Up: Makefile Conventions
4072
 
4073
7.2.5 Variables for Installation Directories
4074
--------------------------------------------
4075
 
4076
Installation directories should always be named by variables, so it is
4077
easy to install in a nonstandard place.  The standard names for these
4078
variables and the values they should have in GNU packages are described
4079
below.  They are based on a standard file system layout; variants of it
4080
are used in GNU/Linux and other modern operating systems.
4081
 
4082
   Installers are expected to override these values when calling `make'
4083
(e.g., `make prefix=/usr install' or `configure' (e.g., `configure
4084
--prefix=/usr').  GNU packages should not try to guess which value
4085
should be appropriate for these variables on the system they are being
4086
installed onto: use the default settings specified here so that all GNU
4087
packages behave identically, allowing the installer to achieve any
4088
desired layout.
4089
 
4090
   These first two variables set the root for the installation.  All the
4091
other installation directories should be subdirectories of one of these
4092
two, and nothing should be directly installed into these two
4093
directories.
4094
 
4095
`prefix'
4096
     A prefix used in constructing the default values of the variables
4097
     listed below.  The default value of `prefix' should be
4098
     `/usr/local'.  When building the complete GNU system, the prefix
4099
     will be empty and `/usr' will be a symbolic link to `/'.  (If you
4100
     are using Autoconf, write it as `@prefix@'.)
4101
 
4102
     Running `make install' with a different value of `prefix' from the
4103
     one used to build the program should _not_ recompile the program.
4104
 
4105
`exec_prefix'
4106
     A prefix used in constructing the default values of some of the
4107
     variables listed below.  The default value of `exec_prefix' should
4108
     be `$(prefix)'.  (If you are using Autoconf, write it as
4109
     `@exec_prefix@'.)
4110
 
4111
     Generally, `$(exec_prefix)' is used for directories that contain
4112
     machine-specific files (such as executables and subroutine
4113
     libraries), while `$(prefix)' is used directly for other
4114
     directories.
4115
 
4116
     Running `make install' with a different value of `exec_prefix'
4117
     from the one used to build the program should _not_ recompile the
4118
     program.
4119
 
4120
   Executable programs are installed in one of the following
4121
directories.
4122
 
4123
`bindir'
4124
     The directory for installing executable programs that users can
4125
     run.  This should normally be `/usr/local/bin', but write it as
4126
     `$(exec_prefix)/bin'.  (If you are using Autoconf, write it as
4127
     `@bindir@'.)
4128
 
4129
`sbindir'
4130
     The directory for installing executable programs that can be run
4131
     from the shell, but are only generally useful to system
4132
     administrators.  This should normally be `/usr/local/sbin', but
4133
     write it as `$(exec_prefix)/sbin'.  (If you are using Autoconf,
4134
     write it as `@sbindir@'.)
4135
 
4136
`libexecdir'
4137
     The directory for installing executable programs to be run by other
4138
     programs rather than by users.  This directory should normally be
4139
     `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
4140
     (If you are using Autoconf, write it as `@libexecdir@'.)
4141
 
4142
     The definition of `libexecdir' is the same for all packages, so
4143
     you should install your data in a subdirectory thereof.  Most
4144
     packages install their data under `$(libexecdir)/PACKAGE-NAME/',
4145
     possibly within additional subdirectories thereof, such as
4146
     `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
4147
 
4148
   Data files used by the program during its execution are divided into
4149
categories in two ways.
4150
 
4151
   * Some files are normally modified by programs; others are never
4152
     normally modified (though users may edit some of these).
4153
 
4154
   * Some files are architecture-independent and can be shared by all
4155
     machines at a site; some are architecture-dependent and can be
4156
     shared only by machines of the same kind and operating system;
4157
     others may never be shared between two machines.
4158
 
4159
   This makes for six different possibilities.  However, we want to
4160
discourage the use of architecture-dependent files, aside from object
4161
files and libraries.  It is much cleaner to make other data files
4162
architecture-independent, and it is generally not hard.
4163
 
4164
   Here are the variables Makefiles should use to specify directories
4165
to put these various kinds of files in:
4166
 
4167
`datarootdir'
4168
     The root of the directory tree for read-only
4169
     architecture-independent data files.  This should normally be
4170
     `/usr/local/share', but write it as `$(prefix)/share'.  (If you
4171
     are using Autoconf, write it as `@datarootdir@'.)  `datadir''s
4172
     default value is based on this variable; so are `infodir',
4173
     `mandir', and others.
4174
 
4175
`datadir'
4176
     The directory for installing idiosyncratic read-only
4177
     architecture-independent data files for this program.  This is
4178
     usually the same place as `datarootdir', but we use the two
4179
     separate variables so that you can move these program-specific
4180
     files without altering the location for Info files, man pages, etc.
4181
 
4182
     This should normally be `/usr/local/share', but write it as
4183
     `$(datarootdir)'.  (If you are using Autoconf, write it as
4184
     `@datadir@'.)
4185
 
4186
     The definition of `datadir' is the same for all packages, so you
4187
     should install your data in a subdirectory thereof.  Most packages
4188
     install their data under `$(datadir)/PACKAGE-NAME/'.
4189
 
4190
`sysconfdir'
4191
     The directory for installing read-only data files that pertain to a
4192
     single machine-that is to say, files for configuring a host.
4193
     Mailer and network configuration files, `/etc/passwd', and so
4194
     forth belong here.  All the files in this directory should be
4195
     ordinary ASCII text files.  This directory should normally be
4196
     `/usr/local/etc', but write it as `$(prefix)/etc'.  (If you are
4197
     using Autoconf, write it as `@sysconfdir@'.)
4198
 
4199
     Do not install executables here in this directory (they probably
4200
     belong in `$(libexecdir)' or `$(sbindir)').  Also do not install
4201
     files that are modified in the normal course of their use (programs
4202
     whose purpose is to change the configuration of the system
4203
     excluded).  Those probably belong in `$(localstatedir)'.
4204
 
4205
`sharedstatedir'
4206
     The directory for installing architecture-independent data files
4207
     which the programs modify while they run.  This should normally be
4208
     `/usr/local/com', but write it as `$(prefix)/com'.  (If you are
4209
     using Autoconf, write it as `@sharedstatedir@'.)
4210
 
4211
`localstatedir'
4212
     The directory for installing data files which the programs modify
4213
     while they run, and that pertain to one specific machine.  Users
4214
     should never need to modify files in this directory to configure
4215
     the package's operation; put such configuration information in
4216
     separate files that go in `$(datadir)' or `$(sysconfdir)'.
4217
     `$(localstatedir)' should normally be `/usr/local/var', but write
4218
     it as `$(prefix)/var'.  (If you are using Autoconf, write it as
4219
     `@localstatedir@'.)
4220
 
4221
   These variables specify the directory for installing certain specific
4222
types of files, if your program has them.  Every GNU package should
4223
have Info files, so every program needs `infodir', but not all need
4224
`libdir' or `lispdir'.
4225
 
4226
`includedir'
4227
     The directory for installing header files to be included by user
4228
     programs with the C `#include' preprocessor directive.  This
4229
     should normally be `/usr/local/include', but write it as
4230
     `$(prefix)/include'.  (If you are using Autoconf, write it as
4231
     `@includedir@'.)
4232
 
4233
     Most compilers other than GCC do not look for header files in
4234
     directory `/usr/local/include'.  So installing the header files
4235
     this way is only useful with GCC.  Sometimes this is not a problem
4236
     because some libraries are only really intended to work with GCC.
4237
     But some libraries are intended to work with other compilers.
4238
     They should install their header files in two places, one
4239
     specified by `includedir' and one specified by `oldincludedir'.
4240
 
4241
`oldincludedir'
4242
     The directory for installing `#include' header files for use with
4243
     compilers other than GCC.  This should normally be `/usr/include'.
4244
     (If you are using Autoconf, you can write it as `@oldincludedir@'.)
4245
 
4246
     The Makefile commands should check whether the value of
4247
     `oldincludedir' is empty.  If it is, they should not try to use
4248
     it; they should cancel the second installation of the header files.
4249
 
4250
     A package should not replace an existing header in this directory
4251
     unless the header came from the same package.  Thus, if your Foo
4252
     package provides a header file `foo.h', then it should install the
4253
     header file in the `oldincludedir' directory if either (1) there
4254
     is no `foo.h' there or (2) the `foo.h' that exists came from the
4255
     Foo package.
4256
 
4257
     To tell whether `foo.h' came from the Foo package, put a magic
4258
     string in the file--part of a comment--and `grep' for that string.
4259
 
4260
`docdir'
4261
     The directory for installing documentation files (other than Info)
4262
     for this package.  By default, it should be
4263
     `/usr/local/share/doc/YOURPKG', but it should be written as
4264
     `$(datarootdir)/doc/YOURPKG'.  (If you are using Autoconf, write
4265
     it as `@docdir@'.)  The YOURPKG subdirectory, which may include a
4266
     version number, prevents collisions among files with common names,
4267
     such as `README'.
4268
 
4269
`infodir'
4270
     The directory for installing the Info files for this package.  By
4271
     default, it should be `/usr/local/share/info', but it should be
4272
     written as `$(datarootdir)/info'.  (If you are using Autoconf,
4273
     write it as `@infodir@'.)  `infodir' is separate from `docdir' for
4274
     compatibility with existing practice.
4275
 
4276
`htmldir'
4277
`dvidir'
4278
`pdfdir'
4279
`psdir'
4280
     Directories for installing documentation files in the particular
4281
     format.  They should all be set to `$(docdir)' by default.  (If
4282
     you are using Autoconf, write them as `@htmldir@', `@dvidir@',
4283
     etc.)  Packages which supply several translations of their
4284
     documentation should install them in `$(htmldir)/'LL,
4285
     `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
4286
     `en' or `pt_BR'.
4287
 
4288
`libdir'
4289
     The directory for object files and libraries of object code.  Do
4290
     not install executables here, they probably ought to go in
4291
     `$(libexecdir)' instead.  The value of `libdir' should normally be
4292
     `/usr/local/lib', but write it as `$(exec_prefix)/lib'.  (If you
4293
     are using Autoconf, write it as `@libdir@'.)
4294
 
4295
`lispdir'
4296
     The directory for installing any Emacs Lisp files in this package.
4297
     By default, it should be `/usr/local/share/emacs/site-lisp', but
4298
     it should be written as `$(datarootdir)/emacs/site-lisp'.
4299
 
4300
     If you are using Autoconf, write the default as `@lispdir@'.  In
4301
     order to make `@lispdir@' work, you need the following lines in
4302
     your `configure.in' file:
4303
 
4304
          lispdir='${datarootdir}/emacs/site-lisp'
4305
          AC_SUBST(lispdir)
4306
 
4307
`localedir'
4308
     The directory for installing locale-specific message catalogs for
4309
     this package.  By default, it should be `/usr/local/share/locale',
4310
     but it should be written as `$(datarootdir)/locale'.  (If you are
4311
     using Autoconf, write it as `@localedir@'.)  This directory
4312
     usually has a subdirectory per locale.
4313
 
4314
   Unix-style man pages are installed in one of the following:
4315
 
4316
`mandir'
4317
     The top-level directory for installing the man pages (if any) for
4318
     this package.  It will normally be `/usr/local/share/man', but you
4319
     should write it as `$(datarootdir)/man'.  (If you are using
4320
     Autoconf, write it as `@mandir@'.)
4321
 
4322
`man1dir'
4323
     The directory for installing section 1 man pages.  Write it as
4324
     `$(mandir)/man1'.
4325
 
4326
`man2dir'
4327
     The directory for installing section 2 man pages.  Write it as
4328
     `$(mandir)/man2'
4329
 
4330
`...'
4331
     *Don't make the primary documentation for any GNU software be a
4332
     man page.  Write a manual in Texinfo instead.  Man pages are just
4333
     for the sake of people running GNU software on Unix, which is a
4334
     secondary application only.*
4335
 
4336
`manext'
4337
     The file name extension for the installed man page.  This should
4338
     contain a period followed by the appropriate digit; it should
4339
     normally be `.1'.
4340
 
4341
`man1ext'
4342
     The file name extension for installed section 1 man pages.
4343
 
4344
`man2ext'
4345
     The file name extension for installed section 2 man pages.
4346
 
4347
`...'
4348
     Use these names instead of `manext' if the package needs to
4349
     install man pages in more than one section of the manual.
4350
 
4351
   And finally, you should set the following variable:
4352
 
4353
`srcdir'
4354
     The directory for the sources being compiled.  The value of this
4355
     variable is normally inserted by the `configure' shell script.
4356
     (If you are using Autoconf, use `srcdir = @srcdir@'.)
4357
 
4358
   For example:
4359
 
4360
     # Common prefix for installation directories.
4361
     # NOTE: This directory must exist when you start the install.
4362
     prefix = /usr/local
4363
     datarootdir = $(prefix)/share
4364
     datadir = $(datarootdir)
4365
     exec_prefix = $(prefix)
4366
     # Where to put the executable for the command `gcc'.
4367
     bindir = $(exec_prefix)/bin
4368
     # Where to put the directories used by the compiler.
4369
     libexecdir = $(exec_prefix)/libexec
4370
     # Where to put the Info files.
4371
     infodir = $(datarootdir)/info
4372
 
4373
   If your program installs a large number of files into one of the
4374
standard user-specified directories, it might be useful to group them
4375
into a subdirectory particular to that program.  If you do this, you
4376
should write the `install' rule to create these subdirectories.
4377
 
4378
   Do not expect the user to include the subdirectory name in the value
4379
of any of the variables listed above.  The idea of having a uniform set
4380
of variable names for installation directories is to enable the user to
4381
specify the exact same values for several different GNU packages.  In
4382
order for this to be useful, all the packages must be designed so that
4383
they will work sensibly when the user does so.
4384
 
4385
   At times, not all of these variables may be implemented in the
4386
current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
4387
believe all of them are.  When any are missing, the descriptions here
4388
serve as specifications for what Autoconf will implement.  As a
4389
programmer, you can either use a development version of Autoconf or
4390
avoid using these variables until a stable release is made which
4391
supports them.
4392
 
4393

4394
File: standards.info,  Node: Standard Targets,  Next: Install Command Categories,  Prev: Directory Variables,  Up: Makefile Conventions
4395
 
4396
7.2.6 Standard Targets for Users
4397
--------------------------------
4398
 
4399
All GNU programs should have the following targets in their Makefiles:
4400
 
4401
`all'
4402
     Compile the entire program.  This should be the default target.
4403
     This target need not rebuild any documentation files; Info files
4404
     should normally be included in the distribution, and DVI (and other
4405
     documentation format) files should be made only when explicitly
4406
     asked for.
4407
 
4408
     By default, the Make rules should compile and link with `-g', so
4409
     that executable programs have debugging symbols.  Users who don't
4410
     mind being helpless can strip the executables later if they wish.
4411
 
4412
`install'
4413
     Compile the program and copy the executables, libraries, and so on
4414
     to the file names where they should reside for actual use.  If
4415
     there is a simple test to verify that a program is properly
4416
     installed, this target should run that test.
4417
 
4418
     Do not strip executables when installing them.  Devil-may-care
4419
     users can use the `install-strip' target to do that.
4420
 
4421
     If possible, write the `install' target rule so that it does not
4422
     modify anything in the directory where the program was built,
4423
     provided `make all' has just been done.  This is convenient for
4424
     building the program under one user name and installing it under
4425
     another.
4426
 
4427
     The commands should create all the directories in which files are
4428
     to be installed, if they don't already exist.  This includes the
4429
     directories specified as the values of the variables `prefix' and
4430
     `exec_prefix', as well as all subdirectories that are needed.  One
4431
     way to do this is by means of an `installdirs' target as described
4432
     below.
4433
 
4434
     Use `-' before any command for installing a man page, so that
4435
     `make' will ignore any errors.  This is in case there are systems
4436
     that don't have the Unix man page documentation system installed.
4437
 
4438
     The way to install Info files is to copy them into `$(infodir)'
4439
     with `$(INSTALL_DATA)' (*note Command Variables::), and then run
4440
     the `install-info' program if it is present.  `install-info' is a
4441
     program that edits the Info `dir' file to add or update the menu
4442
     entry for the given Info file; it is part of the Texinfo package.
4443
     Here is a sample rule to install an Info file:
4444
 
4445
          $(DESTDIR)$(infodir)/foo.info: foo.info
4446
                  $(POST_INSTALL)
4447
          # There may be a newer info file in . than in srcdir.
4448
                  -if test -f foo.info; then d=.; \
4449
                   else d=$(srcdir); fi; \
4450
                  $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
4451
          # Run install-info only if it exists.
4452
          # Use `if' instead of just prepending `-' to the
4453
          # line so we notice real errors from install-info.
4454
          # We use `$(SHELL) -c' because some shells do not
4455
          # fail gracefully when there is an unknown command.
4456
                  if $(SHELL) -c 'install-info --version' \
4457
                     >/dev/null 2>&1; then \
4458
                    install-info --dir-file=$(DESTDIR)$(infodir)/dir \
4459
                                 $(DESTDIR)$(infodir)/foo.info; \
4460
                  else true; fi
4461
 
4462
     When writing the `install' target, you must classify all the
4463
     commands into three categories: normal ones, "pre-installation"
4464
     commands and "post-installation" commands.  *Note Install Command
4465
     Categories::.
4466
 
4467
`install-html'
4468
`install-dvi'
4469
`install-pdf'
4470
`install-ps'
4471
     These targets install documentation in formats other than Info;
4472
     they're intended to be called explicitly by the person installing
4473
     the package, if that format is desired.  GNU prefers Info files,
4474
     so these must be installed by the `install' target.
4475
 
4476
     When you have many documentation files to install, we recommend
4477
     that you avoid collisions and clutter by arranging for these
4478
     targets to install in subdirectories of the appropriate
4479
     installation directory, such as `htmldir'.  As one example, if
4480
     your package has multiple manuals, and you wish to install HTML
4481
     documentation with many files (such as the "split" mode output by
4482
     `makeinfo --html'), you'll certainly want to use subdirectories,
4483
     or two nodes with the same name in different manuals will
4484
     overwrite each other.
4485
 
4486
     Please make these `install-FORMAT' targets invoke the commands for
4487
     the FORMAT target, for example, by making FORMAT a dependency.
4488
 
4489
`uninstall'
4490
     Delete all the installed files--the copies that the `install' and
4491
     `install-*' targets create.
4492
 
4493
     This rule should not modify the directories where compilation is
4494
     done, only the directories where files are installed.
4495
 
4496
     The uninstallation commands are divided into three categories,
4497
     just like the installation commands.  *Note Install Command
4498
     Categories::.
4499
 
4500
`install-strip'
4501
     Like `install', but strip the executable files while installing
4502
     them.  In simple cases, this target can use the `install' target in
4503
     a simple way:
4504
 
4505
          install-strip:
4506
                  $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
4507
                          install
4508
 
4509
     But if the package installs scripts as well as real executables,
4510
     the `install-strip' target can't just refer to the `install'
4511
     target; it has to strip the executables but not the scripts.
4512
 
4513
     `install-strip' should not strip the executables in the build
4514
     directory which are being copied for installation.  It should only
4515
     strip the copies that are installed.
4516
 
4517
     Normally we do not recommend stripping an executable unless you
4518
     are sure the program has no bugs.  However, it can be reasonable
4519
     to install a stripped executable for actual execution while saving
4520
     the unstripped executable elsewhere in case there is a bug.
4521
 
4522
`clean'
4523
     Delete all files in the current directory that are normally
4524
     created by building the program.  Also delete files in other
4525
     directories if they are created by this makefile.  However, don't
4526
     delete the files that record the configuration.  Also preserve
4527
     files that could be made by building, but normally aren't because
4528
     the distribution comes with them.  There is no need to delete
4529
     parent directories that were created with `mkdir -p', since they
4530
     could have existed anyway.
4531
 
4532
     Delete `.dvi' files here if they are not part of the distribution.
4533
 
4534
`distclean'
4535
     Delete all files in the current directory (or created by this
4536
     makefile) that are created by configuring or building the program.
4537
     If you have unpacked the source and built the program without
4538
     creating any other files, `make distclean' should leave only the
4539
     files that were in the distribution.  However, there is no need to
4540
     delete parent directories that were created with `mkdir -p', since
4541
     they could have existed anyway.
4542
 
4543
`mostlyclean'
4544
     Like `clean', but may refrain from deleting a few files that people
4545
     normally don't want to recompile.  For example, the `mostlyclean'
4546
     target for GCC does not delete `libgcc.a', because recompiling it
4547
     is rarely necessary and takes a lot of time.
4548
 
4549
`maintainer-clean'
4550
     Delete almost everything that can be reconstructed with this
4551
     Makefile.  This typically includes everything deleted by
4552
     `distclean', plus more: C source files produced by Bison, tags
4553
     tables, Info files, and so on.
4554
 
4555
     The reason we say "almost everything" is that running the command
4556
     `make maintainer-clean' should not delete `configure' even if
4557
     `configure' can be remade using a rule in the Makefile.  More
4558
     generally, `make maintainer-clean' should not delete anything that
4559
     needs to exist in order to run `configure' and then begin to build
4560
     the program.  Also, there is no need to delete parent directories
4561
     that were created with `mkdir -p', since they could have existed
4562
     anyway.  These are the only exceptions; `maintainer-clean' should
4563
     delete everything else that can be rebuilt.
4564
 
4565
     The `maintainer-clean' target is intended to be used by a
4566
     maintainer of the package, not by ordinary users.  You may need
4567
     special tools to reconstruct some of the files that `make
4568
     maintainer-clean' deletes.  Since these files are normally
4569
     included in the distribution, we don't take care to make them easy
4570
     to reconstruct.  If you find you need to unpack the full
4571
     distribution again, don't blame us.
4572
 
4573
     To help make users aware of this, the commands for the special
4574
     `maintainer-clean' target should start with these two:
4575
 
4576
          @echo 'This command is intended for maintainers to use; it'
4577
          @echo 'deletes files that may need special tools to rebuild.'
4578
 
4579
`TAGS'
4580
     Update a tags table for this program.
4581
 
4582
`info'
4583
     Generate any Info files needed.  The best way to write the rules
4584
     is as follows:
4585
 
4586
          info: foo.info
4587
 
4588
          foo.info: foo.texi chap1.texi chap2.texi
4589
                  $(MAKEINFO) $(srcdir)/foo.texi
4590
 
4591
     You must define the variable `MAKEINFO' in the Makefile.  It should
4592
     run the `makeinfo' program, which is part of the Texinfo
4593
     distribution.
4594
 
4595
     Normally a GNU distribution comes with Info files, and that means
4596
     the Info files are present in the source directory.  Therefore,
4597
     the Make rule for an info file should update it in the source
4598
     directory.  When users build the package, ordinarily Make will not
4599
     update the Info files because they will already be up to date.
4600
 
4601
`dvi'
4602
`html'
4603
`pdf'
4604
`ps'
4605
     Generate documentation files in the given format.  These targets
4606
     should always exist, but any or all can be a no-op if the given
4607
     output format cannot be generated.  These targets should not be
4608
     dependencies of the `all' target; the user must manually invoke
4609
     them.
4610
 
4611
     Here's an example rule for generating DVI files from Texinfo:
4612
 
4613
          dvi: foo.dvi
4614
 
4615
          foo.dvi: foo.texi chap1.texi chap2.texi
4616
                  $(TEXI2DVI) $(srcdir)/foo.texi
4617
 
4618
     You must define the variable `TEXI2DVI' in the Makefile.  It should
4619
     run the program `texi2dvi', which is part of the Texinfo
4620
     distribution.(1)  Alternatively, write just the dependencies, and
4621
     allow GNU `make' to provide the command.
4622
 
4623
     Here's another example, this one for generating HTML from Texinfo:
4624
 
4625
          html: foo.html
4626
 
4627
          foo.html: foo.texi chap1.texi chap2.texi
4628
                  $(TEXI2HTML) $(srcdir)/foo.texi
4629
 
4630
     Again, you would define the variable `TEXI2HTML' in the Makefile;
4631
     for example, it might run `makeinfo --no-split --html' (`makeinfo'
4632
     is part of the Texinfo distribution).
4633
 
4634
`dist'
4635
     Create a distribution tar file for this program.  The tar file
4636
     should be set up so that the file names in the tar file start with
4637
     a subdirectory name which is the name of the package it is a
4638
     distribution for.  This name can include the version number.
4639
 
4640
     For example, the distribution tar file of GCC version 1.40 unpacks
4641
     into a subdirectory named `gcc-1.40'.
4642
 
4643
     The easiest way to do this is to create a subdirectory
4644
     appropriately named, use `ln' or `cp' to install the proper files
4645
     in it, and then `tar' that subdirectory.
4646
 
4647
     Compress the tar file with `gzip'.  For example, the actual
4648
     distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
4649
 
4650
     The `dist' target should explicitly depend on all non-source files
4651
     that are in the distribution, to make sure they are up to date in
4652
     the distribution.  *Note Making Releases: Releases.
4653
 
4654
`check'
4655
     Perform self-tests (if any).  The user must build the program
4656
     before running the tests, but need not install the program; you
4657
     should write the self-tests so that they work when the program is
4658
     built but not installed.
4659
 
4660
   The following targets are suggested as conventional names, for
4661
programs in which they are useful.
4662
 
4663
`installcheck'
4664
     Perform installation tests (if any).  The user must build and
4665
     install the program before running the tests.  You should not
4666
     assume that `$(bindir)' is in the search path.
4667
 
4668
`installdirs'
4669
     It's useful to add a target named `installdirs' to create the
4670
     directories where files are installed, and their parent
4671
     directories.  There is a script called `mkinstalldirs' which is
4672
     convenient for this; you can find it in the Texinfo package.  You
4673
     can use a rule like this:
4674
 
4675
          # Make sure all installation directories (e.g. $(bindir))
4676
          # actually exist by making them if necessary.
4677
          installdirs: mkinstalldirs
4678
                  $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
4679
                                          $(libdir) $(infodir) \
4680
                                          $(mandir)
4681
 
4682
     or, if you wish to support `DESTDIR',
4683
 
4684
          # Make sure all installation directories (e.g. $(bindir))
4685
          # actually exist by making them if necessary.
4686
          installdirs: mkinstalldirs
4687
                  $(srcdir)/mkinstalldirs \
4688
                      $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
4689
                      $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
4690
                      $(DESTDIR)$(mandir)
4691
 
4692
     This rule should not modify the directories where compilation is
4693
     done.  It should do nothing but create installation directories.
4694
 
4695
   ---------- Footnotes ----------
4696
 
4697
   (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
4698
not distributed with Texinfo.
4699
 
4700

4701
File: standards.info,  Node: Install Command Categories,  Prev: Standard Targets,  Up: Makefile Conventions
4702
 
4703
7.2.7 Install Command Categories
4704
--------------------------------
4705
 
4706
When writing the `install' target, you must classify all the commands
4707
into three categories: normal ones, "pre-installation" commands and
4708
"post-installation" commands.
4709
 
4710
   Normal commands move files into their proper places, and set their
4711
modes.  They may not alter any files except the ones that come entirely
4712
from the package they belong to.
4713
 
4714
   Pre-installation and post-installation commands may alter other
4715
files; in particular, they can edit global configuration files or data
4716
bases.
4717
 
4718
   Pre-installation commands are typically executed before the normal
4719
commands, and post-installation commands are typically run after the
4720
normal commands.
4721
 
4722
   The most common use for a post-installation command is to run
4723
`install-info'.  This cannot be done with a normal command, since it
4724
alters a file (the Info directory) which does not come entirely and
4725
solely from the package being installed.  It is a post-installation
4726
command because it needs to be done after the normal command which
4727
installs the package's Info files.
4728
 
4729
   Most programs don't need any pre-installation commands, but we have
4730
the feature just in case it is needed.
4731
 
4732
   To classify the commands in the `install' rule into these three
4733
categories, insert "category lines" among them.  A category line
4734
specifies the category for the commands that follow.
4735
 
4736
   A category line consists of a tab and a reference to a special Make
4737
variable, plus an optional comment at the end.  There are three
4738
variables you can use, one for each category; the variable name
4739
specifies the category.  Category lines are no-ops in ordinary execution
4740
because these three Make variables are normally undefined (and you
4741
_should not_ define them in the makefile).
4742
 
4743
   Here are the three possible category lines, each with a comment that
4744
explains what it means:
4745
 
4746
             $(PRE_INSTALL)     # Pre-install commands follow.
4747
             $(POST_INSTALL)    # Post-install commands follow.
4748
             $(NORMAL_INSTALL)  # Normal commands follow.
4749
 
4750
   If you don't use a category line at the beginning of the `install'
4751
rule, all the commands are classified as normal until the first category
4752
line.  If you don't use any category lines, all the commands are
4753
classified as normal.
4754
 
4755
   These are the category lines for `uninstall':
4756
 
4757
             $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
4758
             $(POST_UNINSTALL)    # Post-uninstall commands follow.
4759
             $(NORMAL_UNINSTALL)  # Normal commands follow.
4760
 
4761
   Typically, a pre-uninstall command would be used for deleting entries
4762
from the Info directory.
4763
 
4764
   If the `install' or `uninstall' target has any dependencies which
4765
act as subroutines of installation, then you should start _each_
4766
dependency's commands with a category line, and start the main target's
4767
commands with a category line also.  This way, you can ensure that each
4768
command is placed in the right category regardless of which of the
4769
dependencies actually run.
4770
 
4771
   Pre-installation and post-installation commands should not run any
4772
programs except for these:
4773
 
4774
     [ basename bash cat chgrp chmod chown cmp cp dd diff echo
4775
     egrep expand expr false fgrep find getopt grep gunzip gzip
4776
     hostname install install-info kill ldconfig ln ls md5sum
4777
     mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
4778
     test touch true uname xargs yes
4779
 
4780
   The reason for distinguishing the commands in this way is for the
4781
sake of making binary packages.  Typically a binary package contains
4782
all the executables and other files that need to be installed, and has
4783
its own method of installing them--so it does not need to run the normal
4784
installation commands.  But installing the binary package does need to
4785
execute the pre-installation and post-installation commands.
4786
 
4787
   Programs to build binary packages work by extracting the
4788
pre-installation and post-installation commands.  Here is one way of
4789
extracting the pre-installation commands (the `-s' option to `make' is
4790
needed to silence messages about entering subdirectories):
4791
 
4792
     make -s -n install -o all \
4793
           PRE_INSTALL=pre-install \
4794
           POST_INSTALL=post-install \
4795
           NORMAL_INSTALL=normal-install \
4796
       | gawk -f pre-install.awk
4797
 
4798
where the file `pre-install.awk' could contain this:
4799
 
4800
     $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
4801
     on {print $0}
4802
     $0 ~ /^pre-install[ \t]*$/ {on = 1}
4803
 
4804

4805
File: standards.info,  Node: Releases,  Prev: Makefile Conventions,  Up: Managing Releases
4806
 
4807
7.3 Making Releases
4808
===================
4809
 
4810
You should identify each release with a pair of version numbers, a
4811
major version and a minor.  We have no objection to using more than two
4812
numbers, but it is very unlikely that you really need them.
4813
 
4814
   Package the distribution of `Foo version 69.96' up in a gzipped tar
4815
file with the name `foo-69.96.tar.gz'.  It should unpack into a
4816
subdirectory named `foo-69.96'.
4817
 
4818
   Building and installing the program should never modify any of the
4819
files contained in the distribution.  This means that all the files
4820
that form part of the program in any way must be classified into "source
4821
files" and "non-source files".  Source files are written by humans and
4822
never changed automatically; non-source files are produced from source
4823
files by programs under the control of the Makefile.
4824
 
4825
   The distribution should contain a file named `README' which gives
4826
the name of the package, and a general description of what it does.  It
4827
is also good to explain the purpose of each of the first-level
4828
subdirectories in the package, if there are any.  The `README' file
4829
should either state the version number of the package, or refer to where
4830
in the package it can be found.
4831
 
4832
   The `README' file should refer to the file `INSTALL', which should
4833
contain an explanation of the installation procedure.
4834
 
4835
   The `README' file should also refer to the file which contains the
4836
copying conditions.  The GNU GPL, if used, should be in a file called
4837
`COPYING'.  If the GNU LGPL is used, it should be in a file called
4838
`COPYING.LESSER'.
4839
 
4840
   Naturally, all the source files must be in the distribution.  It is
4841
okay to include non-source files in the distribution, provided they are
4842
up-to-date and machine-independent, so that building the distribution
4843
normally will never modify them.  We commonly include non-source files
4844
produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
4845
unnecessary dependencies between our distributions, so that users can
4846
install whichever packages they want to install.
4847
 
4848
   Non-source files that might actually be modified by building and
4849
installing the program should *never* be included in the distribution.
4850
So if you do distribute non-source files, always make sure they are up
4851
to date when you make a new distribution.
4852
 
4853
   Make sure that all the files in the distribution are world-readable,
4854
and that directories are world-readable and world-searchable (octal
4855
mode 755).  We used to recommend that all directories in the
4856
distribution also be world-writable (octal mode 777), because ancient
4857
versions of `tar' would otherwise not cope when extracting the archive
4858
as an unprivileged user.  That can easily lead to security issues when
4859
creating the archive, however, so now we recommend against that.
4860
 
4861
   Don't include any symbolic links in the distribution itself.  If the
4862
tar file contains symbolic links, then people cannot even unpack it on
4863
systems that don't support symbolic links.  Also, don't use multiple
4864
names for one file in different directories, because certain file
4865
systems cannot handle this and that prevents unpacking the distribution.
4866
 
4867
   Try to make sure that all the file names will be unique on MS-DOS.  A
4868
name on MS-DOS consists of up to 8 characters, optionally followed by a
4869
period and up to three characters.  MS-DOS will truncate extra
4870
characters both before and after the period.  Thus, `foobarhacker.c'
4871
and `foobarhacker.o' are not ambiguous; they are truncated to
4872
`foobarha.c' and `foobarha.o', which are distinct.
4873
 
4874
   Include in your distribution a copy of the `texinfo.tex' you used to
4875
test print any `*.texinfo' or `*.texi' files.
4876
 
4877
   Likewise, if your program uses small GNU software packages like
4878
regex, getopt, obstack, or termcap, include them in the distribution
4879
file.  Leaving them out would make the distribution file a little
4880
smaller at the expense of possible inconvenience to a user who doesn't
4881
know what other files to get.
4882
 
4883

4884
File: standards.info,  Node: References,  Next: GNU Free Documentation License,  Prev: Managing Releases,  Up: Top
4885
 
4886
8 References to Non-Free Software and Documentation
4887
***************************************************
4888
 
4889
A GNU program should not recommend, promote, or grant legitimacy to the
4890
use of any non-free program.  Proprietary software is a social and
4891
ethical problem, and our aim is to put an end to that problem.  We
4892
can't stop some people from writing proprietary programs, or stop other
4893
people from using them, but we can and should refuse to advertise them
4894
to new potential customers, or to give the public the idea that their
4895
existence is ethical.
4896
 
4897
   The GNU definition of free software is found on the GNU web site at
4898
`http://www.gnu.org/philosophy/free-sw.html', and the definition of
4899
free documentation is found at
4900
`http://www.gnu.org/philosophy/free-doc.html'.  The terms "free" and
4901
"non-free", used in this document, refer to those definitions.
4902
 
4903
   A list of important licenses and whether they qualify as free is in
4904
`http://www.gnu.org/licenses/license-list.html'.  If it is not clear
4905
whether a license qualifies as free, please ask the GNU Project by
4906
writing to .  We will answer, and if the license is
4907
an important one, we will add it to the list.
4908
 
4909
   When a non-free program or system is well known, you can mention it
4910
in passing--that is harmless, since users who might want to use it
4911
probably already know about it.  For instance, it is fine to explain
4912
how to build your package on top of some widely used non-free operating
4913
system, or how to use it together with some widely used non-free
4914
program.
4915
 
4916
   However, you should give only the necessary information to help those
4917
who already use the non-free program to use your program with it--don't
4918
give, or refer to, any further information about the proprietary
4919
program, and don't imply that the proprietary program enhances your
4920
program, or that its existence is in any way a good thing.  The goal
4921
should be that people already using the proprietary program will get
4922
the advice they need about how to use your free program with it, while
4923
people who don't already use the proprietary program will not see
4924
anything likely to lead them to take an interest in it.
4925
 
4926
   If a non-free program or system is obscure in your program's domain,
4927
your program should not mention or support it at all, since doing so
4928
would tend to popularize the non-free program more than it popularizes
4929
your program.  (You cannot hope to find many additional users for your
4930
program among the users of Foobar, if the existence of Foobar is not
4931
generally known among people who might want to use your program.)
4932
 
4933
   Sometimes a program is free software in itself but depends on a
4934
non-free platform in order to run.  For instance, many Java programs
4935
depend on some non-free Java libraries.  To recommend or promote such a
4936
program is to promote the other programs it needs.  This is why we are
4937
careful about listing Java programs in the Free Software Directory: we
4938
don't want to promote the non-free Java libraries.
4939
 
4940
   We hope this particular problem with Java will be gone by and by, as
4941
we replace the remaining non-free standard Java libraries with free
4942
software, but the general principle will remain the same: don't
4943
recommend, promote or legitimize programs that depend on non-free
4944
software to run.
4945
 
4946
   Some free programs strongly encourage the use of non-free software.
4947
A typical example is `mplayer'.  It is free software in itself, and the
4948
free code can handle some kinds of files.  However, `mplayer'
4949
recommends use of non-free codecs for other kinds of files, and users
4950
that install `mplayer' are very likely to install those codecs along
4951
with it.  To recommend `mplayer' is, in effect, to promote use of the
4952
non-free codecs.
4953
 
4954
   Thus, you should not recommend programs that strongly encourage the
4955
use of non-free software.  This is why we do not list `mplayer' in the
4956
Free Software Directory.
4957
 
4958
   A GNU package should not refer the user to any non-free documentation
4959
for free software.  Free documentation that can be included in free
4960
operating systems is essential for completing the GNU system, or any
4961
free operating system, so encouraging it is a priority; to recommend
4962
use of documentation that we are not allowed to include undermines the
4963
impetus for the community to produce documentation that we can include.
4964
So GNU packages should never recommend non-free documentation.
4965
 
4966
   By contrast, it is ok to refer to journal articles and textbooks in
4967
the comments of a program for explanation of how it functions, even
4968
though they are non-free.  This is because we don't include such things
4969
in the GNU system even they are free--they are outside the scope of
4970
what a software distribution needs to include.
4971
 
4972
   Referring to a web site that describes or recommends a non-free
4973
program is promoting that program, so please do not make links (or
4974
mention by name) web sites that contain such material.  This policy is
4975
relevant particularly for the web pages for a GNU package.
4976
 
4977
   Following links from nearly any web site can lead eventually to
4978
non-free software; this is inherent in the nature of the web.  So it
4979
makes no sense to criticize a site for having such links.  As long as
4980
the site does not itself recommend a non-free program, there is no need
4981
to consider the question of the sites that it links to for other
4982
reasons.
4983
 
4984
   Thus, for example, you should not refer to AT&T's web site if that
4985
recommends AT&T's non-free software packages; you should not refer to a
4986
site that links to AT&T's site presenting it as a place to get some
4987
non-free program, because that link recommends and legitimizes the
4988
non-free program.  However, that a site contains a link to AT&T's web
4989
site for some other purpose (such as long-distance telephone service)
4990
is not an objection against it.
4991
 
4992

4993
File: standards.info,  Node: GNU Free Documentation License,  Next: Index,  Prev: References,  Up: Top
4994
 
4995
Appendix A GNU Free Documentation License
4996
*****************************************
4997
 
4998
                     Version 1.3, 3 November 2008
4999
 
5000
     Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
5001
     `http://fsf.org/'
5002
 
5003
     Everyone is permitted to copy and distribute verbatim copies
5004
     of this license document, but changing it is not allowed.
5005
 
5006
  0. PREAMBLE
5007
 
5008
     The purpose of this License is to make a manual, textbook, or other
5009
     functional and useful document "free" in the sense of freedom: to
5010
     assure everyone the effective freedom to copy and redistribute it,
5011
     with or without modifying it, either commercially or
5012
     noncommercially.  Secondarily, this License preserves for the
5013
     author and publisher a way to get credit for their work, while not
5014
     being considered responsible for modifications made by others.
5015
 
5016
     This License is a kind of "copyleft", which means that derivative
5017
     works of the document must themselves be free in the same sense.
5018
     It complements the GNU General Public License, which is a copyleft
5019
     license designed for free software.
5020
 
5021
     We have designed this License in order to use it for manuals for
5022
     free software, because free software needs free documentation: a
5023
     free program should come with manuals providing the same freedoms
5024
     that the software does.  But this License is not limited to
5025
     software manuals; it can be used for any textual work, regardless
5026
     of subject matter or whether it is published as a printed book.
5027
     We recommend this License principally for works whose purpose is
5028
     instruction or reference.
5029
 
5030
  1. APPLICABILITY AND DEFINITIONS
5031
 
5032
     This License applies to any manual or other work, in any medium,
5033
     that contains a notice placed by the copyright holder saying it
5034
     can be distributed under the terms of this License.  Such a notice
5035
     grants a world-wide, royalty-free license, unlimited in duration,
5036
     to use that work under the conditions stated herein.  The
5037
     "Document", below, refers to any such manual or work.  Any member
5038
     of the public is a licensee, and is addressed as "you".  You
5039
     accept the license if you copy, modify or distribute the work in a
5040
     way requiring permission under copyright law.
5041
 
5042
     A "Modified Version" of the Document means any work containing the
5043
     Document or a portion of it, either copied verbatim, or with
5044
     modifications and/or translated into another language.
5045
 
5046
     A "Secondary Section" is a named appendix or a front-matter section
5047
     of the Document that deals exclusively with the relationship of the
5048
     publishers or authors of the Document to the Document's overall
5049
     subject (or to related matters) and contains nothing that could
5050
     fall directly within that overall subject.  (Thus, if the Document
5051
     is in part a textbook of mathematics, a Secondary Section may not
5052
     explain any mathematics.)  The relationship could be a matter of
5053
     historical connection with the subject or with related matters, or
5054
     of legal, commercial, philosophical, ethical or political position
5055
     regarding them.
5056
 
5057
     The "Invariant Sections" are certain Secondary Sections whose
5058
     titles are designated, as being those of Invariant Sections, in
5059
     the notice that says that the Document is released under this
5060
     License.  If a section does not fit the above definition of
5061
     Secondary then it is not allowed to be designated as Invariant.
5062
     The Document may contain zero Invariant Sections.  If the Document
5063
     does not identify any Invariant Sections then there are none.
5064
 
5065
     The "Cover Texts" are certain short passages of text that are
5066
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
5067
     that says that the Document is released under this License.  A
5068
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
5069
     be at most 25 words.
5070
 
5071
     A "Transparent" copy of the Document means a machine-readable copy,
5072
     represented in a format whose specification is available to the
5073
     general public, that is suitable for revising the document
5074
     straightforwardly with generic text editors or (for images
5075
     composed of pixels) generic paint programs or (for drawings) some
5076
     widely available drawing editor, and that is suitable for input to
5077
     text formatters or for automatic translation to a variety of
5078
     formats suitable for input to text formatters.  A copy made in an
5079
     otherwise Transparent file format whose markup, or absence of
5080
     markup, has been arranged to thwart or discourage subsequent
5081
     modification by readers is not Transparent.  An image format is
5082
     not Transparent if used for any substantial amount of text.  A
5083
     copy that is not "Transparent" is called "Opaque".
5084
 
5085
     Examples of suitable formats for Transparent copies include plain
5086
     ASCII without markup, Texinfo input format, LaTeX input format,
5087
     SGML or XML using a publicly available DTD, and
5088
     standard-conforming simple HTML, PostScript or PDF designed for
5089
     human modification.  Examples of transparent image formats include
5090
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
5091
     can be read and edited only by proprietary word processors, SGML or
5092
     XML for which the DTD and/or processing tools are not generally
5093
     available, and the machine-generated HTML, PostScript or PDF
5094
     produced by some word processors for output purposes only.
5095
 
5096
     The "Title Page" means, for a printed book, the title page itself,
5097
     plus such following pages as are needed to hold, legibly, the
5098
     material this License requires to appear in the title page.  For
5099
     works in formats which do not have any title page as such, "Title
5100
     Page" means the text near the most prominent appearance of the
5101
     work's title, preceding the beginning of the body of the text.
5102
 
5103
     The "publisher" means any person or entity that distributes copies
5104
     of the Document to the public.
5105
 
5106
     A section "Entitled XYZ" means a named subunit of the Document
5107
     whose title either is precisely XYZ or contains XYZ in parentheses
5108
     following text that translates XYZ in another language.  (Here XYZ
5109
     stands for a specific section name mentioned below, such as
5110
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
5111
     To "Preserve the Title" of such a section when you modify the
5112
     Document means that it remains a section "Entitled XYZ" according
5113
     to this definition.
5114
 
5115
     The Document may include Warranty Disclaimers next to the notice
5116
     which states that this License applies to the Document.  These
5117
     Warranty Disclaimers are considered to be included by reference in
5118
     this License, but only as regards disclaiming warranties: any other
5119
     implication that these Warranty Disclaimers may have is void and
5120
     has no effect on the meaning of this License.
5121
 
5122
  2. VERBATIM COPYING
5123
 
5124
     You may copy and distribute the Document in any medium, either
5125
     commercially or noncommercially, provided that this License, the
5126
     copyright notices, and the license notice saying this License
5127
     applies to the Document are reproduced in all copies, and that you
5128
     add no other conditions whatsoever to those of this License.  You
5129
     may not use technical measures to obstruct or control the reading
5130
     or further copying of the copies you make or distribute.  However,
5131
     you may accept compensation in exchange for copies.  If you
5132
     distribute a large enough number of copies you must also follow
5133
     the conditions in section 3.
5134
 
5135
     You may also lend copies, under the same conditions stated above,
5136
     and you may publicly display copies.
5137
 
5138
  3. COPYING IN QUANTITY
5139
 
5140
     If you publish printed copies (or copies in media that commonly
5141
     have printed covers) of the Document, numbering more than 100, and
5142
     the Document's license notice requires Cover Texts, you must
5143
     enclose the copies in covers that carry, clearly and legibly, all
5144
     these Cover Texts: Front-Cover Texts on the front cover, and
5145
     Back-Cover Texts on the back cover.  Both covers must also clearly
5146
     and legibly identify you as the publisher of these copies.  The
5147
     front cover must present the full title with all words of the
5148
     title equally prominent and visible.  You may add other material
5149
     on the covers in addition.  Copying with changes limited to the
5150
     covers, as long as they preserve the title of the Document and
5151
     satisfy these conditions, can be treated as verbatim copying in
5152
     other respects.
5153
 
5154
     If the required texts for either cover are too voluminous to fit
5155
     legibly, you should put the first ones listed (as many as fit
5156
     reasonably) on the actual cover, and continue the rest onto
5157
     adjacent pages.
5158
 
5159
     If you publish or distribute Opaque copies of the Document
5160
     numbering more than 100, you must either include a
5161
     machine-readable Transparent copy along with each Opaque copy, or
5162
     state in or with each Opaque copy a computer-network location from
5163
     which the general network-using public has access to download
5164
     using public-standard network protocols a complete Transparent
5165
     copy of the Document, free of added material.  If you use the
5166
     latter option, you must take reasonably prudent steps, when you
5167
     begin distribution of Opaque copies in quantity, to ensure that
5168
     this Transparent copy will remain thus accessible at the stated
5169
     location until at least one year after the last time you
5170
     distribute an Opaque copy (directly or through your agents or
5171
     retailers) of that edition to the public.
5172
 
5173
     It is requested, but not required, that you contact the authors of
5174
     the Document well before redistributing any large number of
5175
     copies, to give them a chance to provide you with an updated
5176
     version of the Document.
5177
 
5178
  4. MODIFICATIONS
5179
 
5180
     You may copy and distribute a Modified Version of the Document
5181
     under the conditions of sections 2 and 3 above, provided that you
5182
     release the Modified Version under precisely this License, with
5183
     the Modified Version filling the role of the Document, thus
5184
     licensing distribution and modification of the Modified Version to
5185
     whoever possesses a copy of it.  In addition, you must do these
5186
     things in the Modified Version:
5187
 
5188
       A. Use in the Title Page (and on the covers, if any) a title
5189
          distinct from that of the Document, and from those of
5190
          previous versions (which should, if there were any, be listed
5191
          in the History section of the Document).  You may use the
5192
          same title as a previous version if the original publisher of
5193
          that version gives permission.
5194
 
5195
       B. List on the Title Page, as authors, one or more persons or
5196
          entities responsible for authorship of the modifications in
5197
          the Modified Version, together with at least five of the
5198
          principal authors of the Document (all of its principal
5199
          authors, if it has fewer than five), unless they release you
5200
          from this requirement.
5201
 
5202
       C. State on the Title page the name of the publisher of the
5203
          Modified Version, as the publisher.
5204
 
5205
       D. Preserve all the copyright notices of the Document.
5206
 
5207
       E. Add an appropriate copyright notice for your modifications
5208
          adjacent to the other copyright notices.
5209
 
5210
       F. Include, immediately after the copyright notices, a license
5211
          notice giving the public permission to use the Modified
5212
          Version under the terms of this License, in the form shown in
5213
          the Addendum below.
5214
 
5215
       G. Preserve in that license notice the full lists of Invariant
5216
          Sections and required Cover Texts given in the Document's
5217
          license notice.
5218
 
5219
       H. Include an unaltered copy of this License.
5220
 
5221
       I. Preserve the section Entitled "History", Preserve its Title,
5222
          and add to it an item stating at least the title, year, new
5223
          authors, and publisher of the Modified Version as given on
5224
          the Title Page.  If there is no section Entitled "History" in
5225
          the Document, create one stating the title, year, authors,
5226
          and publisher of the Document as given on its Title Page,
5227
          then add an item describing the Modified Version as stated in
5228
          the previous sentence.
5229
 
5230
       J. Preserve the network location, if any, given in the Document
5231
          for public access to a Transparent copy of the Document, and
5232
          likewise the network locations given in the Document for
5233
          previous versions it was based on.  These may be placed in
5234
          the "History" section.  You may omit a network location for a
5235
          work that was published at least four years before the
5236
          Document itself, or if the original publisher of the version
5237
          it refers to gives permission.
5238
 
5239
       K. For any section Entitled "Acknowledgements" or "Dedications",
5240
          Preserve the Title of the section, and preserve in the
5241
          section all the substance and tone of each of the contributor
5242
          acknowledgements and/or dedications given therein.
5243
 
5244
       L. Preserve all the Invariant Sections of the Document,
5245
          unaltered in their text and in their titles.  Section numbers
5246
          or the equivalent are not considered part of the section
5247
          titles.
5248
 
5249
       M. Delete any section Entitled "Endorsements".  Such a section
5250
          may not be included in the Modified Version.
5251
 
5252
       N. Do not retitle any existing section to be Entitled
5253
          "Endorsements" or to conflict in title with any Invariant
5254
          Section.
5255
 
5256
       O. Preserve any Warranty Disclaimers.
5257
 
5258
     If the Modified Version includes new front-matter sections or
5259
     appendices that qualify as Secondary Sections and contain no
5260
     material copied from the Document, you may at your option
5261
     designate some or all of these sections as invariant.  To do this,
5262
     add their titles to the list of Invariant Sections in the Modified
5263
     Version's license notice.  These titles must be distinct from any
5264
     other section titles.
5265
 
5266
     You may add a section Entitled "Endorsements", provided it contains
5267
     nothing but endorsements of your Modified Version by various
5268
     parties--for example, statements of peer review or that the text
5269
     has been approved by an organization as the authoritative
5270
     definition of a standard.
5271
 
5272
     You may add a passage of up to five words as a Front-Cover Text,
5273
     and a passage of up to 25 words as a Back-Cover Text, to the end
5274
     of the list of Cover Texts in the Modified Version.  Only one
5275
     passage of Front-Cover Text and one of Back-Cover Text may be
5276
     added by (or through arrangements made by) any one entity.  If the
5277
     Document already includes a cover text for the same cover,
5278
     previously added by you or by arrangement made by the same entity
5279
     you are acting on behalf of, you may not add another; but you may
5280
     replace the old one, on explicit permission from the previous
5281
     publisher that added the old one.
5282
 
5283
     The author(s) and publisher(s) of the Document do not by this
5284
     License give permission to use their names for publicity for or to
5285
     assert or imply endorsement of any Modified Version.
5286
 
5287
  5. COMBINING DOCUMENTS
5288
 
5289
     You may combine the Document with other documents released under
5290
     this License, under the terms defined in section 4 above for
5291
     modified versions, provided that you include in the combination
5292
     all of the Invariant Sections of all of the original documents,
5293
     unmodified, and list them all as Invariant Sections of your
5294
     combined work in its license notice, and that you preserve all
5295
     their Warranty Disclaimers.
5296
 
5297
     The combined work need only contain one copy of this License, and
5298
     multiple identical Invariant Sections may be replaced with a single
5299
     copy.  If there are multiple Invariant Sections with the same name
5300
     but different contents, make the title of each such section unique
5301
     by adding at the end of it, in parentheses, the name of the
5302
     original author or publisher of that section if known, or else a
5303
     unique number.  Make the same adjustment to the section titles in
5304
     the list of Invariant Sections in the license notice of the
5305
     combined work.
5306
 
5307
     In the combination, you must combine any sections Entitled
5308
     "History" in the various original documents, forming one section
5309
     Entitled "History"; likewise combine any sections Entitled
5310
     "Acknowledgements", and any sections Entitled "Dedications".  You
5311
     must delete all sections Entitled "Endorsements."
5312
 
5313
  6. COLLECTIONS OF DOCUMENTS
5314
 
5315
     You may make a collection consisting of the Document and other
5316
     documents released under this License, and replace the individual
5317
     copies of this License in the various documents with a single copy
5318
     that is included in the collection, provided that you follow the
5319
     rules of this License for verbatim copying of each of the
5320
     documents in all other respects.
5321
 
5322
     You may extract a single document from such a collection, and
5323
     distribute it individually under this License, provided you insert
5324
     a copy of this License into the extracted document, and follow
5325
     this License in all other respects regarding verbatim copying of
5326
     that document.
5327
 
5328
  7. AGGREGATION WITH INDEPENDENT WORKS
5329
 
5330
     A compilation of the Document or its derivatives with other
5331
     separate and independent documents or works, in or on a volume of
5332
     a storage or distribution medium, is called an "aggregate" if the
5333
     copyright resulting from the compilation is not used to limit the
5334
     legal rights of the compilation's users beyond what the individual
5335
     works permit.  When the Document is included in an aggregate, this
5336
     License does not apply to the other works in the aggregate which
5337
     are not themselves derivative works of the Document.
5338
 
5339
     If the Cover Text requirement of section 3 is applicable to these
5340
     copies of the Document, then if the Document is less than one half
5341
     of the entire aggregate, the Document's Cover Texts may be placed
5342
     on covers that bracket the Document within the aggregate, or the
5343
     electronic equivalent of covers if the Document is in electronic
5344
     form.  Otherwise they must appear on printed covers that bracket
5345
     the whole aggregate.
5346
 
5347
  8. TRANSLATION
5348
 
5349
     Translation is considered a kind of modification, so you may
5350
     distribute translations of the Document under the terms of section
5351
     4.  Replacing Invariant Sections with translations requires special
5352
     permission from their copyright holders, but you may include
5353
     translations of some or all Invariant Sections in addition to the
5354
     original versions of these Invariant Sections.  You may include a
5355
     translation of this License, and all the license notices in the
5356
     Document, and any Warranty Disclaimers, provided that you also
5357
     include the original English version of this License and the
5358
     original versions of those notices and disclaimers.  In case of a
5359
     disagreement between the translation and the original version of
5360
     this License or a notice or disclaimer, the original version will
5361
     prevail.
5362
 
5363
     If a section in the Document is Entitled "Acknowledgements",
5364
     "Dedications", or "History", the requirement (section 4) to
5365
     Preserve its Title (section 1) will typically require changing the
5366
     actual title.
5367
 
5368
  9. TERMINATION
5369
 
5370
     You may not copy, modify, sublicense, or distribute the Document
5371
     except as expressly provided under this License.  Any attempt
5372
     otherwise to copy, modify, sublicense, or distribute it is void,
5373
     and will automatically terminate your rights under this License.
5374
 
5375
     However, if you cease all violation of this License, then your
5376
     license from a particular copyright holder is reinstated (a)
5377
     provisionally, unless and until the copyright holder explicitly
5378
     and finally terminates your license, and (b) permanently, if the
5379
     copyright holder fails to notify you of the violation by some
5380
     reasonable means prior to 60 days after the cessation.
5381
 
5382
     Moreover, your license from a particular copyright holder is
5383
     reinstated permanently if the copyright holder notifies you of the
5384
     violation by some reasonable means, this is the first time you have
5385
     received notice of violation of this License (for any work) from
5386
     that copyright holder, and you cure the violation prior to 30 days
5387
     after your receipt of the notice.
5388
 
5389
     Termination of your rights under this section does not terminate
5390
     the licenses of parties who have received copies or rights from
5391
     you under this License.  If your rights have been terminated and
5392
     not permanently reinstated, receipt of a copy of some or all of
5393
     the same material does not give you any rights to use it.
5394
 
5395
 10. FUTURE REVISIONS OF THIS LICENSE
5396
 
5397
     The Free Software Foundation may publish new, revised versions of
5398
     the GNU Free Documentation License from time to time.  Such new
5399
     versions will be similar in spirit to the present version, but may
5400
     differ in detail to address new problems or concerns.  See
5401
     `http://www.gnu.org/copyleft/'.
5402
 
5403
     Each version of the License is given a distinguishing version
5404
     number.  If the Document specifies that a particular numbered
5405
     version of this License "or any later version" applies to it, you
5406
     have the option of following the terms and conditions either of
5407
     that specified version or of any later version that has been
5408
     published (not as a draft) by the Free Software Foundation.  If
5409
     the Document does not specify a version number of this License,
5410
     you may choose any version ever published (not as a draft) by the
5411
     Free Software Foundation.  If the Document specifies that a proxy
5412
     can decide which future versions of this License can be used, that
5413
     proxy's public statement of acceptance of a version permanently
5414
     authorizes you to choose that version for the Document.
5415
 
5416
 11. RELICENSING
5417
 
5418
     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
5419
     World Wide Web server that publishes copyrightable works and also
5420
     provides prominent facilities for anybody to edit those works.  A
5421
     public wiki that anybody can edit is an example of such a server.
5422
     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
5423
     site means any set of copyrightable works thus published on the MMC
5424
     site.
5425
 
5426
     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
5427
     license published by Creative Commons Corporation, a not-for-profit
5428
     corporation with a principal place of business in San Francisco,
5429
     California, as well as future copyleft versions of that license
5430
     published by that same organization.
5431
 
5432
     "Incorporate" means to publish or republish a Document, in whole or
5433
     in part, as part of another Document.
5434
 
5435
     An MMC is "eligible for relicensing" if it is licensed under this
5436
     License, and if all works that were first published under this
5437
     License somewhere other than this MMC, and subsequently
5438
     incorporated in whole or in part into the MMC, (1) had no cover
5439
     texts or invariant sections, and (2) were thus incorporated prior
5440
     to November 1, 2008.
5441
 
5442
     The operator of an MMC Site may republish an MMC contained in the
5443
     site under CC-BY-SA on the same site at any time before August 1,
5444
     2009, provided the MMC is eligible for relicensing.
5445
 
5446
 
5447
ADDENDUM: How to use this License for your documents
5448
====================================================
5449
 
5450
To use this License in a document you have written, include a copy of
5451
the License in the document and put the following copyright and license
5452
notices just after the title page:
5453
 
5454
       Copyright (C)  YEAR  YOUR NAME.
5455
       Permission is granted to copy, distribute and/or modify this document
5456
       under the terms of the GNU Free Documentation License, Version 1.3
5457
       or any later version published by the Free Software Foundation;
5458
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5459
       Texts.  A copy of the license is included in the section entitled ``GNU
5460
       Free Documentation License''.
5461
 
5462
   If you have Invariant Sections, Front-Cover Texts and Back-Cover
5463
Texts, replace the "with...Texts." line with this:
5464
 
5465
         with the Invariant Sections being LIST THEIR TITLES, with
5466
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
5467
         being LIST.
5468
 
5469
   If you have Invariant Sections without Cover Texts, or some other
5470
combination of the three, merge those two alternatives to suit the
5471
situation.
5472
 
5473
   If your document contains nontrivial examples of program code, we
5474
recommend releasing these examples in parallel under your choice of
5475
free software license, such as the GNU General Public License, to
5476
permit their use in free software.
5477
 
5478

5479
File: standards.info,  Node: Index,  Prev: GNU Free Documentation License,  Up: Top
5480
 
5481
Index
5482
*****
5483
 
5484
 
5485
* Menu:
5486
5487
* #endif, commenting:                    Comments.            (line  60)
5488
* --help output:                         --help.              (line   6)
5489
* --version output:                      --version.           (line   6)
5490
* -Wall compiler option:                 Syntactic Conventions.
5491
                                                              (line  10)
5492
* accepting contributions:               Contributions.       (line   6)
5493
* address for bug reports:               --help.              (line  11)
5494
* ANSI C standard:                       Standard C.          (line   6)
5495
* arbitrary limits on data:              Semantics.           (line   6)
5496
* ASCII characters:                      Character Set.       (line   6)
5497
* autoconf:                              System Portability.  (line  23)
5498
* avoiding proprietary code:             Reading Non-Free Code.
5499
                                                              (line   6)
5500
* behavior, dependent on program's name: User Interfaces.     (line   6)
5501
* binary packages:                       Install Command Categories.
5502
                                                              (line  80)
5503
* bindir:                                Directory Variables. (line  54)
5504
* braces, in C source:                   Formatting.          (line   6)
5505
* bug reports:                           --help.              (line  11)
5506
* bug-standards@gnu.org email address:   Preface.             (line  30)
5507
* canonical name of a program:           --version.           (line  12)
5508
* casting pointers to integers:          CPU Portability.     (line  89)
5509
* CGI programs, standard options for:    Command-Line Interfaces.
5510
                                                              (line  31)
5511
* change logs:                           Change Logs.         (line   6)
5512
* change logs, conditional changes:      Conditional Changes. (line   6)
5513
* change logs, style:                    Style of Change Logs.
5514
                                                              (line   6)
5515
* character set:                         Character Set.       (line   6)
5516
* command-line arguments, decoding:      Semantics.           (line  46)
5517
* command-line interface:                Command-Line Interfaces.
5518
                                                              (line   6)
5519
* commenting:                            Comments.            (line   6)
5520
* compatibility with C and POSIX standards: Compatibility.    (line   6)
5521
* compiler warnings:                     Syntactic Conventions.
5522
                                                              (line  10)
5523
* conditional changes, and change logs:  Conditional Changes. (line   6)
5524
* conditionals, comments for:            Comments.            (line  60)
5525
* configure:                             Configuration.       (line   6)
5526
* control-L:                             Formatting.          (line 118)
5527
* conventions for makefiles:             Makefile Conventions.
5528
                                                              (line   6)
5529
* CORBA:                                 Graphical Interfaces.
5530
                                                              (line  16)
5531
* credits for manuals:                   Manual Credits.      (line   6)
5532
* D-bus:                                 Graphical Interfaces.
5533
                                                              (line  16)
5534
* data types, and portability:           CPU Portability.     (line   6)
5535
* declaration for system functions:      System Functions.    (line  21)
5536
* DESTDIR:                               DESTDIR.             (line   6)
5537
* documentation:                         Documentation.       (line   6)
5538
* doschk:                                Names.               (line  38)
5539
* downloading this manual:               Preface.             (line  14)
5540
* encodings:                             Character Set.       (line   6)
5541
* error messages:                        Semantics.           (line  19)
5542
* error messages, formatting:            Errors.              (line   6)
5543
* exec_prefix:                           Directory Variables. (line  36)
5544
* expressions, splitting:                Formatting.          (line  81)
5545
* FDL, GNU Free Documentation License:   GNU Free Documentation License.
5546
                                                              (line   6)
5547
* file usage:                            File Usage.          (line   6)
5548
* file-name limitations:                 Names.               (line  38)
5549
* formatting error messages:             Errors.              (line   6)
5550
* formatting source code:                Formatting.          (line   6)
5551
* formfeed:                              Formatting.          (line 118)
5552
* function argument, declaring:          Syntactic Conventions.
5553
                                                              (line   6)
5554
* function prototypes:                   Standard C.          (line  17)
5555
* getopt:                                Command-Line Interfaces.
5556
                                                              (line   6)
5557
* gettext:                               Internationalization.
5558
                                                              (line   6)
5559
* GNOME:                                 Graphical Interfaces.
5560
                                                              (line  16)
5561
* GNOME and Guile:                       Source Language.     (line  38)
5562
* gnustandards project repository:       Preface.             (line  30)
5563
* gnustandards-commit@gnu.org mailing list: Preface.          (line  24)
5564
* graphical user interface:              Graphical Interfaces.
5565
                                                              (line   6)
5566
* grave accent:                          Quote Characters.    (line   6)
5567
* GTK+:                                  Graphical Interfaces.
5568
                                                              (line   6)
5569
* Guile:                                 Source Language.     (line  38)
5570
* implicit int:                          Syntactic Conventions.
5571
                                                              (line   6)
5572
* impossible conditions:                 Semantics.           (line  70)
5573
* installations, staged:                 DESTDIR.             (line   6)
5574
* interface styles:                      Graphical Interfaces.
5575
                                                              (line   6)
5576
* internationalization:                  Internationalization.
5577
                                                              (line   6)
5578
* keyboard interface:                    Graphical Interfaces.
5579
                                                              (line  16)
5580
* LDAP:                                  OID Allocations.     (line   6)
5581
* left quote:                            Quote Characters.    (line   6)
5582
* legal aspects:                         Legal Issues.        (line   6)
5583
* legal papers:                          Contributions.       (line   6)
5584
* libexecdir:                            Directory Variables. (line  67)
5585
* libraries:                             Libraries.           (line   6)
5586
* library functions, and portability:    System Functions.    (line   6)
5587
* library interface:                     Graphical Interfaces.
5588
                                                              (line  16)
5589
* license for manuals:                   License for Manuals. (line   6)
5590
* lint:                                  Syntactic Conventions.
5591
                                                              (line 109)
5592
* locale-specific quote characters:      Quote Characters.    (line   6)
5593
* long option names:                     Option Table.        (line   6)
5594
* long-named options:                    Command-Line Interfaces.
5595
                                                              (line  12)
5596
* makefile, conventions for:             Makefile Conventions.
5597
                                                              (line   6)
5598
* malloc return value:                   Semantics.           (line  25)
5599
* man pages:                             Man Pages.           (line   6)
5600
* manual structure:                      Manual Structure Details.
5601
                                                              (line   6)
5602
* memory allocation failure:             Semantics.           (line  25)
5603
* memory usage:                          Memory Usage.        (line   6)
5604
* message text, and internationalization: Internationalization.
5605
                                                              (line  29)
5606
* mmap:                                  Mmap.                (line   6)
5607
* multiple variables in a line:          Syntactic Conventions.
5608
                                                              (line  35)
5609
* names of variables, functions, and files: Names.            (line   6)
5610
* NEWS file:                             NEWS File.           (line   6)
5611
* non-ASCII characters:                  Character Set.       (line   6)
5612
* non-POSIX systems, and portability:    System Portability.  (line  32)
5613
* non-standard extensions:               Using Extensions.    (line   6)
5614
* NUL characters:                        Semantics.           (line  11)
5615
* OID allocations for GNU:               OID Allocations.     (line   6)
5616
* open brace:                            Formatting.          (line   6)
5617
* optional features, configure-time:     Configuration.       (line 100)
5618
* options for compatibility:             Compatibility.       (line  14)
5619
* options, standard command-line:        Command-Line Interfaces.
5620
                                                              (line  31)
5621
* output device and program's behavior:  User Interfaces.     (line  13)
5622
* packaging:                             Releases.            (line   6)
5623
* PATH_INFO, specifying standard options as: Command-Line Interfaces.
5624
                                                              (line  31)
5625
* portability, and data types:           CPU Portability.     (line   6)
5626
* portability, and library functions:    System Functions.    (line   6)
5627
* portability, between system types:     System Portability.  (line   6)
5628
* POSIX compatibility:                   Compatibility.       (line   6)
5629
* POSIXLY_CORRECT, environment variable: Compatibility.       (line  21)
5630
* post-installation commands:            Install Command Categories.
5631
                                                              (line   6)
5632
* pre-installation commands:             Install Command Categories.
5633
                                                              (line   6)
5634
* prefix:                                Directory Variables. (line  26)
5635
* program configuration:                 Configuration.       (line   6)
5636
* program design:                        Design Advice.       (line   6)
5637
* program name and its behavior:         User Interfaces.     (line   6)
5638
* program's canonical name:              --version.           (line  12)
5639
* programming languages:                 Source Language.     (line   6)
5640
* proprietary programs:                  Reading Non-Free Code.
5641
                                                              (line   6)
5642
* quote characters:                      Quote Characters.    (line   6)
5643
* README file:                           Releases.            (line  21)
5644
* references to non-free material:       References.          (line   6)
5645
* releasing:                             Managing Releases.   (line   6)
5646
* Savannah repository for gnustandards:  Preface.             (line  30)
5647
* sbindir:                               Directory Variables. (line  60)
5648
* signal handling:                       Semantics.           (line  59)
5649
* SNMP:                                  OID Allocations.     (line   6)
5650
* spaces before open-paren:              Formatting.          (line  75)
5651
* staged installs:                       DESTDIR.             (line   6)
5652
* standard command-line options:         Command-Line Interfaces.
5653
                                                              (line  31)
5654
* standards for makefiles:               Makefile Conventions.
5655
                                                              (line   6)
5656
* string library functions:              System Functions.    (line  55)
5657
* syntactic conventions:                 Syntactic Conventions.
5658
                                                              (line   6)
5659
* table of long options:                 Option Table.        (line   6)
5660
* temporary files:                       Semantics.           (line  84)
5661
* temporary variables:                   Syntactic Conventions.
5662
                                                              (line  23)
5663
* texinfo.tex, in a distribution:        Releases.            (line  70)
5664
* TMPDIR environment variable:           Semantics.           (line  84)
5665
* trademarks:                            Trademarks.          (line   6)
5666
* user interface styles:                 Graphical Interfaces.
5667
 
5668
 
5669
* X.509:                                 OID Allocations.     (line   6)
5670
5671
5672

5673
Tag Table:
5674
Node: Top814
5675
Node: Preface2089
5676
Node: Legal Issues4802
5677
Node: Reading Non-Free Code5272
5678
Node: Contributions7002
5679
Node: Trademarks9240
5680
Node: Design Advice10875
5681
Node: Source Language11467
5682
Node: Compatibility13593
5683
Node: Using Extensions15221
5684
Node: Standard C16797
5685
Node: Conditional Compilation19200
5686
Node: Program Behavior20598
5687
Node: Non-GNU Standards21714
5688
Node: Semantics23995
5689
Node: Libraries28715
5690
Node: Errors29960
5691
Node: User Interfaces32453
5692
Node: Graphical Interfaces34058
5693
Node: Command-Line Interfaces35242
5694
Node: --version37274
5695
Node: --help43011
5696
Node: Option Table43884
5697
Node: OID Allocations58839
5698
Node: Memory Usage60636
5699
Node: File Usage61672
5700
Node: Writing C62422
5701
Node: Formatting63394
5702
Node: Comments67683
5703
Node: Syntactic Conventions71235
5704
Node: Names74697
5705
Node: System Portability76909
5706
Node: CPU Portability79800
5707
Node: System Functions83701
5708
Node: Internationalization88898
5709
Node: Character Set92892
5710
Node: Quote Characters93705
5711
Node: Mmap95225
5712
Node: Documentation95933
5713
Node: GNU Manuals97039
5714
Node: Doc Strings and Manuals102777
5715
Node: Manual Structure Details104330
5716
Node: License for Manuals105748
5717
Node: Manual Credits106722
5718
Node: Printed Manuals107115
5719
Node: NEWS File107801
5720
Node: Change Logs108479
5721
Node: Change Log Concepts109233
5722
Node: Style of Change Logs111336
5723
Node: Simple Changes113836
5724
Node: Conditional Changes115278
5725
Node: Indicating the Part Changed116700
5726
Node: Man Pages117227
5727
Node: Reading other Manuals119433
5728
Node: Managing Releases120224
5729
Node: Configuration121005
5730
Node: Makefile Conventions129670
5731
Node: Makefile Basics130552
5732
Node: Utilities in Makefiles133726
5733
Node: Command Variables135871
5734
Node: DESTDIR139093
5735
Node: Directory Variables141242
5736
Node: Standard Targets155735
5737
Ref: Standard Targets-Footnote-1169250
5738
Node: Install Command Categories169350
5739
Node: Releases173883
5740
Node: References177888
5741
Node: GNU Free Documentation License183735

powered by: WebSVN 2.1.0

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