![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to standards.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / libg++ / etc|
Return to standards.texi CVS log | Up to [Apple XNU] / GNUtools / libg++ / etc |
1.1 ! root 1: \input texinfo @c -*-texinfo-*- ! 2: @c %**start of header ! 3: @setfilename standards.info ! 4: @settitle GNU Coding Standards ! 5: @c %**end of header ! 6: ! 7: @ifinfo ! 8: @format ! 9: START-INFO-DIR-ENTRY ! 10: * Standards:: GNU Project coding standards ! 11: END-INFO-DIR-ENTRY ! 12: @end format ! 13: @end ifinfo ! 14: ! 15: @setchapternewpage off ! 16: ! 17: @ifinfo ! 18: Copyright (C) 1992, 1993 Free Software Foundation ! 19: Permission is granted to make and distribute verbatim copies of ! 20: this manual provided the copyright notice and this permission notice ! 21: are preserved on all copies. ! 22: ! 23: @ignore ! 24: Permission is granted to process this file through TeX and print the ! 25: results, provided the printed document carries copying permission ! 26: notice identical to this one except for the removal of this paragraph ! 27: (this paragraph not being relevant to the printed manual). ! 28: @end ignore ! 29: ! 30: Permission is granted to copy and distribute modified versions of this ! 31: manual under the conditions for verbatim copying, provided that the entire ! 32: resulting derived work is distributed under the terms of a permission ! 33: notice identical to this one. ! 34: ! 35: Permission is granted to copy and distribute translations of this manual ! 36: into another language, under the above conditions for modified versions, ! 37: except that this permission notice may be stated in a translation approved ! 38: by the Free Software Foundation. ! 39: @end ifinfo ! 40: ! 41: @titlepage ! 42: @sp 10 ! 43: @titlefont{GNU Coding Standards} ! 44: @author{Richard Stallman} ! 45: @author{last updated 03 Feb 1993} ! 46: @c Note date also appears below. ! 47: @page ! 48: ! 49: @vskip 0pt plus 1filll ! 50: Copyright @copyright{} 1992, 1993 Free Software Foundation ! 51: ! 52: Permission is granted to make and distribute verbatim copies of ! 53: this manual provided the copyright notice and this permission notice ! 54: are preserved on all copies. ! 55: ! 56: Permission is granted to copy and distribute modified versions of this ! 57: manual under the conditions for verbatim copying, provided that the entire ! 58: resulting derived work is distributed under the terms of a permission ! 59: notice identical to this one. ! 60: ! 61: Permission is granted to copy and distribute translations of this manual ! 62: into another language, under the above conditions for modified versions, ! 63: except that this permission notice may be stated in a translation approved ! 64: by Free Software Foundation. ! 65: @end titlepage ! 66: ! 67: @ifinfo ! 68: @node Top, Reading Non-Free Code, (dir), (dir) ! 69: @top Version ! 70: ! 71: Last updated 03 Feb 1993. ! 72: @c Note date also appears above. ! 73: @end ifinfo ! 74: ! 75: @menu ! 76: * Reading Non-Free Code:: Referring to Proprietary Programs ! 77: * Contributions:: Accepting Contributions ! 78: * Change Logs:: Recording Changes ! 79: * Compatibility:: Compatibility with Other Implementations ! 80: * Makefile Conventions:: Makefile Conventions ! 81: * Configuration:: How Configuration Should Work ! 82: * Source Language:: Using Languages Other Than C ! 83: * Formatting:: Formatting Your Source Code ! 84: * Comments:: Commenting Your Work ! 85: * Syntactic Conventions:: Clean Use of C Constructs ! 86: * Names:: Naming Variables and Functions ! 87: * Using Extensions:: Using Non-standard Features ! 88: * Semantics:: Program Behaviour for All Programs ! 89: * Errors:: Formatting Error Messages ! 90: * Libraries:: Library Behaviour ! 91: * Portability:: Portability As It Applies to GNU ! 92: * User Interfaces:: Standards for Command Line Interfaces ! 93: * Documentation:: Documenting Programs ! 94: * Releases:: Making Releases ! 95: @end menu ! 96: ! 97: @node Reading Non-Free Code ! 98: @chapter Referring to Proprietary Programs ! 99: ! 100: Don't in any circumstances refer to Unix source code for or during ! 101: your work on GNU! (Or to any other proprietary programs.) ! 102: ! 103: If you have a vague recollection of the internals of a Unix program, ! 104: this does not absolutely mean you can't write an imitation of it, but ! 105: do try to organize the imitation internally along different lines, ! 106: because this is likely to make the details of the Unix version ! 107: irrelevant and dissimilar to your results. ! 108: ! 109: For example, Unix utilities were generally optimized to minimize ! 110: memory use; if you go for speed instead, your program will be very ! 111: different. You could keep the entire input file in core and scan it ! 112: there instead of using stdio. Use a smarter algorithm discovered more ! 113: recently than the Unix program. Eliminate use of temporary files. Do ! 114: it in one pass instead of two (we did this in the assembler). ! 115: ! 116: Or, on the contrary, emphasize simplicity instead of speed. For some ! 117: applications, the speed of today's computers makes simpler algorithms ! 118: adequate. ! 119: ! 120: Or go for generality. For example, Unix programs often have static ! 121: tables or fixed-size strings, which make for arbitrary limits; use ! 122: dynamic allocation instead. Make sure your program handles NULs and ! 123: other funny characters in the input files. Add a programming language ! 124: for extensibility and write part of the program in that language. ! 125: ! 126: Or turn some parts of the program into independently usable libraries. ! 127: Or use a simple garbage collector instead of tracking precisely when ! 128: to free memory, or use a new GNU facility such as obstacks. ! 129: ! 130: ! 131: @node Contributions ! 132: @chapter Accepting Contributions ! 133: ! 134: If someone else sends you a piece of code to add to the program you are ! 135: working on, we need legal papers to use it---the same sort of legal ! 136: papers we will need to get from you. @emph{Each} significant ! 137: contributor to a program must sign some sort of legal papers in order ! 138: for us to have clear title to the program. The main author alone is not ! 139: enough. ! 140: ! 141: So, before adding in any contributions from other people, tell us ! 142: so we can arrange to get the papers. Then wait until we tell you ! 143: that we have received the signed papers, before you actually use the ! 144: contribution. ! 145: ! 146: This applies both before you release the program and afterward. If ! 147: you receive diffs to fix a bug, and they make significant change, we ! 148: need legal papers for it. ! 149: ! 150: You don't need papers for changes of a few lines here or there, since ! 151: they are not significant for copyright purposes. Also, you don't need ! 152: papers if all you get from the suggestion is some ideas, not actual code ! 153: which you use. For example, if you write a different solution to the ! 154: problem, you don't need to get papers. ! 155: ! 156: I know this is frustrating; it's frustrating for us as well. But if ! 157: you don't wait, you are going out on a limb---for example, what if the ! 158: contributor's employer won't sign a disclaimer? You might have to take ! 159: that code out again! ! 160: ! 161: The very worst thing is if you forget to tell us about the other ! 162: contributor. We could be very embarrassed in court some day as a ! 163: result. ! 164: ! 165: @node Change Logs ! 166: @chapter Change Logs ! 167: ! 168: Keep a change log for each directory, describing the changes made to ! 169: source files in that directory. The purpose of this is so that people ! 170: investigating bugs in the future will know about the changes that ! 171: might have introduced the bug. Often a new bug can be found by ! 172: looking at what was recently changed. More importantly, change logs ! 173: can help eliminate conceptual inconsistencies between different parts ! 174: of a program; they can give you a history of how the conflicting ! 175: concepts arose. ! 176: ! 177: Use the Emacs command @kbd{M-x add-change} to start a new entry in the ! 178: change log. An entry should have an asterisk, the name of the changed ! 179: file, and then in parentheses the name of the changed functions, ! 180: variables or whatever, followed by a colon. Then describe the changes ! 181: you made to that function or variable. ! 182: ! 183: Separate unrelated entries with blank lines. When two entries ! 184: represent parts of the same change, so that they work together, then ! 185: don't put blank lines between them. Then you can omit the file name ! 186: and the asterisk when successive entries are in the same file. ! 187: ! 188: Here are some examples: ! 189: ! 190: @example ! 191: * register.el (insert-register): Return nil. ! 192: (jump-to-register): Likewise. ! 193: ! 194: * sort.el (sort-subr): Return nil. ! 195: ! 196: * tex-mode.el (tex-bibtex-file, tex-file, tex-region): ! 197: Restart the tex shell if process is gone or stopped. ! 198: (tex-shell-running): New function. ! 199: ! 200: * expr.c (store_one_arg): Round size up for move_block_to_reg. ! 201: (expand_call): Round up when emitting USE insns. ! 202: * stmt.c (assign_parms): Round size up for move_block_from_reg. ! 203: @end example ! 204: ! 205: There's no need to describe here the full purpose of the changes or how ! 206: they work together. It is better to put this explanation in comments in ! 207: the code. That's why just ``New function'' is enough; there is a ! 208: comment with the function in the source to explain what it does. ! 209: ! 210: However, sometimes it is useful to write one line to describe the ! 211: overall purpose of a large batch of changes. ! 212: ! 213: You can think of the change log as a conceptual ``undo list'' which ! 214: explains how earlier versions were different from the current version. ! 215: People can see the current version; they don't need the change log ! 216: to tell them what is in it. What they want from a change log is a ! 217: clear explanation of how the earlier version differed. ! 218: ! 219: When you change the calling sequence of a function in a simple ! 220: fashion, and you change all the callers of the function, there is no ! 221: need to make individual entries for all the callers. Just write in ! 222: the entry for the function being called, ``All callers changed.'' ! 223: ! 224: When you change just comments or doc strings, it is enough to write an ! 225: entry for the file, without mentioning the functions. Write just, ! 226: ``Doc fix.'' There's no need to keep a change log for documentation ! 227: files. This is because documentation is not susceptible to bugs that ! 228: are hard to fix. Documentation does not consist of parts that must ! 229: interact in a precisely engineered fashion; to correct an error, you ! 230: need not know the history of the erroneous passage. ! 231: ! 232: ! 233: @node Compatibility ! 234: @chapter Compatibility with Other Implementations ! 235: ! 236: With certain exceptions, utility programs and libraries for GNU should ! 237: be upward compatible with those in Berkeley Unix, and upward compatible ! 238: with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward ! 239: compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior. ! 240: ! 241: When these standards conflict, it is useful to offer compatibility ! 242: modes for each of them. ! 243: ! 244: @sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel ! 245: free to make the extensions anyway, and include a @samp{--ansi} or ! 246: @samp{--compatible} option to turn them off. However, if the extension ! 247: has a significant chance of breaking any real programs or scripts, ! 248: then it is not really upward compatible. Try to redesign its ! 249: interface. ! 250: ! 251: When a feature is used only by users (not by programs or command ! 252: files), and it is done poorly in Unix, feel free to replace it ! 253: completely with something totally different and better. (For example, ! 254: vi is replaced with Emacs.) But it is nice to offer a compatible ! 255: feature as well. (There is a free vi clone, so we offer it.) ! 256: ! 257: Additional useful features not in Berkeley Unix are welcome. ! 258: Additional programs with no counterpart in Unix may be useful, ! 259: but our first priority is usually to duplicate what Unix already ! 260: has. ! 261: ! 262: @comment The makefile standards are in a separate file that is also ! 263: @comment included by make.texinfo. Done by [email protected] on 1/6/93. ! 264: @include make-stds.texi ! 265: ! 266: @node Configuration ! 267: @chapter How Configuration Should Work ! 268: ! 269: Each GNU distribution should come with a shell script named ! 270: @code{configure}. This script is given arguments which describe the ! 271: kind of machine and system you want to compile the program for. ! 272: ! 273: The @code{configure} script must record the configuration options so ! 274: that they affect compilation. ! 275: ! 276: One way to do this is to make a link from a standard name such as ! 277: @file{config.h} to the proper configuration file for the chosen system. ! 278: If you use this technique, the distribution should @emph{not} contain a ! 279: file named @file{config.h}. This is so that people won't be able to ! 280: build the program without configuring it first. ! 281: ! 282: Another thing that @code{configure} can do is to edit the Makefile. If ! 283: you do this, the distribution should @emph{not} contain a file named ! 284: @file{Makefile}. Instead, include a file @file{Makefile.in} which ! 285: contains the input used for editing. Once again, this is so that people ! 286: won't be able to build the program without configuring it first. ! 287: ! 288: If @code{configure} does write the @file{Makefile}, then @file{Makefile} ! 289: should have a target named @file{Makefile} which causes @code{configure} ! 290: to be rerun, setting up the same configuration that was set up last ! 291: time. The files that @code{configure} reads should be listed as ! 292: dependencies of @file{Makefile}. ! 293: ! 294: All the files which are output from the @code{configure} script should ! 295: have comments at the beginning explaining that they were generated ! 296: automatically using @code{configure}. This is so that users won't think ! 297: of trying to edit them by hand. ! 298: ! 299: The @code{configure} script should write a file named @file{config.status} ! 300: which describes which configuration options were specified when the ! 301: program was last configured. This file should be a shell script which, ! 302: if run, will recreate the same configuration. ! 303: ! 304: The @code{configure} script should accept an option of the form ! 305: @samp{--srcdir=@var{dirname}} to specify the directory where sources are found ! 306: (if it is not the current directory). This makes it possible to build ! 307: the program in a separate directory, so that the actual source directory ! 308: is not modified. ! 309: ! 310: If the user does not specify @samp{--srcdir}, then @code{configure} should ! 311: check both @file{.} and @file{..} to see if it can find the sources. If ! 312: it finds the sources in one of these places, it should use them from ! 313: there. Otherwise, it should report that it cannot find the sources, and ! 314: should exit with nonzero status. ! 315: ! 316: Usually the easy way to support @samp{--srcdir} is by editing a ! 317: definition of @code{VPATH} into the Makefile. Some rules may need to ! 318: refer explicitly to the specified source directory. To make this ! 319: possible, @code{configure} can add to the Makefile a variable named ! 320: @code{srcdir} whose value is precisely the specified directory. ! 321: ! 322: The @code{configure} script should also take an argument which specifies the ! 323: type of system to build the program for. This argument should look like ! 324: this: ! 325: ! 326: @example ! 327: @var{cpu}-@var{company}-@var{system} ! 328: @end example ! 329: ! 330: For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. ! 331: ! 332: The @code{configure} script needs to be able to decode all plausible ! 333: alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} ! 334: would be a valid alias. So would @samp{sun3-bsd4.2}, since SunOS is ! 335: basically @sc{BSD} and no other @sc{BSD} system is used on a Sun. For many ! 336: programs, @samp{vax-dec-ultrix} would be an alias for ! 337: @samp{vax-dec-bsd}, simply because the differences between Ultrix and ! 338: @sc{BSD} are rarely noticeable, but a few programs might need to distinguish ! 339: them. ! 340: ! 341: There is a shell script called @file{config.sub} that you can use ! 342: as a subroutine to validate system types and canonicalize aliases. ! 343: ! 344: Other options are permitted to specify in more detail the software ! 345: or hardware are present on the machine: ! 346: ! 347: @table @samp ! 348: @item --with-@var{package} ! 349: The package @var{package} will be installed, so configure this package ! 350: to work with @var{package}. ! 351: ! 352: Possible values of @var{package} include @samp{x}, @samp{gnu-as} (or ! 353: @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and @samp{gdb}. ! 354: ! 355: @item --nfp ! 356: The target machine has no floating point processor. ! 357: ! 358: @item --gas ! 359: The target machine assembler is GAS, the GNU assembler. ! 360: This is obsolete; use @samp{--with-gnu-as} instead. ! 361: ! 362: @item --x ! 363: The target machine has the X Window System installed. ! 364: This is obsolete; use @samp{--with-x} instead. ! 365: @end table ! 366: ! 367: All @code{configure} scripts should accept all of these ``detail'' ! 368: options, whether or not they make any difference to the particular ! 369: package at hand. In particular, they should accept any option that ! 370: starts with @samp{--with-}. This is so users will be able to configure ! 371: an entire GNU source tree at once with a single set of options. ! 372: ! 373: Packages that perform part of compilation may support cross-compilation. ! 374: In such a case, the host and target machines for the program may be ! 375: different. The @code{configure} script should normally treat the ! 376: specified type of system as both the host and the target, thus producing ! 377: a program which works for the same type of machine that it runs on. ! 378: ! 379: The way to build a cross-compiler, cross-assembler, or what have you, is ! 380: to specify the option @samp{--host=@var{hosttype}} when running ! 381: @code{configure}. This specifies the host system without changing the ! 382: type of target system. The syntax for @var{hosttype} is the same as ! 383: described above. ! 384: ! 385: Programs for which cross-operation is not meaningful need not accept the ! 386: @samp{--host} option, because configuring an entire operating system for ! 387: cross-operation is not a meaningful thing. ! 388: ! 389: Some programs have ways of configuring themselves automatically. If ! 390: your program is set up to do this, your @code{configure} script can simply ! 391: ignore most of its arguments. ! 392: ! 393: ! 394: @node Source Language ! 395: @chapter Using Languages Other Than C ! 396: ! 397: Using a language other than C is like using a non-standard feature: it ! 398: will cause trouble for users. Even if GCC supports the other language, ! 399: users may find it inconvenient to have to install the compiler for that ! 400: other language in order to build your program. So please write in C. ! 401: ! 402: There are three exceptions for this rule: ! 403: ! 404: @itemize @bullet ! 405: @item ! 406: It is okay to use a special language if the same program contains an ! 407: interpreter for that language. ! 408: ! 409: Thus, it is not a problem that GNU Emacs contains code written in Emacs ! 410: Lisp, because it comes with a Lisp interpreter. ! 411: ! 412: @item ! 413: It is okay to use another language in a tool specifically intended for ! 414: use with that language. ! 415: ! 416: This is okay because the only people who want to build the tool will be ! 417: those who have installed the other language anyway. ! 418: ! 419: @item ! 420: If an application is not of extremely widespread interest, then perhaps ! 421: it's not important if the application is inconvenient to install. ! 422: @end itemize ! 423: ! 424: @node Formatting ! 425: @chapter Formatting Your Source Code ! 426: ! 427: It is important to put the open-brace that starts the body of a C ! 428: function in column zero, and avoid putting any other open-brace or ! 429: open-parenthesis or open-bracket in column zero. Several tools look ! 430: for open-braces in column zero to find the beginnings of C functions. ! 431: These tools will not work on code not formatted that way. ! 432: ! 433: It is also important for function definitions to start the name of the ! 434: function in column zero. This helps people to search for function ! 435: definitions, and may also help certain tools recognize them. Thus, ! 436: the proper format is this: ! 437: ! 438: @example ! 439: static char * ! 440: concat (s1, s2) /* Name starts in column zero here */ ! 441: char *s1, *s2; ! 442: @{ /* Open brace in column zero here */ ! 443: @dots{} ! 444: @} ! 445: @end example ! 446: ! 447: @noindent ! 448: or, if you want to use @sc{ANSI} C, format the definition like this: ! 449: ! 450: @example ! 451: static char * ! 452: concat (char *s1, char *s2) ! 453: @{ ! 454: @dots{} ! 455: @} ! 456: @end example ! 457: ! 458: In @sc{ANSI} C, if the arguments don't fit nicely on one line, ! 459: split it like this: ! 460: ! 461: @example ! 462: int ! 463: lots_of_args (int an_integer, long a_long, short a_short, ! 464: double a_double, float a_float) ! 465: @dots{} ! 466: @end example ! 467: ! 468: For the body of the function, we prefer code formatted like this: ! 469: ! 470: @example ! 471: if (x < foo (y, z)) ! 472: haha = bar[4] + 5; ! 473: else ! 474: @{ ! 475: while (z) ! 476: @{ ! 477: haha += foo (z, z); ! 478: z--; ! 479: @} ! 480: return ++x + bar (); ! 481: @} ! 482: @end example ! 483: ! 484: We find it easier to read a program when it has spaces before the ! 485: open-parentheses and after the commas. Especially after the commas. ! 486: ! 487: When you split an expression into multiple lines, split it ! 488: before an operator, not after one. Here is the right way: ! 489: ! 490: @example ! 491: if (foo_this_is_long && bar > win (x, y, z) ! 492: && remaining_condition) ! 493: @end example ! 494: ! 495: Try to avoid having two operators of different precedence at the same ! 496: level of indentation. For example, don't write this: ! 497: ! 498: @example ! 499: mode = (inmode[j] == VOIDmode ! 500: || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) ! 501: ? outmode[j] : inmode[j]); ! 502: @end example ! 503: ! 504: Instead, use extra parentheses so that the indentation shows the nesting: ! 505: ! 506: @example ! 507: mode = ((inmode[j] == VOIDmode ! 508: || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) ! 509: ? outmode[j] : inmode[j]); ! 510: @end example ! 511: ! 512: Insert extra parentheses so that Emacs will indent the code properly. ! 513: For example, the following indentation looks nice if you do it by hand, ! 514: but Emacs would mess it up: ! 515: ! 516: @example ! 517: v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 ! 518: + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; ! 519: @end example ! 520: ! 521: But adding a set of parentheses solves the problem: ! 522: ! 523: @example ! 524: v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 ! 525: + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); ! 526: @end example ! 527: ! 528: Format do-while statements like this: ! 529: ! 530: @example ! 531: do ! 532: @{ ! 533: a = foo (a); ! 534: @} ! 535: while (a > 0); ! 536: @end example ! 537: ! 538: Please use formfeed characters (control-L) to divide the program into ! 539: pages at logical places (but not within a function). It does not matter ! 540: just how long the pages are, since they do not have to fit on a printed ! 541: page. The formfeeds should appear alone on lines by themselves. ! 542: ! 543: ! 544: @node Comments ! 545: @chapter Commenting Your Work ! 546: ! 547: Every program should start with a comment saying briefly what it is for. ! 548: Example: @samp{fmt - filter for simple filling of text}. ! 549: ! 550: Please put a comment on each function saying what the function does, ! 551: what sorts of arguments it gets, and what the possible values of ! 552: arguments mean and are used for. It is not necessary to duplicate in ! 553: words the meaning of the C argument declarations, if a C type is being ! 554: used in its customary fashion. If there is anything nonstandard about ! 555: its use (such as an argument of type @code{char *} which is really the ! 556: address of the second character of a string, not the first), or any ! 557: possible values that would not work the way one would expect (such as, ! 558: that strings containing newlines are not guaranteed to work), be sure ! 559: to say so. ! 560: ! 561: Also explain the significance of the return value, if there is one. ! 562: ! 563: Please put two spaces after the end of a sentence in your comments, so ! 564: that the Emacs sentence commands will work. Also, please write ! 565: complete sentences and capitalize the first word. If a lower-case ! 566: identifer comes at the beginning of a sentence, don't capitalize it! ! 567: Changing the spelling makes it a different identifier. If you don't ! 568: like starting a sentence with a lower case letter, write the sentence ! 569: differently (e.g. ``The identifier lower-case is @dots{}''). ! 570: ! 571: The comment on a function is much clearer if you use the argument ! 572: names to speak about the argument values. The variable name itself ! 573: should be lower case, but write it in upper case when you are speaking ! 574: about the value rather than the variable itself. Thus, ``the inode ! 575: number @var{node_num}'' rather than ``an inode''. ! 576: ! 577: There is usually no purpose in restating the name of the function in ! 578: the comment before it, because the reader can see that for himself. ! 579: There might be an exception when the comment is so long that the function ! 580: itself would be off the bottom of the screen. ! 581: ! 582: There should be a comment on each static variable as well, like this: ! 583: ! 584: @example ! 585: /* Nonzero means truncate lines in the display; ! 586: zero means continue them. */ ! 587: ! 588: int truncate_lines; ! 589: @end example ! 590: ! 591: Every @samp{#endif} should have a comment, except in the case of short ! 592: conditionals (just a few lines) that are not nested. The comment should ! 593: state the condition of the conditional that is ending, @emph{including ! 594: its sense}. @samp{#else} should have a comment describing the condition ! 595: @emph{and sense} of the code that follows. For example: ! 596: ! 597: @example ! 598: #ifdef foo ! 599: @dots{} ! 600: #else /* not foo */ ! 601: @dots{} ! 602: #endif /* not foo */ ! 603: @end example ! 604: ! 605: @noindent ! 606: but, by contrast, write the comments this way for a @samp{#ifndef}: ! 607: ! 608: @example ! 609: #ifndef foo ! 610: @dots{} ! 611: #else /* foo */ ! 612: @dots{} ! 613: #endif /* foo */ ! 614: @end example ! 615: ! 616: ! 617: @node Syntactic Conventions ! 618: @chapter Clean Use of C Constructs ! 619: ! 620: Please explicitly declare all arguments to functions. ! 621: Don't omit them just because they are ints. ! 622: ! 623: Declarations of external functions and functions to appear later ! 624: in the source file should all go in one place near the beginning of ! 625: the file (somewhere before the first function definition in the file), ! 626: or else should go in a header file. Don't put extern declarations ! 627: inside functions. ! 628: ! 629: It used to be common practice to use the same local variables (with ! 630: names like @code{tem}) over and over for different values within one ! 631: function. Instead of doing this, it is better declare a separate local ! 632: variable for each distinct purpose, and give it a name which is ! 633: meaningful. This not only makes programs easier to understand, it also ! 634: facilitates optimization by good compilers. You can also move the ! 635: declaration of each local variable into the smallest scope that includes ! 636: all its uses. This makes the program even cleaner. ! 637: ! 638: Don't use local variables or parameters that shadow global identifiers. ! 639: ! 640: Don't declare multiple variables in one declaration that spans lines. ! 641: Start a new declaration on each line, instead. For example, instead ! 642: of this: ! 643: ! 644: @example ! 645: int foo, ! 646: bar; ! 647: @end example ! 648: ! 649: @noindent ! 650: write either this: ! 651: ! 652: @example ! 653: int foo, bar; ! 654: @end example ! 655: ! 656: @noindent ! 657: or this: ! 658: ! 659: @example ! 660: int foo; ! 661: int bar; ! 662: @end example ! 663: ! 664: @noindent ! 665: (If they are global variables, each should have a comment preceding it ! 666: anyway.) ! 667: ! 668: When you have an if-else statement nested in another if statement, ! 669: always put braces around the if-else. Thus, never write like this: ! 670: ! 671: @example ! 672: if (foo) ! 673: if (bar) ! 674: win (); ! 675: else ! 676: lose (); ! 677: @end example ! 678: ! 679: @noindent ! 680: always like this: ! 681: ! 682: @example ! 683: if (foo) ! 684: @{ ! 685: if (bar) ! 686: win (); ! 687: else ! 688: lose (); ! 689: @} ! 690: @end example ! 691: ! 692: If you have an if statement nested inside of an else statement, ! 693: either write @code{else if} on one line, like this, ! 694: ! 695: @example ! 696: if (foo) ! 697: @dots{} ! 698: else if (bar) ! 699: @dots{} ! 700: @end example ! 701: ! 702: @noindent ! 703: with its then-part indented like the preceding then-part, or write the ! 704: nested if within braces like this: ! 705: ! 706: @example ! 707: if (foo) ! 708: @dots{} ! 709: else ! 710: @{ ! 711: if (bar) ! 712: @dots{} ! 713: @} ! 714: @end example ! 715: ! 716: Don't declare both a structure tag and variables or typedefs in the ! 717: same declaration. Instead, declare the structure tag separately ! 718: and then use it to declare the variables or typedefs. ! 719: ! 720: Try to avoid assignments inside if-conditions. For example, don't ! 721: write this: ! 722: ! 723: @example ! 724: if ((foo = (char *) malloc (sizeof *foo)) == 0) ! 725: fatal ("virtual memory exhausted"); ! 726: @end example ! 727: ! 728: @noindent ! 729: instead, write this: ! 730: ! 731: @example ! 732: foo = (char *) malloc (sizeof *foo); ! 733: if (foo == 0) ! 734: fatal ("virtual memory exhausted"); ! 735: @end example ! 736: ! 737: Don't make the program ugly to placate lint. Please don't insert any ! 738: casts to void. Zero without a cast is perfectly fine as a null ! 739: pointer constant. ! 740: ! 741: ! 742: @node Names ! 743: @chapter Naming Variables and Functions ! 744: ! 745: Please use underscores to separate words in a name, so that the Emacs ! 746: word commands can be useful within them. Stick to lower case; reserve ! 747: upper case for macros and enum constants, and for name-prefixes that ! 748: follow a uniform convention. ! 749: ! 750: For example, you should use names like @code{ignore_space_change_flag}; ! 751: don't use names like @code{iCantReadThis}. ! 752: ! 753: Variables that indicate whether command-line options have been ! 754: specified should be named after the meaning of the option, not after ! 755: the option-letter. A comment should state both the exact meaning of ! 756: the option and its letter. For example, ! 757: ! 758: @example ! 759: /* Ignore changes in horizontal whitespace (-b). */ ! 760: int ignore_space_change_flag; ! 761: @end example ! 762: ! 763: When you want to define names with constant integer values, use ! 764: @code{enum} rather than @samp{#define}. GDB knows about enumeration ! 765: constants. ! 766: ! 767: Use file names of 14 characters or less, to avoid creating gratuitous ! 768: problems on System V. ! 769: ! 770: ! 771: @node Using Extensions ! 772: @chapter Using Non-standard Features ! 773: ! 774: Many GNU facilities that already exist support a number of convenient ! 775: extensions over the comparable Unix facilities. Whether to use these ! 776: extensions in implementing your program is a difficult question. ! 777: ! 778: On the one hand, using the extensions can make a cleaner program. ! 779: On the other hand, people will not be able to build the program ! 780: unless the other GNU tools are available. This might cause the ! 781: program to work on fewer kinds of machines. ! 782: ! 783: With some extensions, it might be easy to provide both alternatives. ! 784: For example, you can define functions with a ``keyword'' @code{INLINE} ! 785: and define that as a macro to expand into either @code{inline} or ! 786: nothing, depending on the compiler. ! 787: ! 788: In general, perhaps it is best not to use the extensions if you can ! 789: straightforwardly do without them, but to use the extensions if they ! 790: are a big improvement. ! 791: ! 792: An exception to this rule are the large, established programs (such as ! 793: Emacs) which run on a great variety of systems. Such programs would ! 794: be broken by use of GNU extensions. ! 795: ! 796: Another exception is for programs that are used as part of ! 797: compilation: anything that must be compiled with other compilers in ! 798: order to bootstrap the GNU compilation facilities. If these require ! 799: the GNU compiler, then no one can compile them without having them ! 800: installed already. That would be no good. ! 801: ! 802: Since most computer systems do not yet implement @sc{ANSI} C, using the ! 803: @sc{ANSI} C features is effectively using a GNU extension, so the ! 804: same considerations apply. (Except for @sc{ANSI} features that we ! 805: discourage, such as trigraphs---don't ever use them.) ! 806: ! 807: @node Semantics ! 808: @chapter Program Behaviour for All Programs ! 809: ! 810: Avoid arbitrary limits on the length or number of @emph{any} data ! 811: structure, including filenames, lines, files, and symbols, by allocating ! 812: all data structures dynamically. In most Unix utilities, ``long lines ! 813: are silently truncated''. This is not acceptable in a GNU utility. ! 814: ! 815: Utilities reading files should not drop NUL characters, or any other ! 816: nonprinting characters @emph{including those with codes above 0177}. The ! 817: only sensible exceptions would be utilities specifically intended for ! 818: interface to certain types of printers that can't handle those characters. ! 819: ! 820: Check every system call for an error return, unless you know you wish to ! 821: ignore errors. Include the system error text (from @code{perror} or ! 822: equivalent) in @emph{every} error message resulting from a failing ! 823: system call, as well as the name of the file if any and the name of the ! 824: utility. Just ``cannot open foo.c'' or ``stat failed'' is not ! 825: sufficient. ! 826: ! 827: Check every call to @code{malloc} or @code{realloc} to see if it ! 828: returned zero. Check @code{realloc} even if you are making the block ! 829: smaller; in a system that rounds block sizes to a power of 2, ! 830: @code{realloc} may get a different block if you ask for less space. ! 831: ! 832: In Unix, @code{realloc} can destroy the storage block if it returns ! 833: zero. GNU @code{realloc} does not have this bug: if it fails, the ! 834: original block is unchanged. Feel free to assume the bug is fixed. If ! 835: you wish to run your program on Unix, and wish to avoid lossage in this ! 836: case, you can use the GNU @code{malloc}. ! 837: ! 838: You must expect @code{free} to alter the contents of the block that was ! 839: freed. Anything you want to fetch from the block, you must fetch before ! 840: calling @code{free}. ! 841: ! 842: Use @code{getopt_long} to decode arguments, unless the argument syntax ! 843: makes this unreasonable. ! 844: ! 845: When static storage is to be written in during program execution, use ! 846: explicit C code to initialize it. Reserve C initialized declarations ! 847: for data that will not be changed. ! 848: ! 849: Try to avoid low-level interfaces to obscure Unix data structures (such ! 850: as file directories, utmp, or the layout of kernel memory), since these ! 851: are less likely to work compatibly. If you need to find all the files ! 852: in a directory, use @code{readdir} or some other high-level interface. ! 853: These will be supported compatibly by GNU. ! 854: ! 855: By default, the GNU system will provide the signal handling functions of ! 856: @sc{BSD} and of @sc{POSIX}. So GNU software should be written to use ! 857: these. ! 858: ! 859: In error checks that detect ``impossible'' conditions, just abort. ! 860: There is usually no point in printing any message. These checks ! 861: indicate the existence of bugs. Whoever wants to fix the bugs will have ! 862: to read the source code and run a debugger. So explain the problem with ! 863: comments in the source. The relevant data will be in variables, which ! 864: are easy to examine with the debugger, so there is no point moving them ! 865: elsewhere. ! 866: ! 867: ! 868: @node Errors ! 869: @chapter Formatting Error Messages ! 870: ! 871: Error messages from compilers should look like this: ! 872: ! 873: @example ! 874: @var{source-file-name}:@var{lineno}: @var{message} ! 875: @end example ! 876: ! 877: Error messages from other noninteractive programs should look like this: ! 878: ! 879: @example ! 880: @var{program}:@var{source-file-name}:@var{lineno}: @var{message} ! 881: @end example ! 882: ! 883: @noindent ! 884: when there is an appropriate source file, or like this: ! 885: ! 886: @example ! 887: @var{program}: @var{message} ! 888: @end example ! 889: ! 890: @noindent ! 891: when there is no relevant source file. ! 892: ! 893: In an interactive program (one that is reading commands from a ! 894: terminal), it is better not to include the program name in an error ! 895: message. The place to indicate which program is running is in the ! 896: prompt or with the screen layout. (When the same program runs with ! 897: input from a source other than a terminal, it is not interactive and ! 898: would do best to print error messages using the noninteractive style.) ! 899: ! 900: The string @var{message} should not begin with a capital letter when ! 901: it follows a program name and/or filename. Also, it should not end ! 902: with a period. ! 903: ! 904: Error messages from interactive programs, and other messages such as ! 905: usage messages, should start with a capital letter. But they should not ! 906: end with a period. ! 907: ! 908: ! 909: @node Libraries ! 910: @chapter Library Behaviour ! 911: ! 912: Try to make library functions reentrant. If they need to do dynamic ! 913: storage allocation, at least try to avoid any nonreentrancy aside from ! 914: that of @code{malloc} itself. ! 915: ! 916: Here are certain name conventions for libraries, to avoid name ! 917: conflicts. ! 918: ! 919: Choose a name prefix for the library, more than two characters long. ! 920: All external function and variable names should start with this ! 921: prefix. In addition, there should only be one of these in any given ! 922: library member. This usually means putting each one in a separate ! 923: source file. ! 924: ! 925: An exception can be made when two external symbols are always used ! 926: together, so that no reasonable program could use one without the ! 927: other; then they can both go in the same file. ! 928: ! 929: External symbols that are not documented entry points for the user ! 930: should have names beginning with @samp{_}. They should also contain ! 931: the chosen name prefix for the library, to prevent collisions with ! 932: other libraries. These can go in the same files with user entry ! 933: points if you like. ! 934: ! 935: Static functions and variables can be used as you like and need not ! 936: fit any naming convention. ! 937: ! 938: ! 939: @node Portability ! 940: @chapter Portability As It Applies to GNU ! 941: ! 942: Much of what is called ``portability'' in the Unix world refers to ! 943: porting to different Unix versions. This is a secondary consideration ! 944: for GNU software, because its primary purpose is to run on top of one ! 945: and only one kernel, the GNU kernel, compiled with one and only one C ! 946: compiler, the GNU C compiler. The amount and kinds of variation among ! 947: GNU systems on different cpu's will be like the variation among Berkeley ! 948: 4.3 systems on different cpu's. ! 949: ! 950: All users today run GNU software on non-GNU systems. So supporting a ! 951: variety of non-GNU systems is desirable; simply not paramount. ! 952: The easiest way to achieve portability to a reasonable range of systems ! 953: is to use Autoconf. It's unlikely that your program needs to know more ! 954: information about the host machine than Autoconf can provide, simply ! 955: because most of the programs that need such knowledge have already been ! 956: written. ! 957: ! 958: It is difficult to be sure exactly what facilities the GNU kernel ! 959: will provide, since it isn't finished yet. Therefore, assume you can ! 960: use anything in 4.3; just avoid using the format of semi-internal data ! 961: bases (e.g., directories) when there is a higher-level alternative ! 962: (readdir). ! 963: ! 964: You can freely assume any reasonably standard facilities in the C ! 965: language, libraries or kernel, because we will find it necessary to ! 966: support these facilities in the full GNU system, whether or not we ! 967: have already done so. The fact that there may exist kernels or C ! 968: compilers that lack these facilities is irrelevant as long as the GNU ! 969: kernel and C compiler support them. ! 970: ! 971: It remains necessary to worry about differences among cpu types, such ! 972: as the difference in byte ordering and alignment restrictions. It's ! 973: unlikely that 16-bit machines will ever be supported by GNU, so there ! 974: is no point in spending any time to consider the possibility that an ! 975: int will be less than 32 bits. ! 976: ! 977: You can assume that all pointers have the same format, regardless ! 978: of the type they point to, and that this is really an integer. ! 979: There are some weird machines where this isn't true, but they aren't ! 980: important; don't waste time catering to them. Besides, eventually ! 981: we will put function prototypes into all GNU programs, and that will ! 982: probably make your program work even on weird machines. ! 983: ! 984: Since some important machines (including the 68000) are big-endian, ! 985: it is important not to assume that the address of an int object ! 986: is also the address of its least-significant byte. Thus, don't ! 987: make the following mistake: ! 988: ! 989: @example ! 990: int c; ! 991: @dots{} ! 992: while ((c = getchar()) != EOF) ! 993: write(file_descriptor, &c, 1); ! 994: @end example ! 995: ! 996: You can assume that it is reasonable to use a meg of memory. Don't ! 997: strain to reduce memory usage unless it can get to that level. If ! 998: your program creates complicated data structures, just make them in ! 999: core and give a fatal error if malloc returns zero. ! 1000: ! 1001: If a program works by lines and could be applied to arbitrary ! 1002: user-supplied input files, it should keep only a line in memory, because ! 1003: this is not very hard and users will want to be able to operate on input ! 1004: files that are bigger than will fit in core all at once. ! 1005: ! 1006: ! 1007: @node User Interfaces ! 1008: @chapter Standards for Command Line Interfaces ! 1009: ! 1010: Please don't make the behavior of a utility depend on the name used ! 1011: to invoke it. It is useful sometimes to make a link to a utility ! 1012: with a different name, and that should not change what it does. ! 1013: ! 1014: Instead, use a run time option or a compilation switch or both ! 1015: to select among the alternate behaviors. ! 1016: ! 1017: Likewise, please don't make the behavior of the program depend on the ! 1018: type of output device it is used with. Device independence is an ! 1019: important principle of the system's design; do not compromise it ! 1020: merely to save someone from typing an option now and then. ! 1021: ! 1022: If you think one behavior is most useful when the output is to a ! 1023: terminal, and another is most useful when the output is a file or a ! 1024: pipe, then it is usually best to make the default behavior the one that ! 1025: is useful with output to a terminal, and have an option for the other ! 1026: behavior. ! 1027: ! 1028: Compatibility requires certain programs to depend on the type of output ! 1029: device. It would be disastrous if @code{ls} or @code{sh} did not do so ! 1030: in the way all users expect. In some of these cases, we supplement the ! 1031: program with a preferred alternate version that does not depend on the ! 1032: output device type. For example, we provide a @code{dir} program much ! 1033: like @code{ls} except that its default output format is always ! 1034: multi-column format. ! 1035: ! 1036: It is a good idea to follow the @sc{POSIX} guidelines for the ! 1037: command-line options of a program. The easiest way to do this is to use ! 1038: @code{getopt} to parse them. Note that the GNU version of @code{getopt} ! 1039: will normally permit options anywhere among the arguments unless the ! 1040: special argument @samp{--} is used. This is not what @sc{POSIX} ! 1041: specifies; it is a GNU extension. ! 1042: ! 1043: Please define long-named options that are equivalent to the ! 1044: single-letter Unix-style options. We hope to make GNU more user ! 1045: friendly this way. This is easy to do with the GNU function ! 1046: @code{getopt_long}. ! 1047: ! 1048: One of the advantages of long-named options is that they can be ! 1049: consistent from program to program. For example, users should be able ! 1050: to expect the ``verbose'' option of any GNU program which has one, to be ! 1051: spelled precisely @samp{--verbose}. To achieve this uniformity, look at ! 1052: the table of common long-option names when you choose the option names ! 1053: for your program. The table is in the file @file{longopts.table}. ! 1054: ! 1055: If you use names not already in the table, please send ! 1056: @samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we ! 1057: can update the table. ! 1058: ! 1059: It is usually a good idea for file names given as ordinary arguments ! 1060: to be input files only; any output files would be specified using ! 1061: options (preferably @samp{-o}). Even if you allow an output file name ! 1062: as an ordinary argument for compatibility, try to provide a suitable ! 1063: option as well. This will lead to more consistency among GNU ! 1064: utilities, so that there are fewer idiosyncracies for users to ! 1065: remember. ! 1066: ! 1067: Programs should support an option @samp{--version} which prints the ! 1068: program's version number on standard output and exits successfully, and ! 1069: an option @samp{--help} which prints option usage information on ! 1070: standard output and exits successfully. These options should inhibit ! 1071: the normal function of the command; they should do nothing except print ! 1072: the requested information. ! 1073: ! 1074: @node Documentation ! 1075: @chapter Documenting Programs ! 1076: ! 1077: Please use Texinfo for documenting GNU programs. See the Texinfo ! 1078: manual, either the hardcopy or the version in the GNU Emacs Info ! 1079: subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g. those ! 1080: under the @file{man/} directory in the GNU Emacs Distribution) for ! 1081: examples. ! 1082: ! 1083: The title page of the manual should state the version of the program ! 1084: which the manual applies to. The Top node of the manual should also ! 1085: contain this information. If the manual is changing more frequently ! 1086: than or independent of the program, also state a version number for ! 1087: the manual in both of these places. ! 1088: ! 1089: The manual should document all command-line arguments and all ! 1090: commands. It should give examples of their use. But don't organize ! 1091: the manual as a list of features. Instead, organize it by the ! 1092: concepts a user will have before reaching that point in the manual. ! 1093: Address the goals that a user will have in mind, and explain how to ! 1094: accomplish them. Don't use Unix man pages as a model for how to ! 1095: write GNU documentation; they are a bad example to follow. ! 1096: ! 1097: The manual should have a node named @samp{@var{program} Invocation}, ! 1098: @samp{@var{program} Invoke} or @samp{Invoking @var{program}}, where ! 1099: @var{program} stands for the name of the program being described, as you ! 1100: would type it in the shell to run the program. This node (together with ! 1101: its subnodes if any) should describe the program's command line ! 1102: arguments and how to run it (the sort of information people would look ! 1103: in a man page for). Start with an @samp{@@example} containing a ! 1104: template for all the options and arguments that the program uses. ! 1105: ! 1106: Alternatively, put a menu item in some menu whose item name fits one of ! 1107: the above patterns. This identifies the node which that item points to ! 1108: as the node for this purpose, regardless of the node's actual name. ! 1109: ! 1110: There will be automatic features for specifying a program name and ! 1111: quickly reading just this part of its manual. ! 1112: ! 1113: If one manual describes several programs, it should have such a node for ! 1114: each program described. ! 1115: ! 1116: In addition to its manual, the package should have a file named ! 1117: @file{NEWS} which contains a list of user-visible changes worth ! 1118: mentioning. In each new release, add items to the front of the file and ! 1119: identify the version they pertain to. Don't discard old items; leave ! 1120: them in the file after the newer items. This way, a user upgrading from ! 1121: any previous version can see what is new. ! 1122: ! 1123: If the @file{NEWS} file gets very long, move some of the older items ! 1124: into a file named @file{ONEWS} and put a note at the end referring the ! 1125: user to that file. ! 1126: ! 1127: It is ok to supply a man page for the program as well as a Texinfo ! 1128: manual if you wish to. But keep in mind that supporting a man page ! 1129: requires continual effort, each time the program is changed. Any time ! 1130: you spend on the man page is time taken away from more useful things you ! 1131: could contribute. ! 1132: ! 1133: Thus, even if a user volunteers to donate a man page, you may find this ! 1134: gift costly to accept. Unless you have time on your hands, it may be ! 1135: better to refuse the man page unless the same volunteer agrees to take ! 1136: full responsibility for maintaining it---so that you can wash your hands ! 1137: of it entirely. If the volunteer ceases to do the job, then don't feel ! 1138: obliged to pick it up yourself; it may be better to withdraw the man ! 1139: page until another volunteer offers to carry on with it. ! 1140: ! 1141: Alternatively, if you expect the discrepancies to be small enough that ! 1142: the man page remains useful, put a prominent note near the beginning of ! 1143: the man page explaining that you don't maintain it and that the Texinfo ! 1144: manual is more authoritative, and describing how to access the Texinfo ! 1145: documentation. ! 1146: ! 1147: @node Releases ! 1148: @chapter Making Releases ! 1149: ! 1150: Package the distribution of Foo version 69.96 in a tar file named ! 1151: @file{foo-69.96.tar}. It should unpack into a subdirectory named ! 1152: @file{foo-69.96}. ! 1153: ! 1154: Building and installing the program should never modify any of the files ! 1155: contained in the distribution. This means that all the files that form ! 1156: part of the program in any way must be classified into @dfn{source ! 1157: files} and @dfn{non-source files}. Source files are written by humans ! 1158: and never changed automatically; non-source files are produced from ! 1159: source files by programs under the control of the Makefile. ! 1160: ! 1161: Naturally, all the source files must be in the distribution. It is okay ! 1162: to include non-source files in the distribution, provided they are ! 1163: up-to-date and machine-independent, so that building the distribution ! 1164: normally will never modify them. We commonly included non-source files ! 1165: produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid ! 1166: unnecessary dependencies between our distributions, so that users can ! 1167: install whichever packages they want to install. ! 1168: ! 1169: Non-source files that might actually be modified by building and ! 1170: installing the program should @strong{never} be included in the ! 1171: distribution. So if you do distribute non-source files, always make ! 1172: sure they are up to date when you make a new distribution. ! 1173: ! 1174: Make sure that the directory into which the distribution unpacks (as ! 1175: well as any subdirectories) are all world-writable (octal mode 777). ! 1176: This is so that old versions of @code{tar} which preserve the ! 1177: ownership and permissions of the files from the tar archive will be ! 1178: able to extract all the files even if the user is unprivileged. ! 1179: ! 1180: Make sure that no file name in the distribution is more than 14 ! 1181: characters long. Likewise, no file created by building the program ! 1182: should have a name longer than 14 characters. The reason for this is ! 1183: that some systems adhere to a foolish interpretation of the POSIX ! 1184: standard, and refuse to open a longer name, rather than truncating as ! 1185: they did in the past. ! 1186: ! 1187: Don't include any symbolic links in the distribution itself. If the tar ! 1188: file contains symbolic links, then people cannot even unpack it on ! 1189: systems that don't support symbolic links. Also, don't use multiple ! 1190: names for one file in different directories, because certain file ! 1191: systems cannot handle this and that prevents unpacking the ! 1192: distribution. ! 1193: ! 1194: Try to make sure that all the file names will be unique on MS-DOG. A ! 1195: name on MS-DOG consists of up to 8 characters, optionally followed by a ! 1196: period and up to three characters. MS-DOG will truncate extra ! 1197: characters both before and after the period. Thus, ! 1198: @file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they ! 1199: are truncated to @file{foobarha.c} and @file{foobarha.o}, which are ! 1200: distinct. ! 1201: ! 1202: Include in your distribution a copy of the @file{texinfo.tex} you used ! 1203: to test print any @file{*.texinfo} files. ! 1204: ! 1205: Likewise, if your program uses small GNU software packages like regex, ! 1206: getopt, obstack, or termcap, include them in the distribution file. ! 1207: Leaving them out would make the distribution file a little smaller at ! 1208: the expense of possible inconvenience to a user who doesn't know what ! 1209: other files to get. ! 1210: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.