Add missing module dependencies.

[gnulib.git] / doc / maintain.texi

diff --git a/doc/maintain.texi b/doc/maintain.texi
index 1c62935..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 August 4, 2008
+@set lastupdate February 1, 2009

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


@@ -25,12 +25,12 @@
 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
 Permission is granted to copy, distribute and/or modify this document
 Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document

-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or

 any later version published by the Free Software Foundation; with no
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled
 any later version published by the Free Software Foundation; with no
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled


@@ -619,11 +619,12 @@ Every nontrivial file needs a license notice as well as the copyright
 notice.  (Without a license notice giving permission to copy and
 change the file, the file is non-free.)
 
 notice.  (Without a license notice giving permission to copy and
 change the file, the file is non-free.)
 

-The package itself should contain a full copy of GPL (conventionally
-in a file named @file{COPYING}) and the GNU Free Documentation License
-(included within your documentation).  If the package contains any
-files distributed under the Lesser GPL, it should contain a full copy
-of that as well (conventionally in a file named
+The package itself should contain a full copy of GPL in plain text
+(conventionally in a file named @file{COPYING}) and the GNU Free
+Documentation License (included within your documentation, so there is
+no need for a separate plain text version).  If the package contains
+any files distributed under the Lesser GPL, it should contain a full
+copy of its plain text version also (conventionally in a file named

 @file{COPYING.LESSER}).
 
 If you have questions about license issues for your GNU package,
 @file{COPYING.LESSER}).
 
 If you have questions about license issues for your GNU package,


@@ -713,7 +714,7 @@ features of the GFDL.
 
 @smallexample
 Permission is granted to copy, distribute and/or modify this document
 
 @smallexample
 Permission is granted to copy, distribute and/or modify this document

-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or

 any later version published by the Free Software Foundation; with the
 Invariant Sections being ``GNU General Public License'', with the
 Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
 any later version published by the Free Software Foundation; with the
 Invariant Sections being ``GNU General Public License'', with the
 Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts


@@ -733,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


@@ -1228,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


@@ -1254,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


@@ -1289,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


@@ -1313,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}.


@@ -1375,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:
 


@@ -1466,20 +1482,32 @@ your package (in the example above, that is @code{bar}).
 
 @node Announcements
 @section Announcing Releases
 
 @node Announcements
 @section Announcing Releases

+@cindex announcements

 
 

+@cindex @code{info-gnu} mailing list

 When you have a new release, please make an announcement.  For
 official new releases, including those made just to fix bugs, we
 When you have a new release, please make an announcement.  For
 official new releases, including those made just to fix bugs, we

-recommend using the (moderated) general GNU announcements list,
-@email{info-gnu@@gnu.org}.  Doing so makes it easier for users and
-developers to find the latest GNU releases.  On the other hand, please
-do not announce test releases on @code{info-gnu} unless it's an
+strongly recommend using the (moderated) general GNU announcements
+list, @email{info-gnu@@gnu.org}.  Doing so makes it easier for users
+and developers to find the latest GNU releases.  On the other hand,
+please do not announce test releases on @code{info-gnu} unless it's an

 unusual situation.
 
 unusual situation.
 

+@cindex @url{http://planet.gnu.org}
+@cindex Savannah, news area
+Please also post release announcements in the news section of your
+Savannah project site.  It is fine to also write news entries for test
+releases and any other newsworthy events.  The news feeds from all GNU
+projects at savannah are aggregated at @url{http://planet.gnu.org}.
+(You can also post items directly, or arrange for feeds from other
+locations; see contact information on the GNU Planet web page.) 
+
+@cindex announcement mailing list, project-specific

 You can maintain your own mailing list (typically
 @email{info-@var{program}@@gnu.org}) for announcements as well if you
 You can maintain your own mailing list (typically
 @email{info-@var{program}@@gnu.org}) for announcements as well if you

-like.  For your own list, you can decide as you see fit what events
-are worth announcing.  (@xref{Mail}, for more suggestions on handling
-mail for your package.)
+like.  For your own list, of course you can decide as you see fit what
+events are worth announcing.  (@xref{Mail}, for more suggestions on
+handling mail for your package.)

 
 
 @node Web Pages
 
 
 @node Web Pages


@@ -1568,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
+
+@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:

 
 

-@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,


@@ -1616,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


@@ -1640,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}.