This commit was manufactured by cvs2svn to create branch 'utf-2000'.
[chise/xemacs-chise.git-] / info / standards.info-2
1 This is ../info/standards.info, produced by makeinfo version 4.0 from
2 standards.texi.
3
4 START-INFO-DIR-ENTRY
5 * Standards: (standards).        GNU coding standards.
6 END-INFO-DIR-ENTRY
7
8    GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
9 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
10
11    Permission is granted to make and distribute verbatim copies of this
12 manual provided the copyright notice and this permission notice are
13 preserved on all copies.
14
15    Permission is granted to copy and distribute modified versions of
16 this manual under the conditions for verbatim copying, provided that
17 the entire resulting derived work is distributed under the terms of a
18 permission notice identical to this one.
19
20    Permission is granted to copy and distribute translations of this
21 manual into another language, under the above conditions for modified
22 versions, except that this permission notice may be stated in a
23 translation approved by the Free Software Foundation.
24
25 \1f
26 File: standards.info,  Node: Formatting,  Next: Comments,  Up: Writing C
27
28 Formatting Your Source Code
29 ===========================
30
31    It is important to put the open-brace that starts the body of a C
32 function in column zero, and avoid putting any other open-brace or
33 open-parenthesis or open-bracket in column zero.  Several tools look
34 for open-braces in column zero to find the beginnings of C functions.
35 These tools will not work on code not formatted that way.
36
37    It is also important for function definitions to start the name of
38 the function in column zero.  This helps people to search for function
39 definitions, and may also help certain tools recognize them.  Thus, the
40 proper format is this:
41
42      static char *
43      concat (s1, s2)        /* Name starts in column zero here */
44           char *s1, *s2;
45      {                     /* Open brace in column zero here */
46        ...
47      }
48
49 or, if you want to use Standard C syntax, format the definition like
50 this:
51
52      static char *
53      concat (char *s1, char *s2)
54      {
55        ...
56      }
57
58    In Standard C, if the arguments don't fit nicely on one line, split
59 it like this:
60
61      int
62      lots_of_args (int an_integer, long a_long, short a_short,
63                    double a_double, float a_float)
64      ...
65
66    The rest of this section gives our recommendations for other aspects
67 of C formatting style, which is also the default style of the `indent'
68 program in version 1.2 and newer.  It corresponds to the options
69
70      -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
71      -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
72
73    We don't think of these recommendations as requirements, because it
74 causes no problems for users if two different programs have different
75 formatting styles.
76
77    But whatever style you use, please use it consistently, since a
78 mixture of styles within one program tends to look ugly.  If you are
79 contributing changes to an existing program, please follow the style of
80 that program.
81
82    For the body of the function, our recommended style looks like this:
83
84      if (x < foo (y, z))
85        haha = bar[4] + 5;
86      else
87        {
88          while (z)
89            {
90              haha += foo (z, z);
91              z--;
92            }
93          return ++x + bar ();
94        }
95
96    We find it easier to read a program when it has spaces before the
97 open-parentheses and after the commas.  Especially after the commas.
98
99    When you split an expression into multiple lines, split it before an
100 operator, not after one.  Here is the right way:
101
102      if (foo_this_is_long && bar > win (x, y, z)
103          && remaining_condition)
104
105    Try to avoid having two operators of different precedence at the same
106 level of indentation.  For example, don't write this:
107
108      mode = (inmode[j] == VOIDmode
109              || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
110              ? outmode[j] : inmode[j]);
111
112    Instead, use extra parentheses so that the indentation shows the
113 nesting:
114
115      mode = ((inmode[j] == VOIDmode
116               || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
117              ? outmode[j] : inmode[j]);
118
119    Insert extra parentheses so that Emacs will indent the code properly.
120 For example, the following indentation looks nice if you do it by hand,
121
122      v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
123          + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
124
125 but Emacs would alter it.  Adding a set of parentheses produces
126 something that looks equally nice, and which Emacs will preserve:
127
128      v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
129           + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
130
131    Format do-while statements like this:
132
133      do
134        {
135          a = foo (a);
136        }
137      while (a > 0);
138
139    Please use formfeed characters (control-L) to divide the program into
140 pages at logical places (but not within a function).  It does not matter
141 just how long the pages are, since they do not have to fit on a printed
142 page.  The formfeeds should appear alone on lines by themselves.
143
144 \1f
145 File: standards.info,  Node: Comments,  Next: Syntactic Conventions,  Prev: Formatting,  Up: Writing C
146
147 Commenting Your Work
148 ====================
149
150    Every program should start with a comment saying briefly what it is
151 for.  Example: `fmt - filter for simple filling of text'.
152
153    Please write the comments in a GNU program in English, because
154 English is the one language that nearly all programmers in all
155 countries can read.  If you do not write English well, please write
156 comments in English as well as you can, then ask other people to help
157 rewrite them.  If you can't write comments in English, please find
158 someone to work with you and translate your comments into English.
159
160    Please put a comment on each function saying what the function does,
161 what sorts of arguments it gets, and what the possible values of
162 arguments mean and are used for.  It is not necessary to duplicate in
163 words the meaning of the C argument declarations, if a C type is being
164 used in its customary fashion.  If there is anything nonstandard about
165 its use (such as an argument of type `char *' which is really the
166 address of the second character of a string, not the first), or any
167 possible values that would not work the way one would expect (such as,
168 that strings containing newlines are not guaranteed to work), be sure
169 to say so.
170
171    Also explain the significance of the return value, if there is one.
172
173    Please put two spaces after the end of a sentence in your comments,
174 so that the Emacs sentence commands will work.  Also, please write
175 complete sentences and capitalize the first word.  If a lower-case
176 identifier comes at the beginning of a sentence, don't capitalize it!
177 Changing the spelling makes it a different identifier.  If you don't
178 like starting a sentence with a lower case letter, write the sentence
179 differently (e.g., "The identifier lower-case is ...").
180
181    The comment on a function is much clearer if you use the argument
182 names to speak about the argument values.  The variable name itself
183 should be lower case, but write it in upper case when you are speaking
184 about the value rather than the variable itself.  Thus, "the inode
185 number NODE_NUM" rather than "an inode".
186
187    There is usually no purpose in restating the name of the function in
188 the comment before it, because the reader can see that for himself.
189 There might be an exception when the comment is so long that the
190 function itself would be off the bottom of the screen.
191
192    There should be a comment on each static variable as well, like this:
193
194      /* Nonzero means truncate lines in the display;
195         zero means continue them.  */
196      int truncate_lines;
197
198    Every `#endif' should have a comment, except in the case of short
199 conditionals (just a few lines) that are not nested.  The comment should
200 state the condition of the conditional that is ending, _including its
201 sense_.  `#else' should have a comment describing the condition _and
202 sense_ of the code that follows.  For example:
203
204      #ifdef foo
205        ...
206      #else /* not foo */
207        ...
208      #endif /* not foo */
209      #ifdef foo
210        ...
211      #endif /* foo */
212
213 but, by contrast, write the comments this way for a `#ifndef':
214
215      #ifndef foo
216        ...
217      #else /* foo */
218        ...
219      #endif /* foo */
220      #ifndef foo
221        ...
222      #endif /* not foo */
223
224 \1f
225 File: standards.info,  Node: Syntactic Conventions,  Next: Names,  Prev: Comments,  Up: Writing C
226
227 Clean Use of C Constructs
228 =========================
229
230    Please explicitly declare the types of all objects.  For example, you
231 should explicitly declare all arguments to functions, and you should
232 declare functions to return `int' rather than omitting the `int'.
233
234    Some programmers like to use the GCC `-Wall' option, and change the
235 code whenever it issues a warning.  If you want to do this, then do.
236 Other programmers prefer not to use `-Wall', because it gives warnings
237 for valid and legitimate code which they do not want to change.  If you
238 want to do this, then do.  The compiler should be your servant, not
239 your master.
240
241    Declarations of external functions and functions to appear later in
242 the source file should all go in one place near the beginning of the
243 file (somewhere before the first function definition in the file), or
244 else should go in a header file.  Don't put `extern' declarations inside
245 functions.
246
247    It used to be common practice to use the same local variables (with
248 names like `tem') over and over for different values within one
249 function.  Instead of doing this, it is better declare a separate local
250 variable for each distinct purpose, and give it a name which is
251 meaningful.  This not only makes programs easier to understand, it also
252 facilitates optimization by good compilers.  You can also move the
253 declaration of each local variable into the smallest scope that includes
254 all its uses.  This makes the program even cleaner.
255
256    Don't use local variables or parameters that shadow global
257 identifiers.
258
259    Don't declare multiple variables in one declaration that spans lines.
260 Start a new declaration on each line, instead.  For example, instead of
261 this:
262
263      int    foo,
264             bar;
265
266 write either this:
267
268      int foo, bar;
269
270 or this:
271
272      int foo;
273      int bar;
274
275 (If they are global variables, each should have a comment preceding it
276 anyway.)
277
278    When you have an `if'-`else' statement nested in another `if'
279 statement, always put braces around the `if'-`else'.  Thus, never write
280 like this:
281
282      if (foo)
283        if (bar)
284          win ();
285        else
286          lose ();
287
288 always like this:
289
290      if (foo)
291        {
292          if (bar)
293            win ();
294          else
295            lose ();
296        }
297
298    If you have an `if' statement nested inside of an `else' statement,
299 either write `else if' on one line, like this,
300
301      if (foo)
302        ...
303      else if (bar)
304        ...
305
306 with its `then'-part indented like the preceding `then'-part, or write
307 the nested `if' within braces like this:
308
309      if (foo)
310        ...
311      else
312        {
313          if (bar)
314            ...
315        }
316
317    Don't declare both a structure tag and variables or typedefs in the
318 same declaration.  Instead, declare the structure tag separately and
319 then use it to declare the variables or typedefs.
320
321    Try to avoid assignments inside `if'-conditions.  For example, don't
322 write this:
323
324      if ((foo = (char *) malloc (sizeof *foo)) == 0)
325        fatal ("virtual memory exhausted");
326
327 instead, write this:
328
329      foo = (char *) malloc (sizeof *foo);
330      if (foo == 0)
331        fatal ("virtual memory exhausted");
332
333    Don't make the program ugly to placate `lint'.  Please don't insert
334 any casts to `void'.  Zero without a cast is perfectly fine as a null
335 pointer constant, except when calling a varargs function.
336
337 \1f
338 File: standards.info,  Node: Names,  Next: System Portability,  Prev: Syntactic Conventions,  Up: Writing C
339
340 Naming Variables and Functions
341 ==============================
342
343    The names of global variables and functions in a program serve as
344 comments of a sort.  So don't choose terse names--instead, look for
345 names that give useful information about the meaning of the variable or
346 function.  In a GNU program, names should be English, like other
347 comments.
348
349    Local variable names can be shorter, because they are used only
350 within one context, where (presumably) comments explain their purpose.
351
352    Try to limit your use of abbreviations in symbol names.  It is ok to
353 make a few abbreviations, explain what they mean, and then use them
354 frequently, but don't use lots of obscure abbreviations.
355
356    Please use underscores to separate words in a name, so that the Emacs
357 word commands can be useful within them.  Stick to lower case; reserve
358 upper case for macros and `enum' constants, and for name-prefixes that
359 follow a uniform convention.
360
361    For example, you should use names like `ignore_space_change_flag';
362 don't use names like `iCantReadThis'.
363
364    Variables that indicate whether command-line options have been
365 specified should be named after the meaning of the option, not after
366 the option-letter.  A comment should state both the exact meaning of
367 the option and its letter.  For example,
368
369      /* Ignore changes in horizontal whitespace (-b).  */
370      int ignore_space_change_flag;
371
372    When you want to define names with constant integer values, use
373 `enum' rather than `#define'.  GDB knows about enumeration constants.
374
375    You might want to make sure that none of the file names would
376 conflict the files were loaded onto an MS-DOS file system which
377 shortens the names.  You can use the program `doschk' to test for this.
378
379    Some GNU programs were designed to limit themselves to file names of
380 14 characters or less, to avoid file name conflicts if they are read
381 into older System V systems.  Please preserve this feature in the
382 existing GNU programs that have it, but there is no need to do this in
383 new GNU programs.  `doschk' also reports file names longer than 14
384 characters.
385
386 \1f
387 File: standards.info,  Node: System Portability,  Next: CPU Portability,  Prev: Names,  Up: Writing C
388
389 Portability between System Types
390 ================================
391
392    In the Unix world, "portability" refers to porting to different Unix
393 versions.  For a GNU program, this kind of portability is desirable, but
394 not paramount.
395
396    The primary purpose of GNU software is to run on top of the GNU
397 kernel, compiled with the GNU C compiler, on various types of CPU.  So
398 the kinds of portability that are absolutely necessary are quite
399 limited.  But it is important to support Linux-based GNU systems, since
400 they are the form of GNU that is popular.
401
402    Beyond that, it is good to support the other free operating systems
403 (*BSD), and it is nice to support other Unix-like systems if you want
404 to.  Supporting a variety of Unix-like systems is desirable, although
405 not paramount.  It is usually not too hard, so you may as well do it.
406 But you don't have to consider it an obligation, if it does turn out to
407 be hard.
408
409    The easiest way to achieve portability to most Unix-like systems is
410 to use Autoconf.  It's unlikely that your program needs to know more
411 information about the host platform than Autoconf can provide, simply
412 because most of the programs that need such knowledge have already been
413 written.
414
415    Avoid using the format of semi-internal data bases (e.g.,
416 directories) when there is a higher-level alternative (`readdir').
417
418    As for systems that are not like Unix, such as MSDOS, Windows, the
419 Macintosh, VMS, and MVS, supporting them is often a lot of work.  When
420 that is the case, it is better to spend your time adding features that
421 will be useful on GNU and GNU/Linux, rather than on supporting other
422 incompatible systems.
423
424    It is a good idea to define the "feature test macro" `_GNU_SOURCE'
425 when compiling your C files.  When you compile on GNU or GNU/Linux,
426 this will enable the declarations of GNU library extension functions,
427 and that will usually give you a compiler error message if you define
428 the same function names in some other way in your program.  (You don't
429 have to actually _use_ these functions, if you prefer to make the
430 program more portable to other systems.)
431
432    But whether or not you use these GNU extensions, you should avoid
433 using their names for any other meanings.  Doing so would make it hard
434 to move your code into other GNU programs.
435
436 \1f
437 File: standards.info,  Node: CPU Portability,  Next: System Functions,  Prev: System Portability,  Up: Writing C
438
439 Portability between CPUs
440 ========================
441
442    Even GNU systems will differ because of differences among CPU
443 types--for example, difference in byte ordering and alignment
444 requirements.  It is absolutely essential to handle these differences.
445 However, don't make any effort to cater to the possibility that an
446 `int' will be less than 32 bits.  We don't support 16-bit machines in
447 GNU.
448
449    Similarly, don't make any effort to cater to the possibility that
450 `long' will be smaller than predefined types like `size_t'.  For
451 example, the following code is ok:
452
453      printf ("size = %lu\n", (unsigned long) sizeof array);
454      printf ("diff = %ld\n", (long) (pointer2 - pointer1));
455
456    1989 Standard C requires this to work, and we know of only one
457 counterexample: 64-bit programs on Microsoft Windows IA-64.  We will
458 leave it to those who want to port GNU programs to that environment to
459 figure out how to do it.
460
461    Predefined file-size types like `off_t' are an exception: they are
462 longer than `long' on many platforms, so code like the above won't work
463 with them.  One way to print an `off_t' value portably is to print its
464 digits yourself, one by one.
465
466    Don't assume that the address of an `int' object is also the address
467 of its least-significant byte.  This is false on big-endian machines.
468 Thus, don't make the following mistake:
469
470      int c;
471      ...
472      while ((c = getchar()) != EOF)
473        write(file_descriptor, &c, 1);
474
475    When calling functions, you need not worry about the difference
476 between pointers of various types, or between pointers and integers.
477 On most machines, there's no difference anyway.  As for the few
478 machines where there is a difference, all of them support Standard C
479 prototypes, so you can use prototypes (perhaps conditionalized to be
480 active only in Standard C) to make the code work on those systems.
481
482    In certain cases, it is ok to pass integer and pointer arguments
483 indiscriminately to the same function, and use no prototype on any
484 system.  For example, many GNU programs have error-reporting functions
485 that pass their arguments along to `printf' and friends:
486
487      error (s, a1, a2, a3)
488           char *s;
489           char *a1, *a2, *a3;
490      {
491        fprintf (stderr, "error: ");
492        fprintf (stderr, s, a1, a2, a3);
493      }
494
495 In practice, this works on all machines, since a pointer is generally
496 the widest possible kind of argument; it is much simpler than any
497 "correct" alternative.  Be sure _not_ to use a prototype for such
498 functions.
499
500    If you have decided to use Standard C, then you can instead define
501 `error' using `stdarg.h', and pass the arguments along to `vfprintf'.
502
503    Avoid casting pointers to integers if you can.  Such casts greatly
504 reduce portability, and in most programs they are easy to avoid.  In the
505 cases where casting pointers to integers is essential--such as, a Lisp
506 interpreter which stores type information as well as an address in one
507 word--you'll have to make explicit provisions to handle different word
508 sizes.  You will also need to make provision for systems in which the
509 normal range of addresses you can get from `malloc' starts far away
510 from zero.
511
512 \1f
513 File: standards.info,  Node: System Functions,  Next: Internationalization,  Prev: CPU Portability,  Up: Writing C
514
515 Calling System Functions
516 ========================
517
518    C implementations differ substantially.  Standard C reduces but does
519 not eliminate the incompatibilities; meanwhile, many GNU packages still
520 support pre-standard compilers because this is not hard to do.  This
521 chapter gives recommendations for how to use the more-or-less standard C
522 library functions to avoid unnecessary loss of portability.
523
524    * Don't use the return value of `sprintf'.  It returns the number of
525      characters written on some systems, but not on all systems.
526
527    * Be aware that `vfprintf' is not always available.
528
529    * `main' should be declared to return type `int'.  It should
530      terminate either by calling `exit' or by returning the integer
531      status code; make sure it cannot ever return an undefined value.
532
533    * Don't declare system functions explicitly.
534
535      Almost any declaration for a system function is wrong on some
536      system.  To minimize conflicts, leave it to the system header
537      files to declare system functions.  If the headers don't declare a
538      function, let it remain undeclared.
539
540      While it may seem unclean to use a function without declaring it,
541      in practice this works fine for most system library functions on
542      the systems where this really happens; thus, the disadvantage is
543      only theoretical.  By contrast, actual declarations have
544      frequently caused actual conflicts.
545
546    * If you must declare a system function, don't specify the argument
547      types.  Use an old-style declaration, not a Standard C prototype.
548      The more you specify about the function, the more likely a
549      conflict.
550
551    * In particular, don't unconditionally declare `malloc' or `realloc'.
552
553      Most GNU programs use those functions just once, in functions
554      conventionally named `xmalloc' and `xrealloc'.  These functions
555      call `malloc' and `realloc', respectively, and check the results.
556
557      Because `xmalloc' and `xrealloc' are defined in your program, you
558      can declare them in other files without any risk of type conflict.
559
560      On most systems, `int' is the same length as a pointer; thus, the
561      calls to `malloc' and `realloc' work fine.  For the few
562      exceptional systems (mostly 64-bit machines), you can use
563      *conditionalized* declarations of `malloc' and `realloc'--or put
564      these declarations in configuration files specific to those
565      systems.
566
567    * The string functions require special treatment.  Some Unix systems
568      have a header file `string.h'; others have `strings.h'.  Neither
569      file name is portable.  There are two things you can do: use
570      Autoconf to figure out which file to include, or don't include
571      either file.
572
573    * If you don't include either strings file, you can't get
574      declarations for the string functions from the header file in the
575      usual way.
576
577      That causes less of a problem than you might think.  The newer
578      standard string functions should be avoided anyway because many
579      systems still don't support them.  The string functions you can
580      use are these:
581
582           strcpy   strncpy   strcat   strncat
583           strlen   strcmp    strncmp
584           strchr   strrchr
585
586      The copy and concatenate functions work fine without a declaration
587      as long as you don't use their values.  Using their values without
588      a declaration fails on systems where the width of a pointer
589      differs from the width of `int', and perhaps in other cases.  It
590      is trivial to avoid using their values, so do that.
591
592      The compare functions and `strlen' work fine without a declaration
593      on most systems, possibly all the ones that GNU software runs on.
594      You may find it necessary to declare them *conditionally* on a few
595      systems.
596
597      The search functions must be declared to return `char *'.  Luckily,
598      there is no variation in the data type they return.  But there is
599      variation in their names.  Some systems give these functions the
600      names `index' and `rindex'; other systems use the names `strchr'
601      and `strrchr'.  Some systems support both pairs of names, but
602      neither pair works on all systems.
603
604      You should pick a single pair of names and use it throughout your
605      program.  (Nowadays, it is better to choose `strchr' and `strrchr'
606      for new programs, since those are the standard names.)  Declare
607      both of those names as functions returning `char *'.  On systems
608      which don't support those names, define them as macros in terms of
609      the other pair.  For example, here is what to put at the beginning
610      of your file (or in a header) if you want to use the names
611      `strchr' and `strrchr' throughout:
612
613           #ifndef HAVE_STRCHR
614           #define strchr index
615           #endif
616           #ifndef HAVE_STRRCHR
617           #define strrchr rindex
618           #endif
619           
620           char *strchr ();
621           char *strrchr ();
622
623    Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
624 defined in systems where the corresponding functions exist.  One way to
625 get them properly defined is to use Autoconf.
626
627 \1f
628 File: standards.info,  Node: Internationalization,  Next: Mmap,  Prev: System Functions,  Up: Writing C
629
630 Internationalization
631 ====================
632
633    GNU has a library called GNU gettext that makes it easy to translate
634 the messages in a program into various languages.  You should use this
635 library in every program.  Use English for the messages as they appear
636 in the program, and let gettext provide the way to translate them into
637 other languages.
638
639    Using GNU gettext involves putting a call to the `gettext' macro
640 around each string that might need translation--like this:
641
642      printf (gettext ("Processing file `%s'..."));
643
644 This permits GNU gettext to replace the string `"Processing file
645 `%s'..."' with a translated version.
646
647    Once a program uses gettext, please make a point of writing calls to
648 `gettext' when you add new strings that call for translation.
649
650    Using GNU gettext in a package involves specifying a "text domain
651 name" for the package.  The text domain name is used to separate the
652 translations for this package from the translations for other packages.
653 Normally, the text domain name should be the same as the name of the
654 package--for example, `fileutils' for the GNU file utilities.
655
656    To enable gettext to work well, avoid writing code that makes
657 assumptions about the structure of words or sentences.  When you want
658 the precise text of a sentence to vary depending on the data, use two or
659 more alternative string constants each containing a complete sentences,
660 rather than inserting conditionalized words or phrases into a single
661 sentence framework.
662
663    Here is an example of what not to do:
664
665      printf ("%d file%s processed", nfiles,
666              nfiles != 1 ? "s" : "");
667
668 The problem with that example is that it assumes that plurals are made
669 by adding `s'.  If you apply gettext to the format string, like this,
670
671      printf (gettext ("%d file%s processed"), nfiles,
672              nfiles != 1 ? "s" : "");
673
674 the message can use different words, but it will still be forced to use
675 `s' for the plural.  Here is a better way:
676
677      printf ((nfiles != 1 ? "%d files processed"
678               : "%d file processed"),
679              nfiles);
680
681 This way, you can apply gettext to each of the two strings
682 independently:
683
684      printf ((nfiles != 1 ? gettext ("%d files processed")
685               : gettext ("%d file processed")),
686              nfiles);
687
688 This can be any method of forming the plural of the word for "file", and
689 also handles languages that require agreement in the word for
690 "processed".
691
692    A similar problem appears at the level of sentence structure with
693 this code:
694
695      printf ("#  Implicit rule search has%s been done.\n",
696              f->tried_implicit ? "" : " not");
697
698 Adding `gettext' calls to this code cannot give correct results for all
699 languages, because negation in some languages requires adding words at
700 more than one place in the sentence.  By contrast, adding `gettext'
701 calls does the job straightfowardly if the code starts out like this:
702
703      printf (f->tried_implicit
704              ? "#  Implicit rule search has been done.\n",
705              : "#  Implicit rule search has not been done.\n");
706
707 \1f
708 File: standards.info,  Node: Mmap,  Prev: Internationalization,  Up: Writing C
709
710 Mmap
711 ====
712
713    Don't assume that `mmap' either works on all files or fails for all
714 files.  It may work on some files and fail on others.
715
716    The proper way to use `mmap' is to try it on the specific file for
717 which you want to use it--and if `mmap' doesn't work, fall back on
718 doing the job in another way using `read' and `write'.
719
720    The reason this precaution is needed is that the GNU kernel (the
721 HURD) provides a user-extensible file system, in which there can be many
722 different kinds of "ordinary files."  Many of them support `mmap', but
723 some do not.  It is important to make programs handle all these kinds
724 of files.
725
726 \1f
727 File: standards.info,  Node: Documentation,  Next: Managing Releases,  Prev: Writing C,  Up: Top
728
729 Documenting Programs
730 ********************
731
732    A GNU program should ideally come with full free documentation,
733 adequate for both reference and tutorial purposes.  If the package can
734 be programmed or extended, the documentation should cover programming or
735 extending it, as well as just using it.
736
737 * Menu:
738
739 * GNU Manuals::                 Writing proper manuals.
740 * Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
741 * Manual Structure Details::    Specific structure conventions.
742 * License for Manuals::         Writing the distribution terms for a manual.
743 * Manual Credits::              Giving credit to documentation contributors.
744 * Printed Manuals::             Mentioning the printed manual.
745 * NEWS File::                   NEWS files supplement manuals.
746 * Change Logs::                 Recording Changes
747 * Man Pages::                   Man pages are secondary.
748 * Reading other Manuals::       How far you can go in learning
749                                 from other manuals.
750
751 \1f
752 File: standards.info,  Node: GNU Manuals,  Next: Doc Strings and Manuals,  Up: Documentation
753
754 GNU Manuals
755 ===========
756
757    The preferred document format for the GNU system is the Texinfo
758 formatting language.  Every GNU package should (ideally) have
759 documentation in Texinfo both for reference and for learners.  Texinfo
760 makes it possible to produce a good quality formatted book, using TeX,
761 and to generate an Info file.  It is also possible to generate HTML
762 output from Texinfo source.  See the Texinfo manual, either the
763 hardcopy, or the on-line version available through `info' or the Emacs
764 Info subsystem (`C-h i').
765
766    Nowadays some other formats such as Docbook and Sgmltexi can be
767 converted automatically into Texinfo.  It is ok to produce the Texinfo
768 documentation by conversion this way, as long as it gives good results.
769
770    Programmers often find it most natural to structure the documentation
771 following the structure of the implementation, which they know.  But
772 this structure is not necessarily good for explaining how to use the
773 program; it may be irrelevant and confusing for a user.
774
775    At every level, from the sentences in a paragraph to the grouping of
776 topics into separate manuals, the right way to structure documentation
777 is according to the concepts and questions that a user will have in mind
778 when reading it.  Sometimes this structure of ideas matches the
779 structure of the implementation of the software being documented--but
780 often they are different.  Often the most important part of learning to
781 write good documentation is learning to notice when you are structuring
782 the documentation like the implementation, and think about better
783 alternatives.
784
785    For example, each program in the GNU system probably ought to be
786 documented in one manual; but this does not mean each program should
787 have its own manual.  That would be following the structure of the
788 implementation, rather than the structure that helps the user
789 understand.
790
791    Instead, each manual should cover a coherent _topic_.  For example,
792 instead of a manual for `diff' and a manual for `diff3', we have one
793 manual for "comparison of files" which covers both of those programs,
794 as well as `cmp'.  By documenting these programs together, we can make
795 the whole subject clearer.
796
797    The manual which discusses a program should certainly document all of
798 the program's command-line options and all of its commands.  It should
799 give examples of their use.  But don't organize the manual as a list of
800 features.  Instead, organize it logically, by subtopics.  Address the
801 questions that a user will ask when thinking about the job that the
802 program does.
803
804    In general, a GNU manual should serve both as tutorial and reference.
805 It should be set up for convenient access to each topic through Info,
806 and for reading straight through (appendixes aside).  A GNU manual
807 should give a good introduction to a beginner reading through from the
808 start, and should also provide all the details that hackers want.  The
809 Bison manual is a good example of this--please take a look at it to see
810 what we mean.
811
812    That is not as hard as it first sounds.  Arrange each chapter as a
813 logical breakdown of its topic, but order the sections, and write their
814 text, so that reading the chapter straight through makes sense.  Do
815 likewise when structuring the book into chapters, and when structuring a
816 section into paragraphs.  The watchword is, _at each point, address the
817 most fundamental and important issue raised by the preceding text._
818
819    If necessary, add extra chapters at the beginning of the manual which
820 are purely tutorial and cover the basics of the subject.  These provide
821 the framework for a beginner to understand the rest of the manual.  The
822 Bison manual provides a good example of how to do this.
823
824    To serve as a reference, a manual should have an Index that list all
825 the functions, variables, options, and important concepts that are part
826 of the program.  One combined Index should do for a short manual, but
827 sometimes for a complex package it is better to use multiple indices.
828 The Texinfo manual includes advice on preparing good index entries, see
829 *Note Making Index Entries: (texinfo)Index Entries, and see *Note
830 Defining the Entries of an Index: (texinfo)Indexing Commands.
831
832    Don't use Unix man pages as a model for how to write GNU
833 documentation; most of them are terse, badly structured, and give
834 inadequate explanation of the underlying concepts.  (There are, of
835 course, some exceptions.)  Also, Unix man pages use a particular format
836 which is different from what we use in GNU manuals.
837
838    Please include an email address in the manual for where to report
839 bugs _in the manual_.
840
841    Please do not use the term "pathname" that is used in Unix
842 documentation; use "file name" (two words) instead.  We use the term
843 "path" only for search paths, which are lists of directory names.
844
845    Please do not use the term "illegal" to refer to erroneous input to a
846 computer program.  Please use "invalid" for this, and reserve the term
847 "illegal" for activities punishable by law.
848
849 \1f
850 File: standards.info,  Node: Doc Strings and Manuals,  Next: Manual Structure Details,  Prev: GNU Manuals,  Up: Documentation
851
852 Doc Strings and Manuals
853 =======================
854
855    Some programming systems, such as Emacs, provide a documentation
856 string for each function, command or variable.  You may be tempted to
857 write a reference manual by compiling the documentation strings and
858 writing a little additional text to go around them--but you must not do
859 it.  That approach is a fundamental mistake.  The text of well-written
860 documentation strings will be entirely wrong for a manual.
861
862    A documentation string needs to stand alone--when it appears on the
863 screen, there will be no other text to introduce or explain it.
864 Meanwhile, it can be rather informal in style.
865
866    The text describing a function or variable in a manual must not stand
867 alone; it appears in the context of a section or subsection.  Other text
868 at the beginning of the section should explain some of the concepts, and
869 should often make some general points that apply to several functions or
870 variables.  The previous descriptions of functions and variables in the
871 section will also have given information about the topic.  A description
872 written to stand alone would repeat some of that information; this
873 redundance looks bad.  Meanwhile, the informality that is acceptable in
874 a documentation string is totally unacceptable in a manual.
875
876    The only good way to use documentation strings in writing a good
877 manual is to use them as a source of information for writing good text.
878
879 \1f
880 File: standards.info,  Node: Manual Structure Details,  Next: License for Manuals,  Prev: Doc Strings and Manuals,  Up: Documentation
881
882 Manual Structure Details
883 ========================
884
885    The title page of the manual should state the version of the
886 programs or packages documented in the manual.  The Top node of the
887 manual should also contain this information.  If the manual is changing
888 more frequently than or independent of the program, also state a version
889 number for the manual in both of these places.
890
891    Each program documented in the manual should have a node named
892 `PROGRAM Invocation' or `Invoking PROGRAM'.  This node (together with
893 its subnodes, if any) should describe the program's command line
894 arguments and how to run it (the sort of information people would look
895 in a man page for).  Start with an `@example' containing a template for
896 all the options and arguments that the program uses.
897
898    Alternatively, put a menu item in some menu whose item name fits one
899 of the above patterns.  This identifies the node which that item points
900 to as the node for this purpose, regardless of the node's actual name.
901
902    The `--usage' feature of the Info reader looks for such a node or
903 menu item in order to find the relevant text, so it is essential for
904 every Texinfo file to have one.
905
906    If one manual describes several programs, it should have such a node
907 for each program described in the manual.
908
909 \1f
910 File: standards.info,  Node: License for Manuals,  Next: Manual Credits,  Prev: Manual Structure Details,  Up: Documentation
911
912 License for Manuals
913 ===================
914
915    Please use the GNU Free Documentation License for all GNU manuals
916 that are more than a few pages long.  Likewise for a collection of short
917 documents--you only need one copy of the GNU FDL for the whole
918 collection.  For a single short document, you can use a very permissive
919 non-copyleft license, to avoid taking up space with a long license.
920
921    See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
922 of how to employ the GFDL.
923
924    Note that it is not obligatory to include a copy of the GNU GPL or
925 GNU LGPL in a manual whose license is neither the GPL nor the LGPL.  It
926 can be a good idea to include the program's license in a large manual;
927 in a short manual, whose size would be increased considerably by
928 including the program's license, it is probably better not to include
929 it.
930
931 \1f
932 File: standards.info,  Node: Manual Credits,  Next: Printed Manuals,  Prev: License for Manuals,  Up: Documentation
933
934 Manual Credits
935 ==============
936
937    Please credit the principal human writers of the manual as the
938 authors, on the title page of the manual.  If a company sponsored the
939 work, thank the company in a suitable place in the manual, but do not
940 cite the company as an author.
941
942 \1f
943 File: standards.info,  Node: Printed Manuals,  Next: NEWS File,  Prev: Manual Credits,  Up: Documentation
944
945 Printed Manuals
946 ===============
947
948    The FSF publishes some GNU manuals in printed form.  To encourage
949 sales of these manuals, the on-line versions of the manual should
950 mention at the very start that the printed manual is available and
951 should point at information for getting it--for instance, with a link
952 to the page <http://www.gnu.org/order/order.html>.  This should not be
953 included in the printed manual, though, because there it is redundant.
954
955    It is also useful to explain in the on-line forms of the manual how
956 the user can print out the manual from the sources.
957
958 \1f
959 File: standards.info,  Node: NEWS File,  Next: Change Logs,  Prev: Printed Manuals,  Up: Documentation
960
961 The NEWS File
962 =============
963
964    In addition to its manual, the package should have a file named
965 `NEWS' which contains a list of user-visible changes worth mentioning.
966 In each new release, add items to the front of the file and identify
967 the version they pertain to.  Don't discard old items; leave them in
968 the file after the newer items.  This way, a user upgrading from any
969 previous version can see what is new.
970
971    If the `NEWS' file gets very long, move some of the older items into
972 a file named `ONEWS' and put a note at the end referring the user to
973 that file.
974
975 \1f
976 File: standards.info,  Node: Change Logs,  Next: Man Pages,  Prev: NEWS File,  Up: Documentation
977
978 Change Logs
979 ===========
980
981    Keep a change log to describe all the changes made to program source
982 files.  The purpose of this is so that people investigating bugs in the
983 future will know about the changes that might have introduced the bug.
984 Often a new bug can be found by looking at what was recently changed.
985 More importantly, change logs can help you eliminate conceptual
986 inconsistencies between different parts of a program, by giving you a
987 history of how the conflicting concepts arose and who they came from.
988
989 * Menu:
990
991 * Change Log Concepts::
992 * Style of Change Logs::
993 * Simple Changes::
994 * Conditional Changes::
995 * Indicating the Part Changed::
996
997 \1f
998 File: standards.info,  Node: Change Log Concepts,  Next: Style of Change Logs,  Up: Change Logs
999
1000 Change Log Concepts
1001 -------------------
1002
1003    You can think of the change log as a conceptual "undo list" which
1004 explains how earlier versions were different from the current version.
1005 People can see the current version; they don't need the change log to
1006 tell them what is in it.  What they want from a change log is a clear
1007 explanation of how the earlier version differed.
1008
1009    The change log file is normally called `ChangeLog' and covers an
1010 entire directory.  Each directory can have its own change log, or a
1011 directory can use the change log of its parent directory-it's up to you.
1012
1013    Another alternative is to record change log information with a
1014 version control system such as RCS or CVS.  This can be converted
1015 automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
1016 command `C-x v a' (`vc-update-change-log') does the job.
1017
1018    There's no need to describe the full purpose of the changes or how
1019 they work together.  If you think that a change calls for explanation,
1020 you're probably right.  Please do explain it--but please put the
1021 explanation in comments in the code, where people will see it whenever
1022 they see the code.  For example, "New function" is enough for the
1023 change log when you add a function, because there should be a comment
1024 before the function definition to explain what it does.
1025
1026    However, sometimes it is useful to write one line to describe the
1027 overall purpose of a batch of changes.
1028
1029    The easiest way to add an entry to `ChangeLog' is with the Emacs
1030 command `M-x add-change-log-entry'.  An entry should have an asterisk,
1031 the name of the changed file, and then in parentheses the name of the
1032 changed functions, variables or whatever, followed by a colon.  Then
1033 describe the changes you made to that function or variable.
1034
1035 \1f
1036 File: standards.info,  Node: Style of Change Logs,  Next: Simple Changes,  Prev: Change Log Concepts,  Up: Change Logs
1037
1038 Style of Change Logs
1039 --------------------
1040
1041    Here are some simple examples of change log entries, starting with
1042 the header line that says who made the change and when, followed by
1043 descriptions of specific changes.  (These examples are drawn from Emacs
1044 and GCC.)
1045
1046      1998-08-17  Richard Stallman  <rms@gnu.org>
1047      
1048      * register.el (insert-register): Return nil.
1049      (jump-to-register): Likewise.
1050      
1051      * sort.el (sort-subr): Return nil.
1052      
1053      * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
1054      Restart the tex shell if process is gone or stopped.
1055      (tex-shell-running): New function.
1056      
1057      * expr.c (store_one_arg): Round size up for move_block_to_reg.
1058      (expand_call): Round up when emitting USE insns.
1059      * stmt.c (assign_parms): Round size up for move_block_from_reg.
1060
1061    It's important to name the changed function or variable in full.
1062 Don't abbreviate function or variable names, and don't combine them.
1063 Subsequent maintainers will often search for a function name to find all
1064 the change log entries that pertain to it; if you abbreviate the name,
1065 they won't find it when they search.
1066
1067    For example, some people are tempted to abbreviate groups of function
1068 names by writing `* register.el ({insert,jump-to}-register)'; this is
1069 not a good idea, since searching for `jump-to-register' or
1070 `insert-register' would not find that entry.
1071
1072    Separate unrelated change log entries with blank lines.  When two
1073 entries represent parts of the same change, so that they work together,
1074 then don't put blank lines between them.  Then you can omit the file
1075 name and the asterisk when successive entries are in the same file.
1076
1077    Break long lists of function names by closing continued lines with
1078 `)', rather than `,', and opening the continuation with `(' as in this
1079 example:
1080
1081      * keyboard.c (menu_bar_items, tool_bar_items)
1082      (Fexecute_extended_command): Deal with `keymap' property.
1083
1084 \1f
1085 File: standards.info,  Node: Simple Changes,  Next: Conditional Changes,  Prev: Style of Change Logs,  Up: Change Logs
1086
1087 Simple Changes
1088 --------------
1089
1090    Certain simple kinds of changes don't need much detail in the change
1091 log.
1092
1093    When you change the calling sequence of a function in a simple
1094 fashion, and you change all the callers of the function to use the new
1095 calling sequence, there is no need to make individual entries for all
1096 the callers that you changed.  Just write in the entry for the function
1097 being called, "All callers changed"--like this:
1098
1099      * keyboard.c (Fcommand_execute): New arg SPECIAL.
1100      All callers changed.
1101
1102    When you change just comments or doc strings, it is enough to write
1103 an entry for the file, without mentioning the functions.  Just "Doc
1104 fixes" is enough for the change log.
1105
1106    There's no need to make change log entries for documentation files.
1107 This is because documentation is not susceptible to bugs that are hard
1108 to fix.  Documentation does not consist of parts that must interact in a
1109 precisely engineered fashion.  To correct an error, you need not know
1110 the history of the erroneous passage; it is enough to compare what the
1111 documentation says with the way the program actually works.
1112
1113 \1f
1114 File: standards.info,  Node: Conditional Changes,  Next: Indicating the Part Changed,  Prev: Simple Changes,  Up: Change Logs
1115
1116 Conditional Changes
1117 -------------------
1118
1119    C programs often contain compile-time `#if' conditionals.  Many
1120 changes are conditional; sometimes you add a new definition which is
1121 entirely contained in a conditional.  It is very useful to indicate in
1122 the change log the conditions for which the change applies.
1123
1124    Our convention for indicating conditional changes is to use square
1125 brackets around the name of the condition.
1126
1127    Here is a simple example, describing a change which is conditional
1128 but does not have a function or entity name associated with it:
1129
1130      * xterm.c [SOLARIS2]: Include string.h.
1131
1132    Here is an entry describing a new definition which is entirely
1133 conditional.  This new definition for the macro `FRAME_WINDOW_P' is
1134 used only when `HAVE_X_WINDOWS' is defined:
1135
1136      * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
1137
1138    Here is an entry for a change within the function `init_display',
1139 whose definition as a whole is unconditional, but the changes themselves
1140 are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
1141
1142      * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
1143
1144    Here is an entry for a change that takes affect only when a certain
1145 macro is _not_ defined:
1146
1147      (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
1148
1149 \1f
1150 File: standards.info,  Node: Indicating the Part Changed,  Prev: Conditional Changes,  Up: Change Logs
1151
1152 Indicating the Part Changed
1153 ---------------------------
1154
1155    Indicate the part of a function which changed by using angle brackets
1156 enclosing an indication of what the changed part does.  Here is an entry
1157 for a change in the part of the function `sh-while-getopts' that deals
1158 with `sh' commands:
1159
1160      * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
1161      user-specified option string is empty.
1162
1163 \1f
1164 File: standards.info,  Node: Man Pages,  Next: Reading other Manuals,  Prev: Change Logs,  Up: Documentation
1165
1166 Man Pages
1167 =========
1168
1169    In the GNU project, man pages are secondary.  It is not necessary or
1170 expected for every GNU program to have a man page, but some of them do.
1171 It's your choice whether to include a man page in your program.
1172
1173    When you make this decision, consider that supporting a man page
1174 requires continual effort each time the program is changed.  The time
1175 you spend on the man page is time taken away from more useful work.
1176
1177    For a simple program which changes little, updating the man page may
1178 be a small job.  Then there is little reason not to include a man page,
1179 if you have one.
1180
1181    For a large program that changes a great deal, updating a man page
1182 may be a substantial burden.  If a user offers to donate a man page,
1183 you may find this gift costly to accept.  It may be better to refuse
1184 the man page unless the same person agrees to take full responsibility
1185 for maintaining it--so that you can wash your hands of it entirely.  If
1186 this volunteer later ceases to do the job, then don't feel obliged to
1187 pick it up yourself; it may be better to withdraw the man page from the
1188 distribution until someone else agrees to update it.
1189
1190    When a program changes only a little, you may feel that the
1191 discrepancies are small enough that the man page remains useful without
1192 updating.  If so, put a prominent note near the beginning of the man
1193 page explaining that you don't maintain it and that the Texinfo manual
1194 is more authoritative.  The note should say how to access the Texinfo
1195 documentation.
1196
1197 \1f
1198 File: standards.info,  Node: Reading other Manuals,  Prev: Man Pages,  Up: Documentation
1199
1200 Reading other Manuals
1201 =====================
1202
1203    There may be non-free books or documentation files that describe the
1204 program you are documenting.
1205
1206    It is ok to use these documents for reference, just as the author of
1207 a new algebra textbook can read other books on algebra.  A large portion
1208 of any non-fiction book consists of facts, in this case facts about how
1209 a certain program works, and these facts are necessarily the same for
1210 everyone who writes about the subject.  But be careful not to copy your
1211 outline structure, wording, tables or examples from preexisting non-free
1212 documentation.  Copying from free documentation may be ok; please check
1213 with the FSF about the individual case.
1214