1 This is ../info/standards.info, produced by makeinfo version 4.0 from
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
9 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
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.
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.
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.
26 File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
28 Formatting Your Source Code
29 ===========================
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.
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:
43 concat (s1, s2) /* Name starts in column zero here */
45 { /* Open brace in column zero here */
49 or, if you want to use Standard C syntax, format the definition like
53 concat (char *s1, char *s2)
58 In Standard C, if the arguments don't fit nicely on one line, split
62 lots_of_args (int an_integer, long a_long, short a_short,
63 double a_double, float a_float)
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
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
73 We don't think of these recommendations as requirements, because it
74 causes no problems for users if two different programs have different
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
82 For the body of the function, our recommended style looks like this:
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.
99 When you split an expression into multiple lines, split it before an
100 operator, not after one. Here is the right way:
102 if (foo_this_is_long && bar > win (x, y, z)
103 && remaining_condition)
105 Try to avoid having two operators of different precedence at the same
106 level of indentation. For example, don't write this:
108 mode = (inmode[j] == VOIDmode
109 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
110 ? outmode[j] : inmode[j]);
112 Instead, use extra parentheses so that the indentation shows the
115 mode = ((inmode[j] == VOIDmode
116 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
117 ? outmode[j] : inmode[j]);
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,
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;
125 but Emacs would alter it. Adding a set of parentheses produces
126 something that looks equally nice, and which Emacs will preserve:
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);
131 Format do-while statements like this:
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.
145 File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
150 Every program should start with a comment saying briefly what it is
151 for. Example: `fmt - filter for simple filling of text'.
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.
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
171 Also explain the significance of the return value, if there is one.
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 ...").
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".
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.
192 There should be a comment on each static variable as well, like this:
194 /* Nonzero means truncate lines in the display;
195 zero means continue them. */
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:
213 but, by contrast, write the comments this way for a `#ifndef':
225 File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
227 Clean Use of C Constructs
228 =========================
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'.
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
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
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.
256 Don't use local variables or parameters that shadow global
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
275 (If they are global variables, each should have a comment preceding it
278 When you have an `if'-`else' statement nested in another `if'
279 statement, always put braces around the `if'-`else'. Thus, never write
298 If you have an `if' statement nested inside of an `else' statement,
299 either write `else if' on one line, like this,
306 with its `then'-part indented like the preceding `then'-part, or write
307 the nested `if' within braces like this:
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.
321 Try to avoid assignments inside `if'-conditions. For example, don't
324 if ((foo = (char *) malloc (sizeof *foo)) == 0)
325 fatal ("virtual memory exhausted");
329 foo = (char *) malloc (sizeof *foo);
331 fatal ("virtual memory exhausted");
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.
338 File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
340 Naming Variables and Functions
341 ==============================
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
349 Local variable names can be shorter, because they are used only
350 within one context, where (presumably) comments explain their purpose.
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.
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.
361 For example, you should use names like `ignore_space_change_flag';
362 don't use names like `iCantReadThis'.
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,
369 /* Ignore changes in horizontal whitespace (-b). */
370 int ignore_space_change_flag;
372 When you want to define names with constant integer values, use
373 `enum' rather than `#define'. GDB knows about enumeration constants.
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.
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
387 File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
389 Portability between System Types
390 ================================
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
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.
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
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
415 Avoid using the format of semi-internal data bases (e.g.,
416 directories) when there is a higher-level alternative (`readdir').
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.
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.)
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.
437 File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
439 Portability between CPUs
440 ========================
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
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:
453 printf ("size = %lu\n", (unsigned long) sizeof array);
454 printf ("diff = %ld\n", (long) (pointer2 - pointer1));
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.
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.
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:
472 while ((c = getchar()) != EOF)
473 write(file_descriptor, &c, 1);
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.
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:
487 error (s, a1, a2, a3)
491 fprintf (stderr, "error: ");
492 fprintf (stderr, s, a1, a2, a3);
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
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'.
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
513 File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
515 Calling System Functions
516 ========================
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.
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.
527 * Be aware that `vfprintf' is not always available.
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.
533 * Don't declare system functions explicitly.
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.
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.
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
551 * In particular, don't unconditionally declare `malloc' or `realloc'.
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.
557 Because `xmalloc' and `xrealloc' are defined in your program, you
558 can declare them in other files without any risk of type conflict.
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
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
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
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
582 strcpy strncpy strcat strncat
583 strlen strcmp strncmp
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.
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
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.
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:
617 #define strrchr rindex
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.
628 File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C
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
639 Using GNU gettext involves putting a call to the `gettext' macro
640 around each string that might need translation--like this:
642 printf (gettext ("Processing file `%s'..."));
644 This permits GNU gettext to replace the string `"Processing file
645 `%s'..."' with a translated version.
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.
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.
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
663 Here is an example of what not to do:
665 printf ("%d file%s processed", nfiles,
666 nfiles != 1 ? "s" : "");
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,
671 printf (gettext ("%d file%s processed"), nfiles,
672 nfiles != 1 ? "s" : "");
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:
677 printf ((nfiles != 1 ? "%d files processed"
678 : "%d file processed"),
681 This way, you can apply gettext to each of the two strings
684 printf ((nfiles != 1 ? gettext ("%d files processed")
685 : gettext ("%d file processed")),
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
692 A similar problem appears at the level of sentence structure with
695 printf ("# Implicit rule search has%s been done.\n",
696 f->tried_implicit ? "" : " not");
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:
703 printf (f->tried_implicit
704 ? "# Implicit rule search has been done.\n",
705 : "# Implicit rule search has not been done.\n");
708 File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C
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.
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'.
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
727 File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
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.
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
752 File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
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').
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.
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.
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
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
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.
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
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
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._
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.
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.
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.
838 Please include an email address in the manual for where to report
839 bugs _in the manual_.
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.
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.
850 File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
852 Doc Strings and Manuals
853 =======================
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.
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.
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.
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.
880 File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
882 Manual Structure Details
883 ========================
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.
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.
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.
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.
906 If one manual describes several programs, it should have such a node
907 for each program described in the manual.
910 File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
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.
921 See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
922 of how to employ the GFDL.
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
932 File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
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.
943 File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
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.
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.
959 File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
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.
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
976 File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
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.
991 * Change Log Concepts::
992 * Style of Change Logs::
994 * Conditional Changes::
995 * Indicating the Part Changed::
998 File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
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.
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.
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.
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.
1026 However, sometimes it is useful to write one line to describe the
1027 overall purpose of a batch of changes.
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.
1036 File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
1038 Style of Change Logs
1039 --------------------
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
1046 1998-08-17 Richard Stallman <rms@gnu.org>
1048 * register.el (insert-register): Return nil.
1049 (jump-to-register): Likewise.
1051 * sort.el (sort-subr): Return nil.
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.
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.
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.
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.
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.
1077 Break long lists of function names by closing continued lines with
1078 `)', rather than `,', and opening the continuation with `(' as in this
1081 * keyboard.c (menu_bar_items, tool_bar_items)
1082 (Fexecute_extended_command): Deal with `keymap' property.
1085 File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
1090 Certain simple kinds of changes don't need much detail in the change
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:
1099 * keyboard.c (Fcommand_execute): New arg SPECIAL.
1100 All callers changed.
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.
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.
1114 File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
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.
1124 Our convention for indicating conditional changes is to use square
1125 brackets around the name of the condition.
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:
1130 * xterm.c [SOLARIS2]: Include string.h.
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:
1136 * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
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:
1142 * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
1144 Here is an entry for a change that takes affect only when a certain
1145 macro is _not_ defined:
1147 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
1150 File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
1152 Indicating the Part Changed
1153 ---------------------------
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
1160 * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
1161 user-specified option string is empty.
1164 File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
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.
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.
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,
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.
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
1198 File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
1200 Reading other Manuals
1201 =====================
1203 There may be non-free books or documentation files that describe the
1204 program you are documenting.
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.