X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fmaintain.texi;h=c04722c8a8f1fe3bf7efd3f6a3938d3e71ed1226;hb=7cb5727b0a62d475c2a41c4c0c698f38d845c63d;hp=1c62935ae7575222d702dd012653e551b8082374;hpb=f4d92c2b5019fbf300827b3184cd45f7188e98d7;p=gnulib.git diff --git a/doc/maintain.texi b/doc/maintain.texi index 1c62935ae..c04722c8a 100644 --- 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 August 4, 2008 +@set lastupdate February 1, 2009 @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, -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 -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 @@ -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.) -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, @@ -713,7 +714,7 @@ features of the GFDL. @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 @@ -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 -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. -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 @@ -1228,8 +1230,10 @@ command @code{gpg --gen-key}. (For full information about GPG, see @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 @@ -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 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 -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 @@ -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 -@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 @@ -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 -@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 -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}. @@ -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 -@code{comment} directive is optional. +@code{comment} directive remains optional. 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: @@ -1466,20 +1482,32 @@ your package (in the example above, that is @code{bar}). @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 -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. +@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 -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 @@ -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: -@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} -@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} -@end format +@end smallformat 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 -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, @@ -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: -@example + +@smallexample 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.: -@example +@smallexample 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 @@ -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. +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}.