@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate May 13, 2012
+@set lastupdate January 1, 2013
@c %**end of header
@dircategory GNU organization
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010, 2011, 2012 Free Software Foundation, Inc.
+2010, 2011, 2012, 2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
additional week, please write to @email{maintainers@@gnu.org} about it.
After receiving the necessary form, all contributors then print it and
-sign it. Contributors residing outside the U.S. must mail the signed
-form to the FSF via the post. Contributors located in the U.S. can
-then email or fax a scanned copy back to the FSF (or use postal mail,
-if they prefer). (To emphasize, the necessary distinction is between
-US residents and non-residents; citizenship does not matter.)
+sign it. Contributors located in the USA or Germany can then email or
+fax a scanned copy back to the FSF (or use postal mail, if they
+prefer). Contributors residing outside the USA or Germany must mail
+the signed form to the FSF via postal mail. To emphasize, the
+necessary distinction is between residents and non-residents of these
+countries; citizenship does not matter.
For less common cases, we have template files you should send to the
contributor. Be sure to fill in the name of the person and the name
useful functionality, as a ``library'' facility (though the module is
not always packaged technically as a library).
-Make sure the license of the module is compatible with current <em>and
-future</em> GPL versions. ``GNU GPL version 3 or later'' is good, and
+Make sure the license of the module is compatible with current @emph{and
+future} GPL versions. ``GNU GPL version 3 or later'' is good, and
so is anything which includes permission for use under those GPL
versions (including ``GNU GPL version 2 or later'', ``LGPL version
-<em>n</em> or later'', ``LGPL version 2.1'', ``GNU Affero GPL version
-3 or later''). Lax permissive licenses are ok too, since they are
+@var{n} or later'', ``LGPL version 2.1'', ``GNU Affero GPL version 3
+or later''). Lax permissive licenses are ok too, since they are
compatible with all GPL versions.
``GPL version 2 only'' is obviously unacceptable because it is
-incompatble with GPL version 3. ``GPL version 3 only'' and ``GPL
-version 2 or 3 only'' have a subtler problem: they will be incompatble
+incompatible with GPL version 3. ``GPL version 3 only'' and ``GPL
+version 2 or 3 only'' have a subtler problem: they would be incompatible
with GPL version 4, if we ever make one, so the module would become an
obstacle to upgrading your package's license to ``GPL version 4 or
later''.
GPL versions 2 and 3.
It would be unreasonable to ask the author of the external module to
-assign its the copyright to the FSF. After all, person did not write
+assign its copyright to the FSF. After all, person did not write
it specifically as a contribution to your package, so it would be
-impertinent to ask per, out of the blue, ``Please give the FSF your
+impertinent to ask, out of the blue, ``Please give the FSF your
copyright.''
So make your program use the module but without treating the module as
@menu
* Automated Upload Registration::
* Automated Upload Procedure::
+* FTP Upload Directive File - v1.2::
* FTP Upload Directive File - v1.1::
* FTP Upload Directive File - v1.0::
@end menu
for your GNU package:
@enumerate
-
@item
Create an account for yourself at @url{http://savannah.gnu.org}, if
you don't already have one. By the way, this is also needed to
In the @samp{My Account Conf} page on @code{savannah}, upload the GPG
key you will use to sign your packages. If you haven't created one
before, you can do so with the command @code{gpg --gen-key} (you can
-accept all the default answers to its questions).
+accept and/or confirm the default answers to its questions).
Optional but recommended: Send your key to a GPG public key server:
@code{gpg --keyserver keys.gnupg.net --send-keys @var{keyid}}, where
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
+Since v1.1 of the upload directives, it is also possible to upload a
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.
@url{https://lists.gnu.org/archive/html/ftp-upload-report}.
+@node FTP Upload Directive File - v1.2
+@subsection FTP Upload Directive File - v1.2
+
+All the directives and documentation for v1.1 of the protocol still
+apply. @xref{FTP Upload Directive File - v1.1}, for more information.
+
+@subheading New directive @code{replace}
+
+@cindex replacing uploaded files
+@cindex uploads, replacing
+As part of an uploaded triplet, a @file{foo.tar.gz.directive.asc} file
+might contain these lines (before being GPG-clearsigned):
+
+@example
+version: 1.2
+directory: bar/v1
+filename: foo.tar.gz
+comment: hello world!
+@end example
+
+If @file{foo.tar.gz} exists prior to upload, this directive file will
+result in an error. Prior to May 2012, the behavior (of v1.1) was
+different: any existing files were automatically archived and replaced
+with the new upload. Since May 2012, no files are replaced unless the
+(new) @code{replace} directive is set to @code{true} in the directive
+file. That directive requires version 1.2 of the protocol. For
+example:
+
+@example
+version: 1.2
+directory: bar/v1
+filename: foo.tar.gz
+replace: true
+comment: hello world!
+@end example
+
+
@node FTP Upload Directive File - v1.1
@subsection FTP Upload Directive File - v1.1
When part of a triplet, the directive file must always contain the
directives @code{version}, @code{directory} and @code{filename}, as
-described. In addition, a 'comment' directive is allowed.
+described. In addition, a @code{comment} directive is allowed.
The @code{version} directive must always have the value @samp{1.1}.
@file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
The directive file can be used to create currently non-existent
-directory trees, as long as they are under the package directory for
-your package (in the example above, that is @code{bar}).
+directory trees, as long as they are under the directory for your
+package (in the example above, the package directory is @code{bar}).
If you upload a file that already exists in the FTP directory, the
original will simply be archived and replaced with the new upload.
+There is no automated or online access to archived files; if you want
+to retrieve or view them, please email sysadmin.
@subheading Standalone directives
-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}
+When uploaded by itself, a 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 remains optional.
@node FTP Upload Directive File - v1.0
@subsection FTP Upload Directive File - v1.0
-@dfn{As of June 2006, the upload script is running in compatibility
-mode, allowing uploads with either version@tie{}1.1 or
-version@tie{}1.0 of the directive file syntax. Support for v1.0
-uploads will be phased out by the end of 2006, so please upgrade
-to@tie{}v1.1.}
+Support for v1.0 uploads was phased out in May 2012; please upgrade
+to@tie{}v1.2.
The directive file should contain one line, excluding the clearsigned
data GPG that inserts, which specifies the final destination directory
@node Hosting for Web Pages
@section Hosting for Web Pages
+@cindex web pages, hosting for
The best way to maintain the web pages for your project is to register
the project on @code{savannah.gnu.org}. Then you can edit the pages
@node Freedom for Web Pages
@section Freedom for Web Pages
+@cindex web pages, freedom for
If you use a site other than @code{www.gnu.org}, please make sure that
the site runs on free software alone. (It is ok if the site uses
@node Manuals on Web Pages
@section Manuals on Web Pages
+@cindex web pages, including manuals on
+@cindex formats for documentation, desired
The web pages for the package should include its manuals, in HTML,
-DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source).
-All of these can be generated automatically from the Texinfo source
-using Makeinfo and other programs.
+DVI, Info, PDF, plain ASCII, and the source Texinfo. All of these can
+be generated automatically from Texinfo using Makeinfo and other
+programs. If the Texinfo itself is generated from some other source
+format, include that too.
When there is only one manual, put it in a subdirectory called
@file{manual}; the file @file{manual/index.html} should have a link to
@subsection Invoking @command{gendocs.sh}
@pindex gendocs.sh
@cindex generating documentation output
+@cindex documentation output, generating
The script @command{gendocs.sh} eases the task of generating the
Texinfo documentation output for your web pages
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 HTML
+output. If you prefer to use @command{texi2html}, use the
+@option{--texi2html} command line option, e.g.:
@smallexample
gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
and chapters).
You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI},
-@env{TEXI2HTML} and @env{DVIPS} to control the programs that get
-executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the
+etc., to control the programs that get 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}.
+correspondence about @command{gendocs} to @email{bug-texinfo@@gnu.org}.
@node CVS Keywords in Web Pages
of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd''.
Note that this uses a space, not a slash.
+
@node Interviews and Speeches
@chapter Interviews and Speeches
@itemize @bullet
@item
What GNU is (an operating system developed to be Unix-like and totally
-free software). It is good to mention @url{gnu.org}.
+free software). It is good to mention @url{http://www.gnu.org}.
@item
What free software is (the users control it, so it doesn't control
them). It is good to state the four freedoms and/or refer to
-@url{gnu.org/philosophy/free-sw.html}.
+@url{http://www.gnu.org/philosophy/free-sw.html}.
@item
What GNU/Linux is (Linux filled the last gap in GNU). It is useful to
-refer to @url{gnu.org/gnu/linux-and-gnu.html}.
+refer to @url{http://www.gnu.org/gnu/linux-and-gnu.html}.
@item
What the GNU Project is (the project to develop GNU).