changeset 5495:5fe0551f4ec2

update from gnustandards
author Karl Berry <karl@freefriends.org>
date Mon, 29 Nov 2004 18:37:47 +0000
parents 55a502b8ac3a
children f1a56aa674d2
files doc/maintain.texi doc/make-stds.texi doc/standards.texi
diffstat 3 files changed, 84 insertions(+), 11 deletions(-) [+]
line wrap: on
line diff
--- 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}.
--- 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
--- 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.