Lines Matching +full:readme +full:. +full:installer
1 This is standards.info, produced by makeinfo version 4.13 from
2 standards.texi.
6 * Standards: (standards). GNU coding standards.
9 The GNU coding standards, last updated April 7, 2012.
13 Free Software Foundation, Inc.
19 Texts. A copy of the license is included in the section entitled "GNU
20 Free Documentation License".
23 File: standards.info, Node: Top, Next: Preface, Up: (dir)
28 The GNU coding standards, last updated April 7, 2012.
32 Free Software Foundation, Inc.
38 Texts. A copy of the license is included in the section entitled "GNU
39 Free Documentation License".
43 * Preface:: About the GNU Coding Standards.
44 * Legal Issues:: Keeping free software free.
45 * Design Advice:: General program design.
47 * Writing C:: Making the best use of C.
48 * Documentation:: Documenting programs.
49 * Managing Releases:: The release process.
50 * References:: Mentioning non-free software or documentation.
51 * GNU Free Documentation License:: Copying and sharing this manual.
55 File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
61 Project volunteers. Their purpose is to make the GNU system clean,
62 consistent, and easy to install. This document can also be read as a
63 guide to writing portable, robust and reliable programs. It focuses on
65 even if you write in another programming language. The rules often
66 state reasons for writing in a certain way.
69 recently, please check for a newer version. You can get the GNU Coding
72 `http://www.gnu.org/prep/standards/'.
76 Contents: (maintain)Top.).
79 join the mailing list `gnustandards-commit@gnu.org', via the web
81 `http://lists.gnu.org/mailman/listinfo/gnustandards-commit'. Archives
82 are also available there.
85 <bug-standards@gnu.org>. If you make a suggestion, please include a
87 efficiently. We prefer a context diff to the Texinfo source, but if
89 version of this document, or propose it in any way that makes it clear.
91 `http://savannah.gnu.org/projects/gnustandards'.
94 GNU package. Likely, the need for additional standards will come up.
96 document. If you think your standards would be generally useful, please
97 do suggest them.
100 addressed or not firmly specified here. The most important point is to
102 to document them as much as possible. That way, your program will be
103 more maintainable by others.
106 coding standards for a trivial program.
107 `http://www.gnu.org/software/hello/hello.html'.
110 2012.
113 File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
119 legal difficulties, and other related issues.
123 * Reading Non-Free Code:: Referring to proprietary programs.
124 * Contributions:: Accepting contributions.
125 * Trademarks:: How we deal with trademark issues.
128 File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
134 work on GNU! (Or to any other proprietary programs.)
140 irrelevant and dissimilar to your results.
144 different. You could keep the entire input file in memory and scan it
145 there instead of using stdio. Use a smarter algorithm discovered more
146 recently than the Unix program. Eliminate use of temporary files. Do
147 it in one pass instead of two (we did this in the assembler).
149 Or, on the contrary, emphasize simplicity instead of speed. For some
151 adequate.
153 Or go for generality. For example, Unix programs often have static
155 dynamic allocation instead. Make sure your program handles NULs and
156 other funny characters in the input files. Add a programming language
157 for extensibility and write part of the program in that language.
160 libraries. Or use a simple garbage collector instead of tracking
162 obstacks.
165 File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: L…
173 sign papers initially. _Each_ person who makes a nontrivial
176 enough.
179 us, so we can arrange to get the papers. Then wait until we tell you
181 contribution.
183 This applies both before you release the program and afterward. If
185 need legal papers for that change.
187 This also applies to comments and documentation files. For copyright
188 law, comments and code are just text. Copyright applies to all kinds of
189 text, so we need legal papers for all kinds.
192 for us as well. But if you don't wait, you are going out on a limb--for
197 they are not significant for copyright purposes. Also, you don't need
199 which you use. For example, if someone sent you one implementation, but
201 get papers.
204 contributor. We could be very embarrassed in court some day as a
205 result.
207 We have more detailed advice for maintainers of GNU packages. If you
210 Matters.
213 File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
219 packages or documentation.
222 trademark of so-and-so. The GNU Project has no objection to the basic
224 there is no legal requirement for them, so we don't use them.
228 naming or labeling our own programs or activities. For example, since
231 an "Objective C compiler". The latter would have been meant as a
234 label for the compiler rather than for the language.
237 GNU software or documentation. In hacker terminology, calling
238 something a "win" is a form of praise. If you wish to praise Microsoft
240 software. Usually we write the name "Windows" in full, but when
242 names), we abbreviate it to "w". For instance, the files and functions
243 in Emacs that deal with Windows start with `w32'.
246 File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
252 when designing your program.
256 * Source Language:: Which languages to use.
257 * Compatibility:: Compatibility with other implementations.
258 * Using Extensions:: Using non-standard features.
259 * Standard C:: Using standard C features.
260 * Conditional Compilation:: Compiling code only if a conditional is true.
263 File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
269 speed, the best language to use is C. Using another language is like
270 using a non-standard feature: it will cause trouble for users. Even if
273 program. For example, if you write your program in C++, people will
274 have to install the GNU C++ compiler in order to compile your program.
278 program if it is written in C.
281 alternatives.
286 specifically intended for use with that language. That is because
288 installed the other language anyway.
293 yourself.
296 interpreter for a language that is higher level than C. Often much of
297 the program is written in that language, too. The Emacs editor
298 pioneered this technique.
301 (`http://www.gnu.org/software/guile/'), which implements the language
302 Scheme (an especially clean and simple dialect of Lisp). Guile also
304 GUI functionality within Guile. We don't reject programs written in
306 very important for the overall consistency of the GNU system.
309 File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: D…
317 upward compatible with POSIX if POSIX specifies their behavior.
320 modes for each of them.
322 Standard C and POSIX prohibit many kinds of extensions. Feel free
324 `--compatible' option to turn them off. However, if the extension has
326 is not really upward compatible. So you should try to redesign its
327 interface to make it upward compatible.
331 defined with a null value). Please make your program recognize this
332 variable if appropriate.
336 completely with something totally different and better. (For example,
337 `vi' is replaced with Emacs.) But it is nice to offer a compatible
338 feature as well. (There is a free `vi' clone, so we offer it.)
341 is any precedent for them.
344 File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design…
350 extensions over the comparable Unix facilities. Whether to use these
351 extensions in implementing your program is a difficult question.
353 On the one hand, using the extensions can make a cleaner program.
355 the other GNU tools are available. This might cause the program to
356 work on fewer kinds of machines.
358 With some extensions, it might be easy to provide both alternatives.
361 depending on the compiler.
365 are a big improvement.
368 as Emacs) which run on a great variety of systems. Using GNU
370 do that.
374 order to bootstrap the GNU compilation facilities. If these require
376 installed already. That would be extremely troublesome in certain
377 cases.
380 File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, …
386 features in new programs. There is one exception: do not ever use the
387 "trigraph" feature of Standard C.
390 features in programs. It is ok to use its features if they are present.
393 programs, so if you know how to do that, feel free. If a program you
394 are maintaining has such support, you should try to keep it working.
401 ...
408 ...
415 benefit of prototypes in all the files where the function is called.
417 the function definition in the pre-standard style.
419 This technique does not work for integer types narrower than `int'.
421 declare it as `int' instead.
423 There are a few special cases where this technique is hard to use.
427 wider than `int' on some machines. There is no type you can safely use
428 on all machines in a non-standard definition. The only way to support
430 `dev_t' using Autoconf and choose the argument type accordingly. This
431 may not be worth the trouble.
436 /* Declare the prototype for a general external function. */
444 File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
450 program we prefer using `if (... )' over conditional compilation, as in
452 of all possible code paths.
457 ...
459 ...
464 ...
466 ...
471 in several projects. Of course, the former method assumes that
472 `HAS_FOO' is defined as either 0 or 1.
476 GCC developers many hours, or even days, per year.
479 which cannot be simply used in `if (...)' statements, there is an easy
480 workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
490 File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
495 This chapter describes conventions for writing robust software. It
497 interface, and how libraries should behave.
502 we don't "obey" them.
503 * Semantics:: Writing robust programs.
504 * Libraries:: Library behavior.
505 * Errors:: Formatting error messages.
506 * User Interfaces:: Standards about interfaces generally.
507 * Graphical Interfaces:: Standards for graphical interfaces.
508 * Command-Line Interfaces:: Standards for command line interfaces.
509 * Dynamic Plug-In Interfaces:: Standards for dynamic plug-in interfaces.
510 * Option Table:: Table of long options.
511 * OID Allocations:: Table of OID slots for GNU.
512 * Memory Usage:: When and how to care about memory needs.
513 * File Usage:: Which files to use, and where.
516 File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior
522 suggestions, not orders. We consider those standards, but we do not
523 "obey" them. In developing a GNU program, you should implement an
525 overall in an objective sense. When it doesn't, you shouldn't.
528 users--it means that their programs or scripts will work more portably.
530 specified by that standard. C program developers would be unhappy if
531 it did not. And GNU utilities mostly follow specifications of POSIX.2;
533 incompatible.
537 to make the GNU system better for users.
540 prohibited. How silly! GCC implements many extensions, some of which
541 were later adopted as part of the standard. If you want these
545 is any reason to actually use it.
547 POSIX.2 specifies that `df' and `du' must output sizes by default in
548 units of 512 bytes. What users want is units of 1k, so that is what we
549 do by default. If you want the ridiculous behavior "required" by
551 was originally going to be named `POSIX_ME_HARDER').
553 GNU utilities also depart from the letter of the POSIX.2
555 intermixing options with ordinary arguments. This minor
557 very useful.
560 merely because a standard says it is "forbidden" or "deprecated".
563 File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Be…
570 structures dynamically. In most Unix utilities, "long lines are
571 silently truncated". This is not acceptable in a GNU utility.
574 nonprinting characters _including those with codes above 0177_. The
577 those characters. Whenever possible, try to make programs work
579 UTF-8 is the most important.
582 to ignore errors. Include the system error text (from `perror',
585 name of the utility. Just "cannot open foo.c" or "stat failed" is not
586 sufficient.
589 zero. Check `realloc' even if you are making the block smaller; in a
591 different block if you ask for less space.
593 In Unix, `realloc' can destroy the storage block if it returns zero.
595 is unchanged. Feel free to assume the bug is fixed. If you wish to
597 can use the GNU `malloc'.
600 freed. Anything you want to fetch from the block, you must fetch before
601 calling `free'.
604 error. In an interactive program (one that reads commands from the
606 reader loop. This allows the user to kill other processes to free up
607 virtual memory, and then try the command again.
610 makes this unreasonable.
613 explicit C code to initialize it. Reserve C initialized declarations
614 for data that will not be changed.
618 these are less likely to work compatibly. If you need to find all the
619 files in a directory, use `readdir' or some other high-level interface.
620 These are supported compatibly by GNU.
624 `signal' interface is an inferior design.
627 make a program portable. If you use `signal', then on GNU/Linux
628 systems running GNU libc version 1, you should include `bsd/signal.h'
629 instead of `signal.h', so as to get BSD behavior. It is up to you
631 give up on them.
633 In error checks that detect "impossible" conditions, just abort.
634 There is usually no point in printing any message. These checks
635 indicate the existence of bugs. Whoever wants to fix the bugs will have
636 to read the source code and run a debugger. So explain the problem with
637 comments in the source. The relevant data will be in variables, which
639 elsewhere.
641 Do not use a count of errors as the exit status for a program.
643 (0 through 255). A single run of the program might have 256 errors; if
645 as the status, and it will appear that the program succeeded.
649 instead of `/tmp'.
652 creating temporary files in world-writable directories. In C, you can
658 (gnulib)mkstemps.).
660 In bash, use `set -C' (long name `noclobber') to avoid this problem.
663 (coreutils)mktemp invocation.).
666 File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
671 Try to make library functions reentrant. If they need to do dynamic
673 that of `malloc' itself.
676 conflicts.
678 Choose a name prefix for the library, more than two characters long.
679 All external function and variable names should start with this prefix.
681 member. This usually means putting each one in a separate source file.
685 other; then they can both go in the same file.
688 should have names beginning with `_'. The `_' should be followed by
690 other libraries. These can go in the same files with user entry points
691 if you like.
694 fit any naming convention.
697 File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
709 SOURCEFILE:LINENO.COLUMN: MESSAGE
712 column numbers should start from 1 at the beginning of the line. (Both
713 of these conventions are chosen for compatibility.) Calculate column
715 equal width, and assuming tab stops every 8 columns. For non-ASCII
717 locale; GNU libc and GNU gnulib provide suitable `wcwidth' functions.
720 positions of the erroneous text. There are several formats so that you
721 can avoid redundant information such as a duplicate line number. Here
724 SOURCEFILE:LINE1.COLUMN1-LINE2.COLUMN2: MESSAGE
725 SOURCEFILE:LINE1.COLUMN1-COLUMN2: MESSAGE
730 FILE1:LINE1.COLUMN1-FILE2:LINE2.COLUMN2: MESSAGE
741 when there is no relevant source file.
749 message. The place to indicate which program is running is in the
750 prompt or with the screen layout. (When the same program runs with
752 would do best to print error messages using the noninteractive style.)
756 beginning of a sentence. (The sentence conceptually starts at the
757 beginning of the line.) Also, it should not end with a period.
760 usage messages, should start with a capital letter. But they should not
761 end with a period.
764 File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Prog…
770 invoke it. It is useful sometimes to make a link to a utility with a
771 different name, and that should not change what it does.
774 select among the alternate behaviors.
777 type of output device it is used with. Device independence is an
779 to save someone from typing an option now and then. (Variation in error
781 that people do not depend on.)
787 behavior.
790 output device. It would be disastrous if `ls' or `sh' did not do so in
791 the way all users expect. In some of these cases, we supplement the
793 output device type. For example, we provide a `dir' program much like
795 format.
798 File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Inte…
806 example, "displaying jpeg images while in console mode").
809 functionality. (In many cases, the graphical user interface can be a
810 separate program which invokes the command-line program.) This is so
811 that the same jobs can be done from scripts.
814 running programs, such as within GNOME. (GNOME used to use CORBA for
815 this, but that is being phased out.) In addition, consider providing a
817 console interface (for use by users from console mode). Once you are
819 interface, these won't be much extra work.
822 File: standards.info, Node: Command-Line Interfaces, Next: Dynamic Plug-In Interfaces, Prev: Gra…
828 options of a program. The easiest way to do this is to use `getopt' to
829 parse them. Note that the GNU version of `getopt' will normally permit
831 is used. This is not what POSIX specifies; it is a GNU extension.
834 single-letter Unix-style options. We hope to make GNU more user
835 friendly this way. This is easy to do with the GNU function
836 `getopt_long'.
839 consistent from program to program. For example, users should be able
841 spelled precisely `--verbose'. To achieve this uniformity, look at the
843 your program (*note Option Table::).
847 options (preferably `-o' or `--output'). Even if you allow an output
849 option as another way to specify it. This will lead to more consistency
850 among GNU utilities, and fewer idiosyncrasies for users to remember.
853 `--help'. CGI programs should accept these as command-line options,
855 `http://example.org/p.cgi/--help' in a browser should output the same
856 information as invoking `p.cgi --help' from the command line.
860 * --version:: The standard output for --version.
861 * --help:: The standard output for --help.
864 File: standards.info, Node: --version, Next: --help, Up: Command-Line Interfaces
866 4.7.1 `--version'
871 standard output, and then exit successfully. Other options and
873 not perform its normal function.
876 version number proper starts after the last space. In addition, it
882 `argv[0]'. The idea is to state the standard or canonical name for the
883 program, not its file name. There are other ways to find out the
884 precise file name where a command is found in `PATH'.
893 just before the close-parenthesis.
898 library you want to mention. Use the same format for these lines as for
899 the first line.
902 "just for completeness"--that would produce a lot of unhelpful clutter.
904 they are very important to you in debugging.
907 be a copyright notice. If more than one copyright notice is called
908 for, put each on a separate line.
912 software, and that users are free to copy and change it. Also mention
913 that there is no warranty, to the extent permitted by law. See
914 recommended wording below.
917 program, as a way of giving credit.
922 Copyright (C) 2007 Free Software Foundation, Inc.
923 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
924 This is free software: you are free to change and redistribute it.
925 There is NO WARRANTY, to the extent permitted by law.
929 distribution terms, and changing the rest of the wording as necessary.
933 versions' changes. You don't have to mention the name of the program in
935 line. (The rules are different for copyright notices in source files;
936 *note Copyright Notices: (maintain)Copyright Notices.)
939 copyright notices (*note Internationalization::). If the translation's
945 Write the word "Copyright" exactly like that, in English. Do not
946 translate it into another language. International treaties recognize
948 have legal significance.
950 Finally, here is the table of our suggested license abbreviations.
952 particular version, or later versions with the `+', as shown above.
956 abbreviation as usual, as in the examples below.
959 GNU General Public License, `http://www.gnu.org/licenses/gpl.html'.
963 `http://www.gnu.org/licenses/lgpl.html'.
966 GNU GPL with the exception for Ada.
970 `http://www.apache.org/licenses'.
974 `http://www.perlfoundation.org/legal'.
977 The Expat license, `http://www.jclark.com/xml/copying.txt'.
980 The Mozilla Public License, `http://www.mozilla.org/MPL/'.
984 `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'.
987 The license used for PHP, `http://www.php.net/license/'.
991 `http://www.gnu.org/licenses/license-list.html#PublicDomain'.
994 The license for Python, `http://www.python.org/2.0.1/license.html'.
998 `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'.
1002 Window System, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'.
1005 The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'.
1009 licensing web pages, `http://www.gnu.org/licenses/license-list.html'.
1012 File: standards.info, Node: --help, Prev: --version, Up: Command-Line Interfaces
1014 4.7.2 `--help'
1018 to invoke the program, on standard output, then exit successfully.
1020 the program should not perform its normal function.
1024 (normally <http://www.gnu.org/software/PKG>, and the general page for
1025 help using GNU programs. The format should be like this:
1028 PKG home page: <http://www.gnu.org/software/PKG/>
1029 General help using GNU software: <http://www.gnu.org/gethelp/>
1031 It is ok to mention other appropriate mailing lists and web pages.
1034 File: standards.info, Node: Dynamic Plug-In Interfaces, Next: Option Table, Prev: Command-Line I…
1040 of free plug-ins, and discouraging development of proprietary plug-ins.
1042 those that do should follow these practices.
1046 program are parts of one extended program. For GCC, for example,
1048 clearly form an extended program with the base GCC.
1051 plug-ins are released under an appropriate license. This should be
1052 enforced with a simple programmatic check. For GCC, again for example,
1055 license (*note Plugins: (gccint)Plugins.).
1058 requirement. The GPL itself requires plug-ins to be free software,
1059 licensed compatibly. As long as you have followed the first rule above
1062 license. The symbol definition in the plug-in--or whatever equivalent
1064 distribute proprietary plug-ins to legally defend themselves. If a case
1066 the plug-in developer understood that the license had this requirement.
1069 File: standards.info, Node: Option Table, Next: OID Allocations, Prev: Dynamic Plug-In Interface…
1074 Here is a table of long options used by GNU programs. It is surely
1076 want to be compatible with. If you use names not already in the table,
1077 please send <bug-standards@gnu.org> a list of them, with their
1078 meanings, so we can update the table.
1081 `-N' in `tar'.
1084 `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
1087 `-a' in `diff'.
1090 `-A' in `ls'.
1093 `-a' in `etags', `tee', `time'; `-r' in `tar'.
1096 `-a' in `cp'.
1099 `-n' in `shar'.
1102 `-l' in `m4'.
1105 `-a' in `diff'.
1108 `-v' in `gawk'.
1111 `-W' in `make'.
1114 `-o' in `make'.
1117 `-a' in `recode'.
1120 `-a' in `wdiff'.
1123 `-A' in `ptx'.
1126 `-n' in `wdiff'.
1129 For server programs, run in the background.
1132 `-B' in `ctags'.
1135 `-f' in `shar'.
1138 Used in GDB.
1141 Used in GDB.
1144 `-b' in `tac'.
1147 `-b' in `cpio' and `diff'.
1150 `-b' in `shar'.
1153 Used in `cpio' and `tar'.
1156 `-b' in `head' and `tail'.
1159 `-b' in `ptx'.
1162 Used in various programs to make output shorter.
1165 `-c' in `head', `split', and `tail'.
1168 `-C' in `etags'.
1171 `-A' in `tar'.
1174 Used in various programs to specify the directory to use.
1177 `-c' in `chgrp' and `chown'.
1180 `-F' in `ls'.
1183 `-c' in `recode'.
1186 `-c' in `su'; `-x' in GDB.
1189 `-d' in `tar'.
1192 Used in `gawk'.
1195 `-Z' in `tar' and `shar'.
1198 `-A' in `tar'.
1201 `-w' in `tar'.
1204 Used in `diff'.
1207 `-W copyleft' in `gawk'.
1210 `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
1213 Used in GDB.
1216 `-q' in `who'.
1219 `-l' in `du'.
1222 Used in `tar' and `cpio'.
1225 `-c' in `shar'.
1228 `-x' in `ctags'.
1231 `-d' in `touch'.
1234 `-d' in `make' and `m4'; `-t' in Bison.
1237 `-D' in `m4'.
1240 `-d' in Bison and `ctags'.
1243 `-D' in `tar'.
1246 `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
1249 `-D' in `du'.
1252 Specify an I/O device (special file name).
1255 `-d' in `recode'.
1258 `-d' in `look'.
1261 `-d' in `tar'.
1264 `-n' in `csplit'.
1267 Specify the directory to use, in various programs. In `ls', it
1268 means to show directories themselves rather than their contents.
1270 specially.
1273 `-x' in `strip'.
1276 `-X' in `strip'.
1279 `-n' in `make'.
1282 `-e' in `diff'.
1285 `-z' in `csplit'.
1288 `-x' in `wdiff'.
1291 `-z' in `wdiff'.
1294 `-N' in `diff'.
1297 `-e' in `make'.
1300 `-e' in `xargs'.
1303 Used in GDB.
1306 Used in `makeinfo'.
1309 `-o' in `m4'.
1312 `-b' in `ls'.
1315 `-X' in `tar'.
1318 Used in GDB.
1321 `-x' in `xargs'.
1324 `-e' in `unshar'.
1327 `-t' in `diff'.
1330 `-e' in `sed'.
1333 `-g' in `nm'.
1336 `-i' in `cpio'; `-x' in `tar'.
1339 `-f' in `finger'.
1342 `-f' in `su'.
1345 `-E' in `m4'.
1348 `-f' in `gawk', `info', `make', `mt', `sed', and `tar'.
1351 `-F' in `gawk'.
1354 `-b' in Bison.
1357 `-F' in `ls'.
1360 `-T' in `tar'.
1363 Used in `makeinfo'.
1366 `-F' in `ptx'.
1369 `-y' in Bison.
1372 `-f' in `tail'.
1375 Used in `makeinfo'.
1378 `-f' in `cp', `ln', `mv', and `rm'.
1381 `-F' in `shar'.
1385 do anything special to run the server in the background.
1388 Used in `ls', `time', and `ptx'.
1391 `-F' in `m4'.
1394 Used in GDB.
1397 `-g' in `ptx'.
1400 `-x' in `tar'.
1403 `-i' in `ul'.
1406 `-g' in `recode'.
1409 `-g' in `install'.
1412 `-z' in `tar' and `shar'.
1415 `-H' in `m4'.
1421 `-H' in `who'.
1424 Used to ask for brief usage information.
1427 `-d' in `shar'.
1430 `-q' in `ls'.
1433 In `makeinfo', output HTML.
1436 `-u' in `who'.
1439 `-D' in `diff'.
1442 `-I' in `ls'; `-x' in `recode'.
1445 `-w' in `diff'.
1448 `-B' in `ls'.
1451 `-B' in `diff'.
1454 `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
1457 `-i' in `make'.
1460 `-i' in `ptx'.
1463 `-I' in `etags'.
1466 `-f' in Oleo.
1469 `-i' in `tee'.
1472 `-I' in `diff'.
1475 `-b' in `diff'.
1478 `-i' in `tar'.
1481 `-i' in `etags'; `-I' in `m4'.
1484 `-I' in `make'.
1487 `-G' in `tar'.
1490 `-i', `-l', and `-m' in Finger.
1494 user's init file.
1497 `-i' in `expand'.
1500 `-T' in `diff'.
1503 `-i' in `ls'.
1507 `-w' in `tar'.
1510 `-p' in `shar'.
1516 `-j' in `make'.
1519 `-n' in `make'.
1522 `-k' in `make'.
1525 `-k' in `csplit'.
1528 `-k' in `du' and `ls'.
1531 `-l' in `etags'.
1534 `-l' in `wdiff'.
1537 `-g' in `shar'.
1540 `-C' in `split'.
1543 Used in `split', `head', and `tail'.
1546 `-l' in `cpio'.
1550 Used in `gawk'.
1553 `-t' in `cpio'; `-l' in `recode'.
1556 `-t' in `tar'.
1559 `-N' in `ls'.
1562 `-l' in `make'.
1565 Used in `su'.
1568 Used in `uname'.
1571 `-M' in `ptx'.
1574 `-m' in `hello' and `uname'.
1577 `-d' in `cpio'.
1580 `-f' in `make'.
1583 Used in GDB.
1586 `-n' in `xargs'.
1589 `-n' in `xargs'.
1592 `-l' in `xargs'.
1595 `-l' in `make'.
1598 `-P' in `xargs'.
1601 `-T' in `who'.
1604 `-T' in `who'.
1607 `-d' in `diff'.
1610 `-M' in `shar'.
1613 `-m' in `install', `mkdir', and `mkfifo'.
1616 `-m' in `tar'.
1619 `-M' in `tar'.
1622 `-a' in Bison.
1625 `-L' in `m4'.
1628 `-a' in `shar'.
1631 `-W' in `make'.
1634 `-r' in `make'.
1637 `-w' in `shar'.
1640 `-x' in `shar'.
1643 `-3' in `wdiff'.
1646 `-c' in `touch'.
1649 `-D' in `etags'.
1652 `-1' in `wdiff'.
1655 `-d' in `cp'.
1658 `-2' in `wdiff'.
1661 `-S' in `make'.
1664 `-l' in Bison.
1667 `-P' in `shar'.
1670 `-e' in `gprof'.
1673 `-R' in `etags'.
1676 `-p' in `nm'.
1679 Don't print a startup splash screen.
1682 Used in `makeinfo'.
1685 `-a' in `gprof'.
1688 `-E' in `gprof'.
1691 `-m' in `shar'.
1694 Used in `makeinfo'.
1697 Used in `emacsclient'.
1700 Used in various programs to inhibit warnings.
1703 `-n' in `info'.
1706 `-n' in `uname'.
1709 `-f' in `cpio'.
1712 `-n' in `objdump'.
1715 `-0' in `xargs'.
1718 `-n' in `cat'.
1721 `-b' in `cat'.
1724 `-n' in `nm'.
1727 `-n' in `cpio' and `ls'.
1730 Used in GDB.
1733 `-o' in `tar'.
1736 `-o' in `make'.
1739 `-l' in `tar', `cp', and `du'.
1742 `-o' in `ptx'.
1745 `-f' in `gprof'.
1748 `-F' in `gprof'.
1751 `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
1754 In various programs, specify the output file name.
1757 `-o' in `shar'.
1760 `-o' in `rm'.
1763 `-c' in `unshar'.
1766 `-o' in `install'.
1769 `-l' in `diff'.
1772 Used in `makeinfo'.
1775 `-p' in `mkdir' and `rmdir'.
1778 `-p' in `ul'.
1781 `-p' in `cpio'.
1784 `-P' in `finger'.
1787 `-c' in `cpio' and `tar'.
1790 Used in `gawk'.
1793 `-P' in `m4'.
1796 `-f' in `csplit'.
1799 Used in `tar' and `cp'.
1802 `-p' in `su'.
1805 `-m' in `cpio'.
1808 `-s' in `tar'.
1811 `-p' in `tar'.
1814 `-l' in `diff'.
1817 `-L' in `cmp'.
1820 `-p' in `make'.
1823 `-w' in `make'.
1826 `-o' in `nm'.
1829 `-s' in `nm'.
1832 `-p' in `wdiff'.
1835 `-p' in `ed'.
1838 Specify an HTTP proxy.
1841 `-X' in `shar'.
1844 `-q' in `make'.
1847 Used in many programs to inhibit the usual output. Every program
1848 accepting `--quiet' should accept `--silent' as a synonym.
1854 `-Q' in `ls'.
1857 `-n' in `diff'.
1860 Used in `gawk'.
1863 `-B' in `tar'.
1866 Used in GDB.
1869 `-n' in `make'.
1872 `-R' in `tar'.
1875 Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
1878 `-r' in `touch'.
1881 `-r' in `ptx'.
1884 `-r' in `tac' and `etags'.
1887 `-r' in `uname'.
1890 `-R' in `m4'.
1893 `-r' in `objdump'.
1896 `-r' in `cpio'.
1899 `-i' in `xargs'.
1902 `-s' in `diff'.
1905 `-a' in `cpio'.
1908 `-r' in `ls' and `nm'.
1911 `-f' in `diff'.
1914 `-R' in `ptx'.
1917 `-s' in `tar'.
1920 `-p' in `tar'.
1923 `-g' in `stty'.
1926 Used in GDB.
1929 `-S' in `ptx'.
1932 `-S' in `du'.
1935 `-s' in `tac'.
1938 Used by `recode' to chose files or pipes for sequencing passes.
1941 `-s' in `su'.
1944 `-A' in `cat'.
1947 `-p' in `diff'.
1950 `-E' in `cat'.
1953 `-F' in `diff'.
1956 `-T' in `cat'.
1959 Used in many programs to inhibit the usual output. Every program
1960 accepting `--silent' should accept `--quiet' as a synonym.
1963 `-s' in `ls'.
1967 socket, instead of opening and binding a new socket. This
1969 normally needs a reserved port number.
1972 Used in `ls'.
1975 `-W source' in `gawk'.
1978 `-S' in `tar'.
1981 `-H' in `diff'.
1984 `-E' in `unshar'.
1987 `-L' in `shar'.
1990 `-s' in `cat'.
1993 `-w' in `wdiff'.
1996 `-y' in `wdiff'.
2000 to start processing with.
2003 `-s' in `wdiff'.
2006 `-S' in `shar'.
2009 `-S' in `make'.
2012 `-s' in `recode'.
2015 `-s' in `install'.
2018 `-s' in `strip'.
2021 `-S' in `strip'.
2024 `-s' in `shar'.
2027 `-S' in `cp', `ln', `mv'.
2030 `-b' in `csplit'.
2033 `-s' in `gprof'.
2036 `-s' in `du'.
2039 `-s' in `ln'.
2042 Used in GDB and `objdump'.
2045 `-s' in `m4'.
2048 `-s' in `uname'.
2051 `-t' in `expand' and `unexpand'.
2054 `-T' in `ls'.
2057 `-T' in `tput' and `ul'. `-t' in `wdiff'.
2060 `-a' in `diff'.
2063 `-T' in `shar'.
2066 Used in `ls' and `touch'.
2069 Specify how long to wait before giving up on some operation.
2072 `-O' in `tar'.
2075 `-c' in `du'.
2078 `-t' in `make', `ranlib', and `recode'.
2081 `-t' in `m4'.
2085 and `ptx'.
2088 Used in GDB.
2091 `-t' in `ctags'.
2094 `-T' in `ctags'.
2097 `-t' in `ptx'.
2100 `-z' in `tar'.
2103 `-u' in `cpio'.
2106 `-U' in `m4'.
2109 `-u' in `nm'.
2112 `-u' in `cp', `ctags', `mv', `tar'.
2115 Used in `gawk'; same as `--help'.
2118 `-B' in `shar'.
2121 `-V' in `shar'.
2124 Print more information about progress. Many programs support this.
2127 `-W' in `tar'.
2130 Print the version number.
2133 `-V' in `cp', `ln', `mv'.
2136 `-v' in `ctags'.
2139 `-V' in `tar'.
2142 `-W' in `make'.
2145 `-l' in `shar'.
2148 `-w' in `ls' and `ptx'.
2151 `-W' in `ptx'.
2154 `-T' in `who'.
2157 `-z' in `gprof'.
2160 File: standards.info, Node: OID Allocations, Next: Memory Usage, Prev: Option Table, Up: Progra…
2165 The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the
2166 GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP,
2167 X.509 certificates, and so on. The web site
2168 `http://www.alvestrand.no/objectid' has a (voluntary) listing of many
2169 OID assignments.
2172 <maintainers@gnu.org>. Here is a list of arcs currently assigned:
2175 1.3.6.1.4.1.11591 GNU
2177 1.3.6.1.4.1.11591.1 GNU Radius
2179 1.3.6.1.4.1.11591.2 GnuPG
2180 1.3.6.1.4.1.11591.2.1 notation
2181 1.3.6.1.4.1.11591.2.1.1 pkaAddress
2183 1.3.6.1.4.1.11591.3 GNU Radar
2185 1.3.6.1.4.1.11591.4 GNU GSS
2187 1.3.6.1.4.1.11591.5 GNU Mailutils
2189 1.3.6.1.4.1.11591.6 GNU Shishi
2191 1.3.6.1.4.1.11591.7 GNU Radio
2193 1.3.6.1.4.1.11591.8 GNU Dico
2195 1.3.6.1.4.1.11591.12 digestAlgorithm
2196 1.3.6.1.4.1.11591.12.2 TIGER/192
2197 1.3.6.1.4.1.11591.13 encryptionAlgorithm
2198 1.3.6.1.4.1.11591.13.2 Serpent
2199 1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB
2200 1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC
2201 1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB
2202 1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB
2203 1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB
2204 1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC
2205 1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB
2206 1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB
2207 1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB
2208 1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC
2209 1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB
2210 1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB
2211 1.3.6.1.4.1.11591.14 CRC algorithms
2212 1.3.6.1.4.1.11591.14.1 CRC 32
2215 File: standards.info, Node: Memory Usage, Next: File Usage, Prev: OID Allocations, Up: Program …
2221 making any effort to reduce memory usage. For example, if it is
2224 operate on them.
2228 that would artificially limit the size of files it can handle. If a
2232 are bigger than will fit in memory all at once.
2235 in memory and give a fatal error if `malloc' returns zero.
2238 complicate a program merely to avoid their false alarms. For example,
2240 simply to silence such a tool.
2243 File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
2249 read-only file systems. Thus, if the program manages log files, lock
2252 `/etc'.
2254 There are two exceptions. `/etc' is used to store system
2256 files in `/etc' when its job is to update the system configuration.
2259 directory.
2262 File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
2268 writing GNU software.
2272 * Formatting:: Formatting your source code.
2273 * Comments:: Commenting your work.
2274 * Syntactic Conventions:: Clean use of C constructs.
2275 * Names:: Naming variables, functions, and files.
2276 * System Portability:: Portability among different operating systems.
2277 * CPU Portability:: Supporting the range of CPU types.
2278 * System Functions:: Portability and ``standard'' library functions.
2279 * Internationalization:: Techniques for internationalization.
2280 * Character Set:: Use ASCII by default.
2281 * Quote Characters:: Use "..." or '...' in the C locale.
2282 * Mmap:: How you can safely use `mmap'.
2285 File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
2291 function in column one, so that they will start a defun. Several tools
2293 functions. These tools will not work on code not formatted that way.
2296 one when they are inside a function, so that they won't start a defun.
2298 find it useful to treat that definition as a defun.
2301 the function in column one. This helps people to search for function
2302 definitions, and may also help certain tools recognize them. Thus,
2308 ...
2318 ...
2327 ...
2341 program in version 1.2 and newer. It corresponds to the options
2348 formatting styles.
2351 mixture of styles within one program tends to look ugly. If you are
2353 that program.
2370 open-parentheses and after the commas. Especially after the commas.
2373 operator, not after one. Here is the right way:
2379 level of indentation. For example, don't write this:
2392 Insert extra parentheses so that Emacs will indent the code properly.
2395 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2396 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2398 but Emacs would alter it. Adding a set of parentheses produces
2401 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2402 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2413 pages at logical places (but not within a function). It does not matter
2415 page. The formfeeds should appear alone on lines by themselves.
2418 File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writin…
2423 Every program should start with a comment saying briefly what it is for.
2424 Example: `fmt - filter for simple filling of text'. This comment
2426 of the program.
2430 file.
2434 countries can read. If you do not write English well, please write
2436 rewrite them. If you can't write comments in English, please find
2437 someone to work with you and translate your comments into English.
2441 arguments mean and are used for. It is not necessary to duplicate in
2443 used in its customary fashion. If there is anything nonstandard about
2448 to say so.
2450 Also explain the significance of the return value, if there is one.
2453 so that the Emacs sentence commands will work. Also, please write
2454 complete sentences and capitalize the first word. If a lower-case
2456 Changing the spelling makes it a different identifier. If you don't
2458 differently (e.g., "The identifier lower-case is ...").
2461 names to speak about the argument values. The variable name itself
2463 about the value rather than the variable itself. Thus, "the inode
2464 number NODE_NUM" rather than "an inode".
2467 the comment before it, because readers can see that for themselves.
2469 function itself would be off the bottom of the screen.
2474 zero means continue them. */
2478 conditionals (just a few lines) that are not nested. The comment should
2480 sense_. `#else' should have a comment describing the condition _and
2481 sense_ of the code that follows. For example:
2484 ...
2486 ...
2489 ...
2495 ...
2497 ...
2500 ...
2504 File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
2509 Please explicitly declare the types of all objects. For example, you
2511 declare functions to return `int' rather than omitting the `int'.
2514 code whenever it issues a warning. If you want to do this, then do.
2516 for valid and legitimate code which they do not want to change. If you
2517 want to do this, then do. The compiler should be your servant, not
2518 your master.
2522 `-Wconversion' and `-Wundef'. These tools can help find bugs and
2525 other complications. For example, please don't insert casts to `void'
2526 or calls to do-nothing functions merely to pacify a lint checker.
2531 else should go in a header file. Don't put `extern' declarations inside
2532 functions.
2536 function. Instead of doing this, it is better to declare a separate
2538 meaningful. This not only makes programs easier to understand, it also
2539 facilitates optimization by good compilers. You can also move the
2541 all its uses. This makes the program even cleaner.
2544 identifiers. GCC's `-Wshadow' option can detect this problem.
2546 Don't declare multiple variables in one declaration that spans lines.
2547 Start a new declaration on each line, instead. For example, instead of
2563 anyway.)
2566 statement, always put braces around the `if'-`else'. Thus, never write
2589 ...
2591 ...
2597 ...
2601 ...
2605 same declaration. Instead, declare the structure tag separately and
2606 then use it to declare the variables or typedefs.
2609 `while'-conditions are ok). For example, don't write this:
2620 This example uses zero without a cast as a null pointer constant.
2622 varargs function or when using `sizeof'.
2625 File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: W…
2631 comments of a sort. So don't choose terse names--instead, look for
2633 function. In a GNU program, names should be English, like other
2634 comments.
2637 within one context, where (presumably) comments explain their purpose.
2639 Try to limit your use of abbreviations in symbol names. It is ok to
2641 frequently, but don't use lots of obscure abbreviations.
2644 word commands can be useful within them. Stick to lower case; reserve
2646 follow a uniform convention.
2649 don't use names like `iCantReadThis'.
2653 the option-letter. A comment should state both the exact meaning of
2654 the option and its letter. For example,
2656 /* Ignore changes in horizontal whitespace (-b). */
2660 `enum' rather than `#define'. GDB knows about enumeration constants.
2664 shortens the names. You can use the program `doschk' to test for this.
2668 into older System V systems. Please preserve this feature in the
2670 new GNU programs. `doschk' also reports file names longer than 14
2671 characters.
2674 File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing…
2680 versions. For a GNU program, this kind of portability is desirable, but
2681 not paramount.
2684 kernel, compiled with the GNU C compiler, on various types of CPU. So
2686 limited. But it is important to support Linux-based GNU systems, since
2687 they are the form of GNU that is popular.
2691 to. Supporting a variety of Unix-like systems is desirable, although
2692 not paramount. It is usually not too hard, so you may as well do it.
2694 be hard.
2697 to use Autoconf. It's unlikely that your program needs to know more
2700 written.
2702 Avoid using the format of semi-internal data bases (e.g.,
2703 directories) when there is a higher-level alternative (`readdir').
2707 work. When that is the case, it is better to spend your time adding
2709 supporting other incompatible systems.
2711 If you do support Windows, please do not abbreviate it as "win". In
2712 hacker terminology, calling something a "win" is a form of praise.
2714 please don't do this in GNU packages. Instead of abbreviating
2716 or "w". In GNU Emacs, for instance, we use `w32' in file names of
2718 called `WINDOWSNT'.
2721 when compiling your C files. When you compile on GNU or GNU/Linux,
2724 the same function names in some other way in your program. (You don't
2726 program more portable to other systems.)
2729 using their names for any other meanings. Doing so would make it hard
2730 to move your code into other GNU programs.
2733 File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, …
2740 requirements. It is absolutely essential to handle these differences.
2742 `int' will be less than 32 bits. We don't support 16-bit machines in
2743 GNU.
2746 `long' will be smaller than predefined types like `size_t'. For
2753 counterexample: 64-bit programs on Microsoft Windows. We will leave it
2755 out how to do it.
2759 with them. One way to print an `off_t' value portably is to print its
2760 digits yourself, one by one.
2763 of its least-significant byte. This is false on big-endian machines.
2767 ...
2771 Instead, use `unsigned char' as follows. (The `unsigned' is for
2773 is integer overflow checking.)
2782 Avoid casting pointers to integers if you can. Such casts greatly
2783 reduce portability, and in most programs they are easy to avoid. In the
2787 sizes. You will also need to make provision for systems in which the
2789 from zero.
2792 File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability,…
2798 systems lacked a full implementation of ANSI/ISO C89. Nowadays,
2800 all of C99. Similarly, most systems implement POSIX.1-1993 libraries
2801 and tools, and many have POSIX.1-2001.
2805 clearer, more portable, or faster code. You should use standard
2808 them. In any case, don't make your own declaration of system
2809 functions; that's a recipe for conflict.
2812 portability issue on some system or another. Here are some examples:
2815 Names with trailing `/''s are mishandled on many platforms.
2820 incorrect.
2823 May return `int' instead of `ssize_t'.
2826 On Windows, `errno' is not set on failure.
2828 Gnulib (http://www.gnu.org/software/gnulib/) is a big help in this
2829 regard. Gnulib provides implementations of standard interfaces on many
2833 GNU systems.
2838 functions (`xmalloc', `xrealloc'), and output of error messages.
2843 and use the Gnulib code to supply the missing pieces.
2846 portability: *note Introduction: (gnulib)Top. and *note Portable C and
2847 C++: (autoconf)Portable C and C++. Please consult them for many more
2848 details.
2851 File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, …
2857 messages in a program into various languages. You should use this
2858 library in every program. Use English for the messages as they appear
2860 other languages.
2865 printf (gettext ("Processing file '%s'..."), file);
2868 '%s'..."' with a translated version.
2871 `gettext' when you add new strings that call for translation.
2874 name" for the package. The text domain name is used to separate the
2875 translations for this package from the translations for other packages.
2877 package--for example, `coreutils' for the GNU core utilities.
2880 assumptions about the structure of words or sentences. When you want
2884 sentence framework.
2896 to be substituted in the other string. Worse, in some languages (like
2899 happens to be not the same for "disk" as for "floppy disk".
2909 printf ("# Implicit rule search has%s been done.\n",
2914 more than one place in the sentence. By contrast, adding `gettext'
2918 ? "# Implicit rule search has been done.\n",
2919 : "# Implicit rule search has not been done.\n");
2927 by adding `s'. If you apply gettext to the format string, like this,
2933 `s' for the plural. Here is a better way, with gettext being applied to
2942 24, ... and one for the rest. The GNU `ngettext' function solves this
2949 File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, …
2957 the application domain. For example, if source code deals with the
2959 accented characters in month names like "Flore'al". Also, it is OK
2961 names of contributors in change logs (*note Change Logs::).
2964 with one encoding, certainly within a single file. UTF-8 is likely to
2965 be the best choice.
2968 File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C
2975 0x27 (`'') for both opening and closing quotes. Although GNU programs
2979 looks better.
2982 locale-specific quotes in non-C locales. For example:
2984 printf (gettext ("Processing file '%s'..."), file);
2987 `"Traitement de fichier < %s >..."', yielding quotes more appropriate
2988 for a French locale.
2991 directly. By convention, `gettext' translates the string `"`"' to the
2993 can use these translations. Generally, though, it is better to
2994 translate quote characters in the context of longer strings.
2998 reliable. For example, you could escape special characters using
2999 conventions from the C language or the Bourne shell. See for example
3000 the option `--quoting-style' of GNU `ls'.
3003 File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C
3009 files. It may work on some files and fail on others.
3013 doing the job in another way using `read' and `write'.
3017 different kinds of "ordinary files". Many of them support `mmap', but
3018 some do not. It is important to make programs handle all these kinds
3019 of files.
3022 File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
3028 for both reference and tutorial purposes. If the package can be
3030 extending it, as well as just using it.
3034 * GNU Manuals:: Writing proper manuals.
3035 * Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
3036 * Manual Structure Details:: Specific structure conventions.
3037 * License for Manuals:: Writing the distribution terms for a manual.
3038 * Manual Credits:: Giving credit to documentation contributors.
3039 * Printed Manuals:: Mentioning the printed manual.
3040 * NEWS File:: NEWS files supplement manuals.
3041 * Change Logs:: Recording changes.
3042 * Man Pages:: Man pages are secondary.
3044 from other manuals.
3047 File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
3053 formatting language. Every GNU package should (ideally) have
3054 documentation in Texinfo both for reference and for learners. Texinfo
3056 and to generate an Info file. It is also possible to generate HTML
3057 output from Texinfo source. See the Texinfo manual, either the
3059 Info subsystem (`C-h i').
3062 converted automatically into Texinfo. It is ok to produce the Texinfo
3063 documentation by conversion this way, as long as it gives good results.
3066 the topic and reads it straight through. This means covering basic
3067 topics at the beginning, and advanced topics only later. This also
3068 means defining every specialized term when it is first used.
3071 structure for its documentation. But this structure is not necessarily
3073 confusing for a user.
3076 concepts and questions that a user will have in mind when reading it.
3079 within the manual). Sometimes this structure of ideas matches the
3081 often they are different. An important part of learning to write good
3084 and look for better alternatives.
3088 have its own manual. That would be following the structure of the
3090 understand.
3092 Instead, each manual should cover a coherent _topic_. For example,
3095 as well as `cmp'. By documenting these programs together, we can make
3096 the whole subject clearer.
3099 the program's command-line options and all of its commands. It should
3100 give examples of their use. But don't organize the manual as a list of
3101 features. Instead, organize it logically, by subtopics. Address the
3103 program does. Don't just tell the reader what each feature can do--say
3104 what jobs it is good for, and show how to use it for those jobs.
3106 avoid.
3108 In general, a GNU manual should serve both as tutorial and reference.
3110 and for reading straight through (appendixes aside). A GNU manual
3112 start, and should also provide all the details that hackers want. The
3114 what we mean.
3116 That is not as hard as it first sounds. Arrange each chapter as a
3118 text, so that reading the chapter straight through makes sense. Do
3120 section into paragraphs. The watchword is, _at each point, address the
3121 most fundamental and important issue raised by the preceding text._
3124 are purely tutorial and cover the basics of the subject. These provide
3125 the framework for a beginner to understand the rest of the manual. The
3126 Bison manual provides a good example of how to do this.
3130 of the program. One combined Index should do for a short manual, but
3131 sometimes for a complex package it is better to use multiple indices.
3134 Defining the Entries of an Index: (texinfo)Indexing Commands.
3138 inadequate explanation of the underlying concepts. (There are, of
3139 course, some exceptions.) Also, Unix man pages use a particular format
3140 which is different from what we use in GNU manuals.
3143 bugs _in the text of the manual_.
3146 documentation; use "file name" (two words) instead. We use the term
3147 "path" only for search paths, which are lists of directory names.
3150 a computer program. Please use "invalid" for this, and reserve the
3151 term "illegal" for activities prohibited by law.
3154 is a function. `foo ()' is not a function, it is a function call with
3155 no arguments.
3158 File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU M…
3164 for each function, command or variable. You may be tempted to write a
3166 little additional text to go around them--but you must not do it. That
3167 approach is a fundamental mistake. The text of well-written
3168 documentation strings will be entirely wrong for a manual.
3171 screen, there will be no other text to introduce or explain it.
3172 Meanwhile, it can be rather informal in style.
3175 alone; it appears in the context of a section or subsection. Other text
3178 variables. The previous descriptions of functions and variables in the
3179 section will also have given information about the topic. A description
3181 redundancy looks bad. Meanwhile, the informality that is acceptable in
3182 a documentation string is totally unacceptable in a manual.
3185 manual is to use them as a source of information for writing good text.
3188 File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strin…
3194 packages documented in the manual. The Top node of the manual should
3195 also contain this information. If the manual is changing more
3197 number for the manual in both of these places.
3200 `PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
3203 for in a man page). Start with an `@example' containing a template for
3204 all the options and arguments that the program uses.
3207 of the above patterns. This identifies the node which that item points
3208 to as the node for this purpose, regardless of the node's actual name.
3212 every Texinfo file to have one.
3215 for each program described in the manual.
3218 File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure De…
3224 are more than a few pages long. Likewise for a collection of short
3226 collection. For a single short document, you can use a very permissive
3227 non-copyleft license, to avoid taking up space with a long license.
3229 See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
3230 of how to employ the GFDL.
3233 GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
3237 it.
3240 File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, U…
3246 on the title page of the manual. If a company sponsored the work, thank
3248 company as an author.
3251 File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documen…
3256 The FSF publishes some GNU manuals in printed form. To encourage sales
3260 `http://www.gnu.org/order/order.html'. This should not be included in
3261 the printed manual, though, because there it is redundant.
3264 the user can print out the manual from the sources.
3267 File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentat…
3273 which contains a list of user-visible changes worth mentioning. In
3275 version they pertain to. Don't discard old items; leave them in the
3276 file after the newer items. This way, a user upgrading from any
3277 previous version can see what is new.
3281 that file.
3284 File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
3290 files. The purpose of this is so that people investigating bugs in the
3291 future will know about the changes that might have introduced the bug.
3292 Often a new bug can be found by looking at what was recently changed.
3295 history of how the conflicting concepts arose and who they came from.
3306 File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
3308 6.8.1 Change Log Concepts
3312 explains how earlier versions were different from the current version.
3314 tell them what is in it. What they want from a change log is a clear
3315 explanation of how the earlier version differed.
3318 entire directory. Each directory can have its own change log, or a
3320 you.
3323 version control system such as RCS or CVS. This can be converted
3325 command `C-x v a' (`vc-update-change-log') does the job.
3328 they work together. However, sometimes it is useful to write one line
3329 to describe the overall purpose of a change or a batch of changes. If
3330 you think that a change calls for explanation, you're probably right.
3332 in the code, where people will see it whenever they see the code. For
3335 definition to explain what it does.
3338 files (manuals, help files, etc.) in change logs. However, we've been
3340 copyright records.
3343 command `M-x add-change-log-entry'. An entry should have an asterisk,
3345 changed functions, variables or whatever, followed by a colon. Then
3346 describe the changes you made to that function or variable.
3349 File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concept…
3351 6.8.2 Style of Change Logs
3356 followed by descriptions of specific changes. (These examples are
3357 drawn from Emacs and GCC.)
3359 1998-08-17 Richard Stallman <rms@gnu.org>
3361 * register.el (insert-register): Return nil.
3362 (jump-to-register): Likewise.
3364 * sort.el (sort-subr): Return nil.
3366 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3367 Restart the tex shell if process is gone or stopped.
3368 (tex-shell-running): New function.
3370 * expr.c (store_one_arg): Round size up for move_block_to_reg.
3371 (expand_call): Round up when emitting USE insns.
3372 * stmt.c (assign_parms): Round size up for move_block_from_reg.
3374 It's important to name the changed function or variable in full.
3375 Don't abbreviate function or variable names, and don't combine them.
3378 they won't find it when they search.
3381 names by writing `* register.el ({insert,jump-to}-register)'; this is
3383 `insert-register' would not find that entry.
3385 Separate unrelated change log entries with blank lines. When two
3387 then don't put blank lines between them. Then you can omit the file
3388 name and the asterisk when successive entries are in the same file.
3394 * keyboard.c (menu_bar_items, tool_bar_items)
3395 (Fexecute_extended_command): Deal with 'keymap' property.
3398 in the change log entry rather than in the text of the entry. In other
3401 2002-07-14 John Doe <jdoe@gnu.org>
3403 * sewing.c: Make it sew.
3407 2002-07-14 Usual Maintainer <usual@gnu.org>
3409 * sewing.c: Make it sew. Patch by jdoe@gnu.org.
3411 As for the date, that should be the date you applied the change.
3414 File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Log…
3416 6.8.3 Simple Changes
3420 log.
3425 the callers that you changed. Just write in the entry for the function
3428 * keyboard.c (Fcommand_execute): New arg SPECIAL.
3429 All callers changed.
3432 an entry for the file, without mentioning the functions. Just "Doc
3433 fixes" is enough for the change log.
3436 documentation files. This is because documentation is not susceptible
3437 to bugs that are hard to fix. Documentation does not consist of parts
3438 that must interact in a precisely engineered fashion. To correct an
3441 actually works.
3445 the records of authorship more accurate.
3448 File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple…
3450 6.8.4 Conditional Changes
3454 or static conditions. For example, C programs can contain compile-time
3457 for certain versions of the interpreter; and Automake `Makefile.am'
3459 only to be considered if a configure-time Automake conditional is true.
3463 entirely dependent on a build-time condition. It is useful to indicate
3464 in the change log the conditions for which a change applies.
3467 brackets around the name of the condition_.
3470 variations, so here are some examples to help clarify. This first
3474 * xterm.c [SOLARIS2]: Include <string.h>.
3475 * FilePath.pm [$^O eq 'VMS']: Import the VMS::Feature module.
3476 * framework.py [sys.version_info < (2, 6)]: Make "with" statement
3478 to support also python 2.5.
3482 self-evident.
3488 * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3494 * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3499 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3502 File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change L…
3504 6.8.5 Indicating the Part Changed
3508 enclosing an indication of what the changed part does. Here is an entry
3512 * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
3513 user-specified option string is empty.
3516 File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Docu…
3521 In the GNU project, man pages are secondary. It is not necessary or
3522 expected for every GNU program to have a man page, but some of them do.
3523 It's your choice whether to include a man page in your program.
3526 requires continual effort each time the program is changed. The time
3527 you spend on the man page is time taken away from more useful work.
3530 be a small job. Then there is little reason not to include a man page,
3531 if you have one.
3534 may be a substantial burden. If a user offers to donate a man page,
3535 you may find this gift costly to accept. It may be better to refuse
3537 for maintaining it--so that you can wash your hands of it entirely. If
3540 distribution until someone else agrees to update it.
3544 updating. If so, put a prominent note near the beginning of the man
3546 is more authoritative. The note should say how to access the Texinfo
3547 documentation.
3550 license. The simple all-permissive license is appropriate for simple
3552 Notices for Other Files.).
3556 Manuals::).
3559 (`http://www.gnu.org/software/help2man/') is one way to automate
3560 generation of a man page, in this case from `--help' output. This is
3561 sufficient in many cases.
3564 File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
3570 program you are documenting.
3573 a new algebra textbook can read other books on algebra. A large portion
3576 everyone who writes about the subject. But be careful not to copy your
3578 documentation. Copying from free documentation may be ok; please check
3579 with the FSF about the individual case.
3582 File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
3588 tar file and putting it up for FTP. You should set up your software so
3589 that it can be configured to run on a variety of systems. Your Makefile
3591 layout should also conform to the standards discussed below. Doing so
3593 GNU software.
3597 * Configuration:: How configuration of GNU packages should work.
3598 * Makefile Conventions:: Makefile conventions.
3602 File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
3608 `configure'. This script is given arguments which describe the kind of
3609 machine and system you want to compile the program for. The
3611 affect compilation.
3614 `configure' script in GNU packages. Many packages implement it using
3615 GNU Autoconf (*note Introduction: (autoconf)Top.) and/or GNU Automake
3616 (*note Introduction: (automake)Top.), but you do not have to use these
3617 tools. You can implement it any way you like; for instance, by making
3619 system.
3622 from a standard name such as `config.h' to the proper configuration
3623 file for the chosen system. If you use this technique, the
3624 distribution should _not_ contain a file named `config.h'. This is so
3626 first.
3628 Another thing that `configure' can do is to edit the Makefile. If
3630 `Makefile'. Instead, it should include a file `Makefile.in' which
3631 contains the input used for editing. Once again, this is so that people
3632 won't be able to build the program without configuring it first.
3636 setting up the same configuration that was set up last time. The files
3637 that `configure' reads should be listed as dependencies of `Makefile'.
3641 automatically using `configure'. This is so that users won't think of
3642 trying to edit them by hand.
3644 The `configure' script should write a file named `config.status'
3646 program was last configured. This file should be a shell script which,
3647 if run, will recreate the same configuration.
3651 it is not the current directory). This makes it possible to build the
3653 not modified.
3656 check both `.' and `..' to see if it can find the sources. If it finds
3657 the sources in one of these places, it should use them from there.
3659 exit with nonzero status.
3662 definition of `VPATH' into the Makefile. Some rules may need to refer
3663 explicitly to the specified source directory. To make this possible,
3665 value is precisely the specified directory.
3669 Directory Variables::). Here is the list:
3677 the type of system to build the program for. This argument should look
3683 `i686-pc-linux-gnu'.
3686 alternatives for how to describe a machine. Thus,
3687 `athlon-pc-gnu/linux' would be a valid alias. There is a shell script
3688 called `config.sub'
3689 (http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD)
3691 canonicalize aliases.
3695 argument. For example, `configure --build=i686-pc-linux-gnu' is
3696 equivalent to `configure i686-pc-linux-gnu'. When the build type is
3698 normally guess it using the shell script `config.guess'
3699 (http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD).
3708 facility called FEATURE. This allows users to choose which
3709 optional features to include. Giving an optional PARAMETER of
3710 `no' should omit FEATURE, if it is built by default.
3713 another. No `--enable' option should ever substitute one useful
3714 behavior for another useful behavior. The only proper use for
3716 or exclude it.
3720 to work with PACKAGE.
3723 `gnu-libc', `gdb', `x', and `x-toolkit'.
3726 find certain files. That is outside the scope of what `--with'
3727 options are for.
3730 Set the value of the variable VARIABLE to VALUE. This is used to
3732 process. For example, the user could issue `configure CFLAGS=-g
3734 default optimization.
3737 ./configure CC=gcc
3739 CC=gcc ./configure
3741 `config.status'. However, both methods should be supported.
3745 the particular package at hand. In particular, they should accept any
3746 option that starts with `--with-' or `--enable-'. This is so users
3748 single set of options.
3752 think of. That is deliberate. We want to limit the possible
3753 configuration options in GNU software. We do not want GNU programs to
3754 have idiosyncratic configuration options.
3757 cross-compilation. In such a case, the host and target machines for the
3758 program may be different.
3762 works for the same type of machine that it runs on.
3766 uses the same syntax as BUILDTYPE. The host type normally defaults to
3767 the build type.
3771 option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
3772 for the host type. So the command would look like this:
3774 ./configure --host=HOSTTYPE --target=TARGETTYPE
3776 The target type normally defaults to the host type. Programs for
3779 cross-operation is not a meaningful operation.
3781 Some programs have ways of configuring themselves automatically. If
3783 ignore most of its arguments.
3786 File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Mana…
3792 programs. Using Automake will help you write a Makefile that follows
3793 these conventions. For more information on portable Makefiles, see
3794 POSIX and *note Portable Make Programming: (autoconf)Portable Make.
3798 * Makefile Basics:: General conventions for Makefiles.
3799 * Utilities in Makefiles:: Utilities to be used in Makefiles.
3800 * Command Variables:: Variables for specifying commands.
3801 * DESTDIR:: Supporting staged installs.
3802 * Directory Variables:: Variables for installation directories.
3803 * Standard Targets:: Standard targets for users.
3805 rule: normal, pre-install and post-install.
3808 File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventi…
3810 7.2.1 General Conventions for Makefiles
3818 inherited from the environment. (This is never a problem with GNU
3819 `make'.)
3822 implicit rules, and this sometimes creates confusion or misbehavior. So
3826 .SUFFIXES:
3827 .SUFFIXES: .c .o
3830 suffixes which may be subject to implicit rules in this Makefile.
3832 Don't assume that `.' is in the path for command execution. When
3834 make, please make sure that it uses `./' if the program is built as
3836 the source code. Without one of these prefixes, the current search
3837 path is used.
3839 The distinction between `./' (the "build directory") and
3842 `configure'. A rule of the form:
3844 foo.1 : foo.man sedscript
3845 sed -f sedscript foo.man > foo.1
3848 `foo.man' and `sedscript' are in the source directory.
3853 wherever it is. (Many versions of `make' set `$<' only in implicit
3854 rules.) A Makefile target like
3856 foo.o : bar.c
3857 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
3861 foo.o : bar.c
3862 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
3864 in order to allow `VPATH' to work correctly. When the target has
3866 to make the rule work well. For example, the target above for `foo.1'
3869 foo.1 : foo.man sedscript
3870 sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@
3874 Bison or Flex. Since these files normally appear in the source
3876 build directory. So Makefile rules to update them should put the
3877 updated files in the source directory.
3882 in any way.
3885 their subtargets) work correctly with a parallel `make'.
3888 File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basi…
3890 7.2.2 Utilities in Makefiles
3895 the POSIX shell), not `csh'. Don't use any special features of `ksh'
3897 `sh'.
3905 Compression programs such as `gzip' can be used in the `dist' rule.
3908 options and features of these programs. For example, don't use `mkdir
3910 all and with others, it is not safe for parallel execution. For a list
3912 (autoconf)Portable Shell.
3915 since a few file systems don't support them.
3919 so that the user can substitute alternatives. Here are some of the
3931 bad happens if the system does not have the program in question.
3934 a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
3937 systems that don't have symbolic links.
3945 exist.
3948 File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up:…
3950 7.2.3 Variables for Specifying Commands
3954 options, and so on.
3956 In particular, you should run most utility programs via variables.
3959 whenever you need to use Bison.
3963 need to replace them with other programs.
3966 is used to supply options to the program. Append `FLAGS' to the
3968 example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
3970 but we keep them because they are standard.) Use `CPPFLAGS' in any
3973 of `ld'.
3976 compilation of certain files, do not include them in `CFLAGS'. Users
3977 expect to be able to specify `CFLAGS' freely themselves. Instead,
3983 ALL_CFLAGS = -I. $(CFLAGS)
3984 .c.o:
3988 _required_ for proper compilation. You can consider it a default that
3989 is only recommended. If the package is set up so that it is compiled
3991 value of `CFLAGS' as well.
3995 the others.
3998 those which do compilation and those which do linking.
4001 basic command for installing a file into the system.
4004 and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
4006 644'.) Then it should use those variables as the commands for actual
4007 installation, for executables and non-executables respectively.
4011 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
4014 target files, as explained in the next section.
4022 File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Ma…
4024 7.2.4 `DESTDIR': Support for Staged Installs
4031 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
4034 command line as an absolute file name. For example:
4039 targets, as those are the only targets where it is useful.
4042 `/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
4044 `/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
4045 instead.
4050 into a temporary location (`DESTDIR'). However, installed files
4052 will not be modified.
4055 then the files are installed into their expected locations by default.
4058 contents.
4060 `DESTDIR' support is commonly used in package creation. It is also
4064 those permissions. Finally, it can be useful with tools such as
4067 operations. So, we strongly recommend GNU packages support `DESTDIR',
4068 though it is not an absolute requirement.
4071 File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Mak…
4073 7.2.5 Variables for Installation Directories
4077 easy to install in a nonstandard place. The standard names for these
4079 below. They are based on a standard file system layout; variants of it
4080 are used in GNU/Linux and other modern operating systems.
4083 (e.g., `make prefix=/usr install' or `configure' (e.g., `configure
4084 --prefix=/usr'). GNU packages should not try to guess which value
4087 packages behave identically, allowing the installer to achieve any
4088 desired layout.
4091 created (if necessary) before they are installed into.
4093 These first two variables set the root for the installation. All the
4096 directories.
4100 listed below. The default value of `prefix' should be
4101 `/usr/local'. When building the complete GNU system, the prefix
4102 will be empty and `/usr' will be a symbolic link to `/'. (If you
4103 are using Autoconf, write it as `@prefix@'.)
4106 one used to build the program should _not_ recompile the program.
4110 variables listed below. The default value of `exec_prefix' should
4111 be `$(prefix)'. (If you are using Autoconf, write it as
4112 `@exec_prefix@'.)
4117 directories.
4121 program.
4124 directories.
4128 run. This should normally be `/usr/local/bin', but write it as
4129 `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
4130 `@bindir@'.)
4135 administrators. This should normally be `/usr/local/sbin', but
4136 write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
4137 write it as `@sbindir@'.)
4141 programs rather than by users. This directory should normally be
4142 `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
4143 (If you are using Autoconf, write it as `@libexecdir@'.)
4146 you should install your data in a subdirectory thereof. Most
4149 `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
4152 categories in two ways.
4155 normally modified (though users may edit some of these).
4160 others may never be shared between two machines.
4162 This makes for six different possibilities. However, we want to
4164 files and libraries. It is much cleaner to make other data files
4165 architecture-independent, and it is generally not hard.
4172 architecture-independent data files. This should normally be
4173 `/usr/local/share', but write it as `$(prefix)/share'. (If you
4174 are using Autoconf, write it as `@datarootdir@'.) `datadir''s
4176 `mandir', and others.
4180 architecture-independent data files for this program. This is
4183 files without altering the location for Info files, man pages, etc.
4186 `$(datarootdir)'. (If you are using Autoconf, write it as
4187 `@datadir@'.)
4190 should install your data in a subdirectory thereof. Most packages
4191 install their data under `$(datadir)/PACKAGE-NAME/'.
4195 single machine-that is to say, files for configuring a host.
4197 forth belong here. All the files in this directory should be
4198 ordinary ASCII text files. This directory should normally be
4199 `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
4200 using Autoconf, write it as `@sysconfdir@'.)
4203 belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
4206 excluded). Those probably belong in `$(localstatedir)'.
4210 which the programs modify while they run. This should normally be
4211 `/usr/local/com', but write it as `$(prefix)/com'. (If you are
4212 using Autoconf, write it as `@sharedstatedir@'.)
4216 while they run, and that pertain to one specific machine. Users
4219 separate files that go in `$(datadir)' or `$(sysconfdir)'.
4221 it as `$(prefix)/var'. (If you are using Autoconf, write it as
4222 `@localstatedir@'.)
4225 types of files, if your program has them. Every GNU package should
4227 `libdir' or `lispdir'.
4231 programs with the C `#include' preprocessor directive. This
4233 `$(prefix)/include'. (If you are using Autoconf, write it as
4234 `@includedir@'.)
4237 directory `/usr/local/include'. So installing the header files
4238 this way is only useful with GCC. Sometimes this is not a problem
4239 because some libraries are only really intended to work with GCC.
4240 But some libraries are intended to work with other compilers.
4242 specified by `includedir' and one specified by `oldincludedir'.
4246 compilers other than GCC. This should normally be `/usr/include'.
4247 (If you are using Autoconf, you can write it as `@oldincludedir@'.)
4250 `oldincludedir' is empty. If it is, they should not try to use
4251 it; they should cancel the second installation of the header files.
4254 unless the header came from the same package. Thus, if your Foo
4255 package provides a header file `foo.h', then it should install the
4257 is no `foo.h' there or (2) the `foo.h' that exists came from the
4258 Foo package.
4260 To tell whether `foo.h' came from the Foo package, put a magic
4261 string in the file--part of a comment--and `grep' for that string.
4265 for this package. By default, it should be
4267 `$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write
4268 it as `@docdir@'.) The YOURPKG subdirectory, which may include a
4270 such as `README'.
4273 The directory for installing the Info files for this package. By
4275 written as `$(datarootdir)/info'. (If you are using Autoconf,
4276 write it as `@infodir@'.) `infodir' is separate from `docdir' for
4277 compatibility with existing practice.
4284 format. They should all be set to `$(docdir)' by default. (If
4286 etc.) Packages which supply several translations of their
4288 `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
4289 `en' or `pt_BR'.
4292 The directory for object files and libraries of object code. Do
4294 `$(libexecdir)' instead. The value of `libdir' should normally be
4295 `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
4296 are using Autoconf, write it as `@libdir@'.)
4299 The directory for installing any Emacs Lisp files in this package.
4301 should be written as `$(datarootdir)/emacs/site-lisp'.
4303 If you are using Autoconf, write the default as `@lispdir@'. In
4305 your `configure.in' file:
4312 this package. By default, it should be `/usr/local/share/locale',
4313 but it should be written as `$(datarootdir)/locale'. (If you are
4314 using Autoconf, write it as `@localedir@'.) This directory
4315 usually has a subdirectory per locale.
4321 this package. It will normally be `/usr/local/share/man', but you
4322 should write it as `$(datarootdir)/man'. (If you are using
4323 Autoconf, write it as `@mandir@'.)
4326 The directory for installing section 1 man pages. Write it as
4327 `$(mandir)/man1'.
4330 The directory for installing section 2 man pages. Write it as
4333 `...'
4335 man page. Write a manual in Texinfo instead. Man pages are just
4337 secondary application only.*
4340 The file name extension for the installed man page. This should
4342 normally be `.1'.
4345 The file name extension for installed section 1 man pages.
4348 The file name extension for installed section 2 man pages.
4350 `...'
4352 install man pages in more than one section of the manual.
4357 The directory for the sources being compiled. The value of this
4358 variable is normally inserted by the `configure' shell script.
4359 (If you are using Autoconf, use `srcdir = @srcdir@'.)
4363 # Common prefix for installation directories.
4364 # NOTE: This directory must exist when you start the install.
4369 # Where to put the executable for the command `gcc'.
4371 # Where to put the directories used by the compiler.
4373 # Where to put the Info files.
4378 into a subdirectory particular to that program. If you do this, you
4379 should write the `install' rule to create these subdirectories.
4382 of any of the variables listed above. The idea of having a uniform set
4384 specify the exact same values for several different GNU packages. In
4386 they will work sensibly when the user does so.
4390 believe all of them are. When any are missing, the descriptions here
4391 serve as specifications for what Autoconf will implement. As a
4394 supports them.
4397 File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory …
4399 7.2.6 Standard Targets for Users
4405 Compile the entire program. This should be the default target.
4409 asked for.
4412 that executable programs have debugging symbols. Otherwise, you
4414 far from easy to reproduce with a fresh build.
4418 to the file names where they should reside for actual use. If
4420 installed, this target should run that test.
4422 Do not strip executables when installing them. This helps eventual
4425 loaded during normal execution. Users that need stripped binaries
4426 may invoke the `install-strip' target to do that.
4430 provided `make all' has just been done. This is convenient for
4432 another.
4435 to be installed, if they don't already exist. This includes the
4437 `exec_prefix', as well as all subdirectories that are needed. One
4439 below.
4442 `make' will ignore any errors. This is in case there are systems
4443 that don't have the Unix man page documentation system installed.
4447 the `install-info' program if it is present. `install-info' is a
4449 entry for the given Info file; it is part of the Texinfo package.
4453 being present.
4455 do-install-info: foo.info installdirs
4457 # Prefer an info file in . to one in srcdir.
4458 if test -f foo.info; then d=.; \
4460 $(INSTALL_DATA) $$d/foo.info \
4461 "$(DESTDIR)$(infodir)/foo.info"
4462 # Run install-info only if it exists.
4464 # line so we notice real errors from install-info.
4466 # fail gracefully when there is an unknown command.
4471 "$(DESTDIR)$(infodir)/foo.info"; \
4476 commands and "post-installation" commands. *Note Install Command
4477 Categories::.
4485 the package, if that format is desired. GNU prefers Info files,
4486 so these must be installed by the `install' target.
4491 installation directory, such as `htmldir'. As one example, if
4496 overwrite each other.
4499 the FORMAT target, for example, by making FORMAT a dependency.
4503 `install-*' targets create.
4506 done, only the directories where files are installed.
4509 just like the installation commands. *Note Install Command
4510 Categories::.
4514 them. In simple cases, this target can use the `install' target in
4523 target; it has to strip the executables but not the scripts.
4526 directory which are being copied for installation. It should only
4527 strip the copies that are installed.
4530 are sure the program has no bugs. However, it can be reasonable
4532 the unstripped executable elsewhere in case there is a bug.
4536 created by building the program. Also delete files in other
4537 directories if they are created by this makefile. However, don't
4538 delete the files that record the configuration. Also preserve
4540 the distribution comes with them. There is no need to delete
4542 could have existed anyway.
4544 Delete `.dvi' files here if they are not part of the distribution.
4548 makefile) that are created by configuring or building the program.
4551 files that were in the distribution. However, there is no need to
4553 they could have existed anyway.
4557 normally don't want to recompile. For example, the `mostlyclean'
4558 target for GCC does not delete `libgcc.a', because recompiling it
4559 is rarely necessary and takes a lot of time.
4563 Makefile. This typically includes everything deleted by
4565 tables, Info files, and so on.
4569 `configure' can be remade using a rule in the Makefile. More
4572 the program. Also, there is no need to delete parent directories
4574 anyway. These are the only exceptions; `maintainer-clean' should
4575 delete everything else that can be rebuilt.
4578 maintainer of the package, not by ordinary users. You may need
4580 maintainer-clean' deletes. Since these files are normally
4582 to reconstruct. If you find you need to unpack the full
4583 distribution again, don't blame us.
4589 @echo 'deletes files that may need special tools to rebuild.'
4592 Update a tags table for this program.
4595 Generate any Info files needed. The best way to write the rules
4598 info: foo.info
4600 foo.info: foo.texi chap1.texi chap2.texi
4601 $(MAKEINFO) $(srcdir)/foo.texi
4603 You must define the variable `MAKEINFO' in the Makefile. It should
4605 distribution.
4608 the Info files are present in the source directory. Therefore,
4610 directory. When users build the package, ordinarily Make will not
4611 update the Info files because they will already be up to date.
4617 Generate documentation files in the given format. These targets
4619 output format cannot be generated. These targets should not be
4621 them.
4625 dvi: foo.dvi
4627 foo.dvi: foo.texi chap1.texi chap2.texi
4628 $(TEXI2DVI) $(srcdir)/foo.texi
4630 You must define the variable `TEXI2DVI' in the Makefile. It
4632 distribution. (`texi2dvi' uses TeX to do the real work of
4633 formatting. TeX is not distributed with Texinfo.) Alternatively,
4635 command.
4639 html: foo.html
4641 foo.html: foo.texi chap1.texi chap2.texi
4642 $(TEXI2HTML) $(srcdir)/foo.texi
4646 is part of the Texinfo distribution).
4649 Create a distribution tar file for this program. The tar file
4652 distribution for. This name can include the version number.
4655 into a subdirectory named `gcc-1.40'.
4659 in it, and then `tar' that subdirectory.
4661 Compress the tar file with `gzip'. For example, the actual
4662 distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
4663 It is ok to support other free compression formats as well.
4667 the distribution. *Note Making Releases: Releases.
4670 Perform self-tests (if any). The user must build the program
4673 built but not installed.
4676 programs in which they are useful.
4679 Perform installation tests (if any). The user must build and
4680 install the program before running the tests. You should not
4681 assume that `$(bindir)' is in the search path.
4686 directories. There is a script called `mkinstalldirs' which is
4687 convenient for this; you can find it in the Gnulib package. You
4690 # Make sure all installation directories (e.g. $(bindir))
4691 # actually exist by making them if necessary.
4699 # Make sure all installation directories (e.g. $(bindir))
4700 # actually exist by making them if necessary.
4708 done. It should do nothing but create installation directories.
4711 File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Con…
4713 7.2.7 Install Command Categories
4718 "post-installation" commands.
4721 modes. They may not alter any files except the ones that come entirely
4722 from the package they belong to.
4726 bases.
4730 normal commands.
4733 `install-info'. This cannot be done with a normal command, since it
4735 solely from the package being installed. It is a post-installation
4737 installs the package's Info files.
4740 the feature just in case it is needed.
4743 categories, insert "category lines" among them. A category line
4744 specifies the category for the commands that follow.
4747 variable, plus an optional comment at the end. There are three
4749 specifies the category. Category lines are no-ops in ordinary execution
4751 _should not_ define them in the makefile).
4756 $(PRE_INSTALL) # Pre-install commands follow.
4757 $(POST_INSTALL) # Post-install commands follow.
4758 $(NORMAL_INSTALL) # Normal commands follow.
4762 line. If you don't use any category lines, all the commands are
4763 classified as normal.
4767 $(PRE_UNINSTALL) # Pre-uninstall commands follow.
4768 $(POST_UNINSTALL) # Post-uninstall commands follow.
4769 $(NORMAL_UNINSTALL) # Normal commands follow.
4772 from the Info directory.
4777 commands with a category line also. This way, you can ensure that each
4779 dependencies actually run.
4791 sake of making binary packages. Typically a binary package contains
4794 installation commands. But installing the binary package does need to
4795 execute the pre-installation and post-installation commands.
4798 pre-installation and post-installation commands. Here is one way of
4806 | gawk -f pre-install.awk
4808 where the file `pre-install.awk' could contain this:
4815 File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
4821 major version and a minor. We have no objection to using more than two
4822 numbers, but it is very unlikely that you really need them.
4825 file with the name `foo-69.96.tar.gz'. It should unpack into a
4826 subdirectory named `foo-69.96'.
4829 files contained in the distribution. This means that all the files
4831 files" and "non-source files". Source files are written by humans and
4833 files by programs under the control of the Makefile.
4835 The distribution should contain a file named `README' which gives
4836 the name of the package, and a general description of what it does. It
4838 subdirectories in the package, if there are any. The `README' file
4840 in the package it can be found.
4842 The `README' file should refer to the file `INSTALL', which should
4843 contain an explanation of the installation procedure.
4845 The `README' file should also refer to the file which contains the
4846 copying conditions. The GNU GPL, if used, should be in a file called
4847 `COPYING'. If the GNU LGPL is used, it should be in a file called
4848 `COPYING.LESSER'.
4850 Naturally, all the source files must be in the distribution. It is
4854 building of the distribution will never modify them. We commonly
4858 want to install.
4861 installing the program should *never* be included in the distribution.
4863 to date when you make a new distribution.
4867 mode 755). We used to recommend that all directories in the
4870 as an unprivileged user. That can easily lead to security issues when
4871 creating the archive, however, so now we recommend against that.
4873 Don't include any symbolic links in the distribution itself. If the
4875 systems that don't support symbolic links. Also, don't use multiple
4877 systems cannot handle this and that prevents unpacking the distribution.
4879 Try to make sure that all the file names will be unique on MS-DOS. A
4881 period and up to three characters. MS-DOS will truncate extra
4882 characters both before and after the period. Thus, `foobarhacker.c'
4883 and `foobarhacker.o' are not ambiguous; they are truncated to
4884 `foobarha.c' and `foobarha.o', which are distinct.
4886 Include in your distribution a copy of the `texinfo.tex' you used to
4887 test print any `*.texinfo' or `*.texi' files.
4891 file. Leaving them out would make the distribution file a little
4893 know what other files to get.
4896 File: standards.info, Node: References, Next: GNU Free Documentation License, Prev: Managing Rel…
4902 use of any non-free program. Proprietary software is a social and
4903 ethical problem, and our aim is to put an end to that problem. We
4907 existence is ethical.
4910 `http://www.gnu.org/philosophy/free-sw.html', and the definition of
4912 `http://www.gnu.org/philosophy/free-doc.html'. The terms "free" and
4913 "non-free", used in this document, refer to those definitions.
4916 `http://www.gnu.org/licenses/license-list.html'. If it is not clear
4918 writing to <licensing@gnu.org>. We will answer, and if the license is
4919 an important one, we will add it to the list.
4923 probably already know about it. For instance, it is fine to explain
4926 program.
4932 program, or that its existence is in any way a good thing. The goal
4936 anything likely to lead them to take an interest in it.
4941 your program. (You cannot hope to find many additional users for your
4943 generally known among people who might want to use your program.)
4946 non-free platform in order to run. For instance, many Java programs
4947 depend on some non-free Java libraries. To recommend or promote such a
4948 program is to promote the other programs it needs. This is why we are
4950 don't want to promote the non-free Java libraries.
4956 software to run.
4958 Some free programs strongly encourage the use of non-free software.
4959 A typical example is `mplayer'. It is free software in itself, and the
4960 free code can handle some kinds of files. However, `mplayer'
4963 with it. To recommend `mplayer' is, in effect, to promote use of the
4964 non-free codecs.
4967 use of non-free software. This is why we do not list `mplayer' in the
4968 Free Software Directory.
4971 for free software. Free documentation that can be included in free
4975 impetus for the community to produce documentation that we can include.
4976 So GNU packages should never recommend non-free documentation.
4980 though they are non-free. This is because we don't include such things
4982 what a software distribution needs to include.
4986 mention by name) web sites that contain such material. This policy is
4987 relevant particularly for the web pages for a GNU package.
4990 non-free software; this is inherent in the nature of the web. So it
4991 makes no sense to criticize a site for having such links. As long as
4994 reasons.
5000 non-free program. However, that a site contains a link to AT&T's web
5002 is not an objection against it.
5005 File: standards.info, Node: GNU Free Documentation License, Next: Index, Prev: References, Up: …
5012 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
5013 `http://fsf.org/'
5016 of this license document, but changing it is not allowed.
5018 0. PREAMBLE
5024 noncommercially. Secondarily, this License preserves for the
5026 being considered responsible for modifications made by others.
5029 works of the document must themselves be free in the same sense.
5031 license designed for free software.
5036 that the software does. But this License is not limited to
5038 of subject matter or whether it is published as a printed book.
5040 instruction or reference.
5042 1. APPLICABILITY AND DEFINITIONS
5046 can be distributed under the terms of this License. Such a notice
5048 to use that work under the conditions stated herein. The
5049 "Document", below, refers to any such manual or work. Any member
5050 of the public is a licensee, and is addressed as "you". You
5052 way requiring permission under copyright law.
5056 modifications and/or translated into another language.
5062 fall directly within that overall subject. (Thus, if the Document
5064 explain any mathematics.) The relationship could be a matter of
5067 regarding them.
5072 License. If a section does not fit the above definition of
5073 Secondary then it is not allowed to be designated as Invariant.
5074 The Document may contain zero Invariant Sections. If the Document
5075 does not identify any Invariant Sections then there are none.
5079 that says that the Document is released under this License. A
5081 be at most 25 words.
5090 formats suitable for input to text formatters. A copy made in an
5093 modification by readers is not Transparent. An image format is
5094 not Transparent if used for any substantial amount of text. A
5095 copy that is not "Transparent" is called "Opaque".
5101 human modification. Examples of transparent image formats include
5102 PNG, XCF and JPG. Opaque formats include proprietary formats that
5106 produced by some word processors for output purposes only.
5110 material this License requires to appear in the title page. For
5113 work's title, preceding the beginning of the body of the text.
5116 of the Document to the public.
5120 following text that translates XYZ in another language. (Here XYZ
5122 "Acknowledgements", "Dedications", "Endorsements", or "History".)
5125 to this definition.
5128 which states that this License applies to the Document. These
5132 has no effect on the meaning of this License.
5134 2. VERBATIM COPYING
5140 add no other conditions whatsoever to those of this License. You
5142 or further copying of the copies you make or distribute. However,
5143 you may accept compensation in exchange for copies. If you
5145 the conditions in section 3.
5148 and you may publicly display copies.
5150 3. COPYING IN QUANTITY
5157 Back-Cover Texts on the back cover. Both covers must also clearly
5158 and legibly identify you as the publisher of these copies. The
5160 title equally prominent and visible. You may add other material
5161 on the covers in addition. Copying with changes limited to the
5164 other respects.
5169 adjacent pages.
5177 copy of the Document, free of added material. If you use the
5183 retailers) of that edition to the public.
5188 version of the Document.
5190 4. MODIFICATIONS
5197 whoever possesses a copy of it. In addition, you must do these
5200 A. Use in the Title Page (and on the covers, if any) a title
5203 in the History section of the Document). You may use the
5205 that version gives permission.
5207 B. List on the Title Page, as authors, one or more persons or
5212 from this requirement.
5214 C. State on the Title page the name of the publisher of the
5215 Modified Version, as the publisher.
5217 D. Preserve all the copyright notices of the Document.
5219 E. Add an appropriate copyright notice for your modifications
5220 adjacent to the other copyright notices.
5222 F. Include, immediately after the copyright notices, a license
5225 the Addendum below.
5227 G. Preserve in that license notice the full lists of Invariant
5229 license notice.
5231 H. Include an unaltered copy of this License.
5233 I. Preserve the section Entitled "History", Preserve its Title,
5236 the Title Page. If there is no section Entitled "History" in
5240 the previous sentence.
5242 J. Preserve the network location, if any, given in the Document
5245 previous versions it was based on. These may be placed in
5246 the "History" section. You may omit a network location for a
5249 it refers to gives permission.
5251 K. For any section Entitled "Acknowledgements" or "Dedications",
5254 acknowledgements and/or dedications given therein.
5256 L. Preserve all the Invariant Sections of the Document,
5257 unaltered in their text and in their titles. Section numbers
5259 titles.
5261 M. Delete any section Entitled "Endorsements". Such a section
5262 may not be included in the Modified Version.
5264 N. Do not retitle any existing section to be Entitled
5266 Section.
5268 O. Preserve any Warranty Disclaimers.
5273 designate some or all of these sections as invariant. To do this,
5275 Version's license notice. These titles must be distinct from any
5276 other section titles.
5282 definition of a standard.
5286 of the list of Cover Texts in the Modified Version. Only one
5288 added by (or through arrangements made by) any one entity. If the
5293 publisher that added the old one.
5297 assert or imply endorsement of any Modified Version.
5299 5. COMBINING DOCUMENTS
5307 their Warranty Disclaimers.
5311 copy. If there are multiple Invariant Sections with the same name
5315 unique number. Make the same adjustment to the section titles in
5317 combined work.
5322 "Acknowledgements", and any sections Entitled "Dedications". You
5323 must delete all sections Entitled "Endorsements."
5325 6. COLLECTIONS OF DOCUMENTS
5332 documents in all other respects.
5338 that document.
5340 7. AGGREGATION WITH INDEPENDENT WORKS
5347 works permit. When the Document is included in an aggregate, this
5349 are not themselves derivative works of the Document.
5356 form. Otherwise they must appear on printed covers that bracket
5357 the whole aggregate.
5359 8. TRANSLATION
5363 4. Replacing Invariant Sections with translations requires special
5366 original versions of these Invariant Sections. You may include a
5370 original versions of those notices and disclaimers. In case of a
5373 prevail.
5378 actual title.
5380 9. TERMINATION
5383 except as expressly provided under this License. Any attempt
5385 and will automatically terminate your rights under this License.
5392 reasonable means prior to 60 days after the cessation.
5399 after your receipt of the notice.
5403 you under this License. If your rights have been terminated and
5405 the same material does not give you any rights to use it.
5407 10. FUTURE REVISIONS OF THIS LICENSE
5410 the GNU Free Documentation License from time to time. Such new
5412 differ in detail to address new problems or concerns. See
5413 `http://www.gnu.org/copyleft/'.
5416 number. If the Document specifies that a particular numbered
5420 published (not as a draft) by the Free Software Foundation. If
5423 Free Software Foundation. If the Document specifies that a proxy
5426 authorizes you to choose that version for the Document.
5428 11. RELICENSING
5432 provides prominent facilities for anybody to edit those works. A
5433 public wiki that anybody can edit is an example of such a server.
5436 site.
5442 published by that same organization.
5445 in part, as part of another Document.
5452 to November 1, 2008.
5456 2009, provided the MMC is eligible for relicensing.
5466 Copyright (C) YEAR YOUR NAME.
5471 Texts. A copy of the license is included in the section entitled ``GNU
5472 Free Documentation License''.
5475 Texts, replace the "with...Texts." line with this:
5479 being LIST.
5483 situation.
5488 permit their use in free software.
5491 File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
5499 * #endif, commenting: Comments. (line 60)
5500 * --help output: --help. (line 6)
5501 * --version output: --version. (line 6)
5502 * -Wall compiler option: Syntactic Conventions.
5504 * accepting contributions: Contributions. (line 6)
5505 * address for bug reports: --help. (line 11)
5506 * ANSI C standard: Standard C. (line 6)
5507 * arbitrary limits on data: Semantics. (line 6)
5508 * ASCII characters: Character Set. (line 6)
5509 * autoconf: System Portability. (line 23)
5510 * avoiding proprietary code: Reading Non-Free Code.
5512 * behavior, dependent on program's name: User Interfaces. (line 6)
5513 * binary packages: Install Command Categories.
5515 * bindir: Directory Variables. (line 57)
5516 * braces, in C source: Formatting. (line 6)
5517 * bug reports: --help. (line 11)
5518 * bug-standards@gnu.org email address: Preface. (line 30)
5519 * C library functions, and portability: System Functions. (line 6)
5520 * canonical name of a program: --version. (line 12)
5521 * casting pointers to integers: CPU Portability. (line 50)
5522 * CGI programs, standard options for: Command-Line Interfaces.
5524 * change logs: Change Logs. (line 6)
5525 * change logs, conditional changes: Conditional Changes. (line 6)
5526 * change logs, style: Style of Change Logs.
5528 * character set: Character Set. (line 6)
5529 * clang: Syntactic Conventions.
5531 * command-line arguments, decoding: Semantics. (line 47)
5532 * command-line interface: Command-Line Interfaces.
5534 * commenting: Comments. (line 6)
5535 * compatibility with C and POSIX standards: Compatibility. (line 6)
5536 * compiler warnings: Syntactic Conventions.
5538 * conditional changes, and change logs: Conditional Changes. (line 6)
5539 * conditionals, comments for: Comments. (line 60)
5540 * configure: Configuration. (line 6)
5541 * control-L: Formatting. (line 128)
5542 * conventions for makefiles: Makefile Conventions.
5544 * CORBA: Graphical Interfaces.
5546 * credits for manuals: Manual Credits. (line 6)
5547 * D-bus: Graphical Interfaces.
5549 * data structures, in Gnulib: System Functions. (line 44)
5550 * data types, and portability: CPU Portability. (line 6)
5551 * DESTDIR: DESTDIR. (line 6)
5552 * directories, creating installation: Directory Variables. (line 20)
5553 * documentation: Documentation. (line 6)
5554 * doschk: Names. (line 38)
5555 * double quote: Quote Characters. (line 6)
5556 * downloading this manual: Preface. (line 14)
5557 * dynamic plug-ins: Dynamic Plug-In Interfaces.
5559 * encodings: Character Set. (line 6)
5560 * enum types, formatting: Formatting. (line 45)
5561 * error messages: Semantics. (line 19)
5562 * error messages, formatting: Errors. (line 6)
5563 * error messages, in Gnulib: System Functions. (line 44)
5564 * exec_prefix: Directory Variables. (line 39)
5565 * expressions, splitting: Formatting. (line 91)
5566 * FDL, GNU Free Documentation License: GNU Free Documentation License.
5568 * file usage: File Usage. (line 6)
5569 * file-name limitations: Names. (line 38)
5570 * formatting error messages: Errors. (line 6)
5571 * formatting source code: Formatting. (line 6)
5572 * formfeed: Formatting. (line 128)
5573 * function argument, declaring: Syntactic Conventions.
5575 * function definitions, formatting: Formatting. (line 6)
5576 * function prototypes: Standard C. (line 17)
5577 * getopt: Command-Line Interfaces.
5579 * gettext: Internationalization.
5581 * GNOME: Graphical Interfaces.
5583 * GNOME and Guile: Source Language. (line 38)
5584 * Gnulib: System Functions. (line 37)
5585 * gnustandards project repository: Preface. (line 30)
5586 * gnustandards-commit@gnu.org mailing list: Preface. (line 24)
5587 * graphical user interface: Graphical Interfaces.
5589 * grave accent: Quote Characters. (line 6)
5590 * GTK+: Graphical Interfaces.
5592 * Guile: Source Language. (line 38)
5593 * implicit int: Syntactic Conventions.
5595 * impossible conditions: Semantics. (line 71)
5596 * installation directories, creating: Directory Variables. (line 20)
5597 * installations, staged: DESTDIR. (line 6)
5598 * interface styles: Graphical Interfaces.
5600 * internationalization: Internationalization.
5602 * keyboard interface: Graphical Interfaces.
5604 * LDAP: OID Allocations. (line 6)
5605 * left quote: Quote Characters. (line 6)
5606 * legal aspects: Legal Issues. (line 6)
5607 * legal papers: Contributions. (line 6)
5608 * libexecdir: Directory Variables. (line 70)
5609 * libiconv: Semantics. (line 11)
5610 * libraries: Libraries. (line 6)
5611 * library functions, and portability: System Functions. (line 6)
5612 * library interface: Graphical Interfaces.
5614 * license for manuals: License for Manuals. (line 6)
5615 * lint: Syntactic Conventions.
5617 * locale-specific quote characters: Quote Characters. (line 6)
5618 * long option names: Option Table. (line 6)
5619 * long-named options: Command-Line Interfaces.
5621 * makefile, conventions for: Makefile Conventions.
5623 * malloc return value: Semantics. (line 26)
5624 * man pages: Man Pages. (line 6)
5625 * manual structure: Manual Structure Details.
5627 * memory allocation failure: Semantics. (line 26)
5628 * memory leak: Memory Usage. (line 23)
5629 * memory usage: Memory Usage. (line 6)
5630 * message text, and internationalization: Internationalization.
5632 * mmap: Mmap. (line 6)
5633 * multiple variables in a line: Syntactic Conventions.
5635 * names of variables, functions, and files: Names. (line 6)
5636 * NEWS file: NEWS File. (line 6)
5637 * non-ASCII characters: Character Set. (line 6)
5638 * non-POSIX systems, and portability: System Portability. (line 32)
5639 * non-standard extensions: Using Extensions. (line 6)
5640 * NUL characters: Semantics. (line 11)
5641 * OID allocations for GNU: OID Allocations. (line 6)
5642 * open brace: Formatting. (line 6)
5643 * opening quote: Quote Characters. (line 6)
5644 * optional features, configure-time: Configuration. (line 100)
5645 * options for compatibility: Compatibility. (line 14)
5646 * options, standard command-line: Command-Line Interfaces.
5648 * output device and program's behavior: User Interfaces. (line 13)
5649 * packaging: Releases. (line 6)
5650 * PATH_INFO, specifying standard options as: Command-Line Interfaces.
5652 * plug-ins: Dynamic Plug-In Interfaces.
5654 * plugin_is_GPL_compatible: Dynamic Plug-In Interfaces.
5656 * portability, and data types: CPU Portability. (line 6)
5657 * portability, and library functions: System Functions. (line 6)
5658 * portability, between system types: System Portability. (line 6)
5659 * POSIX compatibility: Compatibility. (line 6)
5660 * POSIX functions, and portability: System Functions. (line 6)
5661 * POSIXLY_CORRECT, environment variable: Compatibility. (line 21)
5662 * post-installation commands: Install Command Categories.
5664 * pre-installation commands: Install Command Categories.
5666 * prefix: Directory Variables. (line 29)
5667 * program configuration: Configuration. (line 6)
5668 * program design: Design Advice. (line 6)
5669 * program name and its behavior: User Interfaces. (line 6)
5670 * program's canonical name: --version. (line 12)
5671 * programming languages: Source Language. (line 6)
5672 * proprietary programs: Reading Non-Free Code.
5674 * quote characters: Quote Characters. (line 6)
5675 * README file: Releases. (line 21)
5676 * references to non-free material: References. (line 6)
5677 * releasing: Managing Releases. (line 6)
5678 * right quote: Quote Characters. (line 6)
5679 * Savannah repository for gnustandards: Preface. (line 30)
5680 * sbindir: Directory Variables. (line 63)
5681 * signal handling: Semantics. (line 60)
5682 * single quote: Quote Characters. (line 6)
5683 * SNMP: OID Allocations. (line 6)
5684 * spaces before open-paren: Formatting. (line 85)
5685 * staged installs: DESTDIR. (line 6)
5686 * standard command-line options: Command-Line Interfaces.
5688 * standards for makefiles: Makefile Conventions.
5690 * struct types, formatting: Formatting. (line 45)
5691 * syntactic conventions: Syntactic Conventions.
5693 * table of long options: Option Table. (line 6)
5694 * temporary files: Semantics. (line 85)
5695 * temporary variables: Syntactic Conventions.
5697 * texinfo.tex, in a distribution: Releases. (line 72)
5698 * TMPDIR environment variable: Semantics. (line 85)
5699 * trademarks: Trademarks. (line 6)
5700 * user interface styles: Graphical Interfaces.
5702 * valgrind: Memory Usage. (line 23)
5703 * where to obtain standards.texi: Preface. (line 14)
5704 * X.509: OID Allocations. (line 6)
5705 * xmalloc, in Gnulib: System Functions. (line 44)