X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=c86ad42d7aa35cd72d01317970eb8380b9e41a69;hb=0ac90c5a98030c998f3e1db3a0d7f19d4630b6b6;hp=fec548b35dd082a303db787003a81c50b1afba82;hpb=142eb2ee2f26e522b7ab0d8fefb0b3c34201f208;p=gnulib.git diff --git a/doc/standards.texi b/doc/standards.texi index fec548b35..c86ad42d7 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c This date is automagically updated when you save this file: -@set lastupdate February 13, 2013 +@set lastupdate December 17, 2013 @c %**end of header @dircategory GNU organization @@ -291,34 +291,17 @@ account when designing your program. @cindex programming languages When you want to use a language that gets compiled and runs at high -speed, the best language to use is C. Using another language is like -using a non-standard feature: it will cause trouble for users. Even if -GCC supports the other language, users may find it inconvenient to have -to install the compiler for that other language in order to build your -program. For example, if you write your program in C++, people will -have to install the GNU C++ compiler in order to compile your program. - -C has one other advantage over C++ and other compiled languages: more -people know C, so more people will find it easy to read and modify the -program if it is written in C. - -So in general it is much better to use C, rather than the -comparable alternatives. - -But there are two exceptions to that conclusion: - -@itemize @bullet -@item -It is no problem to use another language to write a tool specifically -intended for use with that language. That is because the only people -who want to build the tool will be those who have installed the other -language anyway. - -@item -If an application is of interest only to a narrow part of the community, -then the question of which language it is written in has less effect on -other people, so you may as well please yourself. -@end itemize +speed, the best language to use is C. C++ is ok too, but please don't +make heavy use of templates. So is Java, if you compile it. + +When highest efficiency is not required, other languages commonly used +in the free software community, such as Scheme, Python, Ruby, and +Java, are OK too. Scheme, as implemented by GNU@tie{}Guile, plays a +particular role in the GNU System: it is the preferred language to +extend programs written in C/C++, and also a fine language for a wide +range of applications. The more GNU components use Guile and Scheme, +the more users are able to extend and combine them (@pxref{The Emacs +Thesis,,, guile, GNU Guile Reference Manual}). Many programs are designed to be extensible: they include an interpreter for a language that is higher level than C. Often much of the program @@ -333,8 +316,8 @@ language Scheme (an especially clean and simple dialect of Lisp). Guile also includes bindings for GTK+/GNOME, making it practical to write modern GUI functionality within Guile. We don't reject programs written in other ``scripting languages'' such as Perl and Python, but -using Guile is very important for the overall consistency of the GNU -system. +using Guile is the path that will lead to overall consistency of the +GNU system. @node Compatibility @@ -1075,7 +1058,7 @@ The Apache Software Foundation license, @url{http://www.apache.org/@/licenses}. @item Artistic -The Artistic license used for Perl, @url{http://www.perlfoundation.org/@/legal}. +The Artistic license used for Perl, @url{http://dev.perl.org/licenses/artistic.html}. @item Expat The Expat license, @url{http://www.jclark.com/@/xml/@/copying.txt}. @@ -2306,8 +2289,8 @@ Print the version number. @cindex X.509 The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the -GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP, -X.509 certificates, and so on. The web site +GNU Project (thanks to Sergey Poznyakoff). These are used for SNMP, +LDAP, X.509 certificates, and so on. The web site @url{http://www.alvestrand.no/objectid} has a (voluntary) listing of many OID assignments. @@ -2389,6 +2372,11 @@ when writing GNU software. @section Formatting Your Source Code @cindex formatting source code +@cindex line length +@cindex length of source lines +Please keep the length of source lines to 79 characters or less, for +maximum readability in the widest range of environments. + @cindex open brace @cindex braces, in C source @cindex function definitions, formatting @@ -3257,8 +3245,9 @@ the option @option{--quoting-style} of GNU @code{ls}. @section Mmap @findex mmap -Don't assume that @code{mmap} either works on all files or fails -for all files. It may work on some files and fail on others. +If you use @code{mmap} to read or write files, don't assume it either +works on all files or fails for all files. It may work on some files +and fail on others. The proper way to use @code{mmap} is to try it on the specific file for which you want to use it---and if @code{mmap} doesn't work, fall back on @@ -3373,13 +3362,13 @@ are purely tutorial and cover the basics of the subject. These provide the framework for a beginner to understand the rest of the manual. The Bison manual provides a good example of how to do this. -To serve as a reference, a manual should have an Index that list all the -functions, variables, options, and important concepts that are part of -the program. One combined Index should do for a short manual, but -sometimes for a complex package it is better to use multiple indices. -The Texinfo manual includes advice on preparing good index entries, see -@ref{Index Entries, , Making Index Entries, texinfo, GNU Texinfo}, and -see @ref{Indexing Commands, , Defining the Entries of an +To serve as a reference, a manual should have an Index that lists all +the functions, variables, options, and important concepts that are +part of the program. One combined Index should do for a short manual, +but sometimes for a complex package it is better to use multiple +indices. The Texinfo manual includes advice on preparing good index +entries, see @ref{Index Entries, , Making Index Entries, texinfo, GNU +Texinfo}, and see @ref{Indexing Commands, , Defining the Entries of an Index, texinfo, GNU Texinfo}. Don't use Unix man pages as a model for how to write GNU documentation; @@ -3924,7 +3913,8 @@ corresponding to most of the standard directory variables @example --prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir ---sharedstatedir --localstatedir --libdir --includedir --oldincludedir +--sharedstatedir --localstatedir --runstatedir +--libdir --includedir --oldincludedir --datarootdir --datadir --infodir --localedir --mandir --docdir --htmldir --dvidir --pdfdir --psdir @end example