Regenerated for Unicode 5.1.0.

[gnulib.git] / doc / maintain.texi

diff --git a/doc/maintain.texi b/doc/maintain.texi
index 0db3d35..c04722c 100644 (file)
--- 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:
 @c For double-sided printing, uncomment:
 @c @setchapternewpage odd
 @c This date is automagically updated when you save this file:

-@set lastupdate November 8, 2008
+@set lastupdate February 1, 2009

 @c %**end of header
 
 @dircategory GNU organization
 @c %**end of header
 
 @dircategory GNU organization


@@ -25,7 +25,7 @@
 Information for maintainers of GNU software, last updated @value{lastupdate}.
 
 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
 Information for maintainers of GNU software, last updated @value{lastupdate}.
 
 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,

-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software

 Foundation, Inc.
 
 @quotation
 Foundation, Inc.
 
 @quotation


@@ -734,17 +734,18 @@ name.
 Please adjust the list of invariant sections as appropriate for your
 manual.  If there are none, then say ``with no Invariant Sections''.
 If your manual is not published by the FSF, and under 400 pages, you
 Please adjust the list of invariant sections as appropriate for your
 manual.  If there are none, then say ``with no Invariant Sections''.
 If your manual is not published by the FSF, and under 400 pages, you

-can omit both cover texts and the inclusion of the GPL.
+can omit both cover texts.

 
 @xref{GNU Sample Texts,,,texinfo,Texinfo}, for a full example in a
 Texinfo manual, and see
 @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about
 how to use the GNU FDL.
 
 
 @xref{GNU Sample Texts,,,texinfo,Texinfo}, for a full example in a
 Texinfo manual, and see
 @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about
 how to use the GNU FDL.
 

-If the manual is over 400 pages, or if the FSF thinks it might be a good
-choice for publishing on paper, then please include our standard
-invariant section which explains the importance of free documentation.
-Write to @email{assign@@gnu.org} to get a copy of this section.
+If the manual is over 400 pages, or if the FSF thinks it might be a
+good choice for publishing on paper, then please include the GNU GPL,
+as in the notice above.  Please also include our standard invariant
+section which explains the importance of free documentation.  Write to
+@email{assign@@gnu.org} to get a copy of this section.

 
 When you distribute several manuals together in one software package,
 their on-line forms can share a single copy of the GFDL (see
 
 When you distribute several manuals together in one software package,
 their on-line forms can share a single copy of the GFDL (see


@@ -1229,8 +1230,10 @@ command @code{gpg --gen-key}.  (For full information about GPG, see
 @url{http://www.gnu.org/software/gpg}).
 
 @item
 @url{http://www.gnu.org/software/gpg}).
 
 @item

-Send a message, preferably GPG-signed, to @email{ftp-upload@@gnu.org}
-with the following:
+Compose a message with the following items in some @var{msgfile}.
+Then GPG-sign it by running @code{gpg --clearsign @var{msgfile}}, and
+finally email the resulting @file{@var{msgfile}.asc}), to
+@email{ftp-upload@@gnu.org}.

 
 @enumerate
 @item
 
 @enumerate
 @item


@@ -1255,15 +1258,18 @@ The administrators will acknowledge your message when they have added
 the proper GPG keys as authorized to upload files for the
 corresponding packages.
 
 the proper GPG keys as authorized to upload files for the
 corresponding packages.
 

+The upload system will email receipts to the given email addresses
+when an upload is made, either successfully or unsuccessfully.
+

 
 @node Automated Upload Procedure
 @subsection Automated Upload Procedure
 
 @cindex uploads
 
 
 @node Automated Upload Procedure
 @subsection Automated Upload Procedure
 
 @cindex uploads
 

-Once you have registered your information as described in the
-previous section, you will be able to do unattended ftp uploads using
-the following procedure.
+Once you have registered your information as described in the previous
+section, you will be able to do ftp uploads for yourself using the
+following procedure.

 
 For each upload destined for @code{ftp.gnu.org} or
 @code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be
 
 For each upload destined for @code{ftp.gnu.org} or
 @code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be


@@ -1290,9 +1296,9 @@ extension. If you do not follow this naming convention, the upload
 @emph{will not be processed}.
 
 Since v1.1 of the upload script, it is also possible to upload a
 @emph{will not be processed}.
 
 Since v1.1 of the upload script, it is also possible to upload a

-@dfn{directive file} on its own to perform certain operations on
-uploaded files.  @xref{FTP Upload Directive File - v1.1}, for more
-information.
+clearsigned directive file on its own (no accompanying @file{.sig} or
+any other file) to perform certain operations on the server.
+@xref{FTP Upload Directive File - v1.1}, for more information.

 
 Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If
 the upload is destined for @code{ftp.gnu.org}, place the file(s) in
 
 Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If
 the upload is destined for @code{ftp.gnu.org}, place the file(s) in


@@ -1314,14 +1320,15 @@ processed.
 One relatively easy way to create and transfer the necessary files is
 to use the @code{gnupload} script, which is available from the
 @file{build-aux/} directory of the @code{gnulib} project at
 One relatively easy way to create and transfer the necessary files is
 to use the @code{gnupload} script, which is available from the
 @file{build-aux/} directory of the @code{gnulib} project at

-@url{http://savannah.gnu.org/projects/gnulib}.  Run @code{gnupload
---help} for a description and examples.
+@url{http://savannah.gnu.org/projects/gnulib}.  @code{gnupload} can
+also remove uploaded files.  Run @code{gnupload --help} for a
+description and examples.

 
 @code{gnupload} uses the @code{ncftpput} program to do the actual
 transfers; if you don't happen to have the @code{ncftp} package
 
 @code{gnupload} uses the @code{ncftpput} program to do the actual
 transfers; if you don't happen to have the @code{ncftp} package

-installed, you can use the @code{ncftpput-ftp} script as a
-replacement, which uses plain command line @code{ftp}.  It's also
-available from the @file{build-aux/} directory of @code{gnulib}.
+installed, the @code{ncftpput-ftp} script in the @file{build-aux/}
+directory of @code{gnulib}.  serves as a replacement which uses plain
+command line @code{ftp}.

 
 If you have difficulties processing an upload, email
 @email{ftp-upload@@gnu.org}.
 
 If you have difficulties processing an upload, email
 @email{ftp-upload@@gnu.org}.


@@ -1376,10 +1383,18 @@ When uploaded by itself, the directive file must contain one or more
 of the directives @code{symlink}, @code{rmsymlink} or @code{archive},
 in addition to the obligatory @code{directory} and @code{version}
 directives.  A @code{filename} directive is not allowed, and a
 of the directives @code{symlink}, @code{rmsymlink} or @code{archive},
 in addition to the obligatory @code{directory} and @code{version}
 directives.  A @code{filename} directive is not allowed, and a

-@code{comment} directive is optional.
+@code{comment} directive remains optional.

 
 If you use more than one directive, the directives are executed in the
 
 If you use more than one directive, the directives are executed in the

-sequence they are specified in.
+sequence they are specified in.  If a directive results in an error,
+further execution of the upload is aborted.
+
+Removing a symbolic link (with @code{rmsymlink}) which does not exist
+results in an error.  However, attempting to create a symbolic link
+that already exists (with @code{symlink}) is not an error.  In this
+case @code{symlink} behaves like the command @command{ln -s -f}: any
+existing symlink is removed before creating the link.  (But an
+existing regular file or directory is not removed.)

 
 Here are a few examples.  The first removes a symlink:
 
 
 Here are a few examples.  The first removes a symlink:
 


@@ -1581,32 +1596,36 @@ Texinfo documentation output for your web pages
 section above.  It has a companion template file, used as the basis
 for the HTML index pages.  Both are available from the Texinfo CVS
 sources:
 section above.  It has a companion template file, used as the basis
 for the HTML index pages.  Both are available from the Texinfo CVS
 sources:

-@format
+
+@smallformat

 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}
 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template}
 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}
 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template}

-@end format
+@end smallformat

 
 

-There is also a ``minimalistic'' template version, available from:
+There is also a minimalistic template, available from:

 
 

-@format
+@smallformat

 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min}
 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min}

-@end format
+@end smallformat

 
 Invoke the script like this, in the directory containing the Texinfo
 source:
 
 Invoke the script like this, in the directory containing the Texinfo
 source:

-@example
-gendocs.sh @var{yourmanual} "GNU @var{yourmanual} manual"
-@end example

 
 

-@noindent where @var{yourmanual} is the short name for your package.
-The script processes the file @file{@var{yourmanual}.texinfo} (or
-@file{.texi} or @file{.txi}).  For example:
+@smallexample
+gendocs.sh --email @var{yourbuglist} @var{yourmanual} "GNU @var{yourmanual} manual"
+@end smallexample

 
 

-@example
+@noindent where @var{yourmanual} is the short name for your package
+and @var{yourbuglist} is the email address for bug reports (typically
+@code{bug-@var{package}@@gnu.org}).  The script processes the file
+@file{@var{yourmanual}.texinfo} (or @file{.texi} or @file{.txi}).  For
+example:
+
+@smallexample

 cd .../emacs/man
 # download gendocs.sh and gendocs_template
 cd .../emacs/man
 # download gendocs.sh and gendocs_template

-gendocs.sh emacs "GNU Emacs manual"
-@end example
+gendocs.sh --email bug-gnu-emacs@@gnu.org emacs "GNU Emacs manual"
+@end smallexample

 
 @command{gendocs.sh} creates a subdirectory @file{manual/} containing
 the manual generated in all the standard output formats: Info, HTML,
 
 @command{gendocs.sh} creates a subdirectory @file{manual/} containing
 the manual generated in all the standard output formats: Info, HTML,


@@ -1629,20 +1648,21 @@ times with different arguments, specifying a different output
 directory with @option{-o} each time, and moving all the output to
 your web page.  Then write (by hand) an overall index.html with links
 to them all.  For example:
 directory with @option{-o} each time, and moving all the output to
 your web page.  Then write (by hand) an overall index.html with links
 to them all.  For example:

-@example
+
+@smallexample

 cd .../texinfo/doc
 cd .../texinfo/doc

-gendocs.sh -o texinfo texinfo "GNU Texinfo manual"
-gendocs.sh -o info info "GNU Info manual"
-gendocs.sh -o info-stnd info-stnd "GNU info-stnd manual"
-@end example
+gendocs.sh --email bug-texinfo@@gnu.org -o texinfo texinfo "GNU Texinfo manual"
+gendocs.sh --email bug-texinfo@@gnu.org -o info info "GNU Info manual"
+gendocs.sh --email bug-texinfo@@gnu.org -o info-stnd info-stnd "GNU info-stnd manual"
+@end smallexample

 
 By default, the script uses @command{makeinfo} for generating
 @acronym{HTML} output.  If you prefer to use @command{texi2html}, use
 the @option{--texi2html} command line option, e.g.:
 
 
 By default, the script uses @command{makeinfo} for generating
 @acronym{HTML} output.  If you prefer to use @command{texi2html}, use
 the @option{--texi2html} command line option, e.g.:
 

-@example
+@smallexample

 gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
 gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"

-@end example
+@end smallexample

 
 The template files will automatically produce entries for additional
 HTML output generated by @command{texi2html} (i.e., split by sections
 
 The template files will automatically produce entries for additional
 HTML output generated by @command{texi2html} (i.e., split by sections


@@ -1653,6 +1673,9 @@ You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI},
 executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the
 @file{gendocs_template} file is found.
 
 executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the
 @file{gendocs_template} file is found.
 

+As usual, run @samp{gendocs.sh --help} for a description of all the
+options, environment variables, and more information.
+

 Please email bug reports, enhancement requests, or other
 correspondence to @email{bug-texinfo@@gnu.org}.
 
 Please email bug reports, enhancement requests, or other
 correspondence to @email{bug-texinfo@@gnu.org}.