@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate May 17, 2012
+@set lastupdate October 27, 2012
@c %**end of header
@dircategory GNU organization
@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
projects / gnulib.git / blobdiff