# HG changeset patch # User Karl Berry # Date 1101753467 0 # Node ID 5fe0551f4ec2c82db54168226341c214a9207e98 # Parent 55a502b8ac3a27fd76c83edeef6f3f84a3486828 update from gnustandards diff --git a/doc/maintain.texi b/doc/maintain.texi --- a/doc/maintain.texi +++ b/doc/maintain.texi @@ -5,7 +5,7 @@ @c For double-sided printing, uncomment: @c @setchapternewpage odd @c This date is automagically updated when you save this file: -@set lastupdate October 4, 2004 +@set lastupdate October 29, 2004 @c %**end of header @dircategory GNU organization @@ -184,7 +184,7 @@ @cindex copyright papers If you maintain an FSF-copyrighted package -certain legal procedures when incorporating legally significant +certain legal procedures are required when incorporating legally significant changes written by other people. This ensures that the FSF has the legal right to distribute the package, and the standing to defend its GPL-covered status in court if necessary. @@ -1160,7 +1160,8 @@ Your designated upload email addresses (@pxref{Automated Upload Registration}) are sent a message if there are any problems processing -an upload for your package. +an upload for your package. You also receive a message when your ++upload has been successfully processed. If you have difficulties processing an upload, email @email{ftp-upload@@gnu.org}. diff --git a/doc/make-stds.texi b/doc/make-stds.texi --- a/doc/make-stds.texi +++ b/doc/make-stds.texi @@ -388,10 +388,10 @@ based on this variable; so are @samp{infodir}, @samp{mandir}, and others. @item datadir -The directory for installing ideosyncratic read-only +The directory for installing idiosyncratic read-only architecture-independent data files for this program. This is usually the same place as @samp{datarootdir}, but we use the two separate -variables so that you can move these ideosyncratic files without +variables so that you can move these idiosyncratic files without altering the location for Info files, man pages, etc. The default definition of @samp{datadir} should be @@ -471,11 +471,34 @@ To tell whether @file{foo.h} came from the Foo package, put a magic string in the file---part of a comment---and @code{grep} for that string. +@item docdir +The directory for installing documentation files (other than Info) for +this package. By default, it should be +@file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as +@file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf, +write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which +may include a version number, prevents collisions among files with +common names, such as @file{README}. + @item infodir The directory for installing the Info files for this package. By default, it should be @file{/usr/local/share/info}, but it should be written as @file{$(datarootdir)/info}. (If you are using Autoconf, -write it as @samp{@@infodir@@}.) +write it as @samp{@@infodir@@}.) @code{infodir} is separate from +@code{docdir} for compatibility with existing practice. + +@item htmldir +@itemx dvidir +@itemx pdfdir +@itemx psdir +Directories for installing documentation files in the particular +format. (It is not required to support documentation in all these +formats.) They should all be set to @code{$(docdir)} by default. (If +you are using Autoconf, write them as @samp{@@htmldir@@}, +@samp{@@dvidir@@}, etc.) Packages which supply several translations +of their documentation should install them in +@samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where +@var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}. @item libdir The directory for object files and libraries of object code. Do not @@ -654,6 +677,24 @@ commands and @dfn{post-installation} commands. @xref{Install Command Categories}. +@item install-html +@itemx install-dvi +@itemx install-pdf +@itemx install-ps +These targets install documentation in formats other than Info; +they're intended to be called explicitly by the person installing the +package, if that format is desired. GNU prefers Info files, so these +must be installed by the @code{install} target. + +When you have many documentation files to install, we recommend that +you avoid collisions and clutter by arranging for these targets to +install in subdirectories of the appropriate installation directory, +such as @code{htmldir}. As one example, if your package has multiple +manuals, and you wish to install HTML documentation with many files +(such as the ``split'' mode output by @code{makeinfo --html}), you'll +certainly want to use subdirectories, or two nodes with the same name +in different manuals will overwrite each other. + @item uninstall Delete all the installed files---the copies that the @samp{install} target creates. @@ -767,8 +808,11 @@ because they will already be up to date. @item dvi -Generate DVI files for all Texinfo documentation. -For example: +@itemx html +@itemx pdf +@itemx ps +Generate documentation files in the given format, if possible. +Here's an example rule for generating DVI files from Texinfo: @smallexample dvi: foo.dvi @@ -784,6 +828,20 @@ of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, write just the dependencies, and allow GNU @code{make} to provide the command. +Here's another example, this one for generating HTML from Texinfo: + +@smallexample +html: foo.html + +foo.html: foo.texi chap1.texi chap2.texi + $(TEXI2HTML) $(srcdir)/foo.texi +@end smallexample + +@noindent +Again, you would define the variable @code{TEXI2HTML} in the Makefile; +for example, it might run @code{makeinfo --no-split --html} +(@command{makeinfo} is part of the Texinfo distribution). + @item dist Create a distribution tar file for this program. The tar file should be set up so that the file names in the tar file start with a subdirectory diff --git a/doc/standards.texi b/doc/standards.texi --- 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 October 1, 2004 +@set lastupdate November 29, 2004 @c %**end of header @dircategory GNU organization @@ -264,7 +264,7 @@ @c A major revision of the C Standard appeared in 1999. @menu -* Source Language:: Which languges to use. +* Source Language:: Which languages to use. * Compatibility:: Compatibility with other implementations * Using Extensions:: Using non-standard features * Standard C:: Using Standard C features @@ -273,7 +273,7 @@ @node Source Language @section Which Languages to Use -@cindex programming languges +@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 @@ -3464,6 +3464,20 @@ is more authoritative. The note should say how to access the Texinfo documentation. +Be sure that man pages include a copyright statement and free +license. The simple all-permissive license is appropriate for simple +man pages: + +@example +Copying and distribution of this file, with or without modification, +are permitted in any medium without royalty provided the copyright +notice and this notice are preserved. +@end example + +For long man pages, with enough explanation and documentation that +they can be considered true manuals, use the GFDL (@pxref{License for +Manuals}). + Finally, the GNU help2man program (@uref{http://www.gnu.org/software/help2man/}) is one way to automate generation of a man page, in this case from @option{--help} output.