Initial revision

diff --git a/freshmeat-submit.xml b/freshmeat-submit.xml
new file mode 100644 (file)
index 0000000..3701331
--- /dev/null
+++ b/freshmeat-submit.xml
@@ -0,0 +1,367 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC 
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "docbook/docbookx.dtd">
+<refentry id='freshmeat-submit.1'>
+<refmeta>
+<refentrytitle>freshmeat-submit</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='date'>Dec 7 2003</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>freshmeat-submit</refname>
+<refpurpose>submit release announcements to freshmeat.net</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+  <command>freshmeat-submit</command>
+    <arg>-V</arg>
+    <arg>-n</arg>
+    <arg>-N</arg>
+    <arg>-d</arg>
+    <arg><replaceable>data-options</replaceable></arg>
+    <arg rep='repeat'><replaceable>data-options</replaceable></arg>
+    <arg rep='repeat'><replaceable>files</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+
+<para><application>freshmeat-submit</application> is a command-line tool
+for submitting release announcements to freshmeat.net.  It is intended
+for batch-mode operation in project release scripts, and designed so
+that its input format can easily be generated by scripts.</para>
+
+<para><application>freshmeat-submit</application> accepts release
+information from binary packages named in the command line, or from an
+email-message-like data block on standard input, or from command-line
+flags. Values set with command-line flags override those collected
+from standard input, which in turn override those collected from
+binary package files. The accumulated data is entered into the
+freshmeat database via its XML-RPC interface.</para>
+
+<para>A few flags control the operation of
+<application>freshmeat-submit</application> itself.</para>
+
+<variablelist>
+<varlistentry>
+<term>-d</term>
+<listitem>
+<para>Delete the specified release rather than submitting it.  With
+this option, all data other than Project, Branch, and Release are
+ignored.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>-n</term>
+<listitem>
+<para>Process command-line options only; don't read data from
+standard input.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>-N</term>
+<listitem>
+<para>Display the merged record from binary package arguments,
+standard input and command-line options to standard output.  Don't
+ship it.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>-V</term>
+<listitem>
+<para>Enable verbose debugging of the XML-RPC transaction.  This
+option is mainly for developers.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>Release information is accepted from three sources in the
+following order:</para>
+
+<orderedlist>
+<listitem>
+<para>Binary package files named on the command line.  Presently
+the only supported format is RPM. The data from certain RPM tags
+is mined out of the RPM and merged into the release information.</para>
+</listitem>
+
+<listitem>
+<para>An RFC-2822-format message, strongly resembling an ordinary
+email message, on standard input.  The message header fields each
+specify a particular item of release information; the body (if
+present) becomes the change announcement text.</para>
+</listitem>
+
+<listitem>
+<para>Command-line switches.</para>
+</listitem>
+</orderedlist>
+
+<para>Here is a table of the fields and their 
+corresponding command-line switches:</para>
+
+<informaltable>
+<tgroup cols='5' rowsep='1'>
+<thead>
+<row>
+  <entry>Message field</entry>
+  <entry>RPM tag</entry>
+  <entry>Short switch</entry>
+  <entry>Long switch</entry>
+  <entry>Explanation</entry>
+</row>
+</thead>
+<tbody>
+
+<row>
+<entry>Project:</entry>          <entry>NAME</entry>
+<entry>-p</entry><entry>--project</entry>
+<entry>
+<para>Name of the project (freshmeat shortname) to operate on.</para>
+</entry>
+</row>
+
+<row>
+<entry>Branch:</entry>           <entry>-</entry>
+<entry>-b</entry><entry>--branch</entry>
+<entry>
+<para>Name of project branch to operate on; defaults to &ldquo;Default
+branch&rdquo;</para>
+</entry>
+</row>
+
+<row>
+<entry>Version:</entry>                 <entry>VERSION</entry>
+<entry>-v</entry><entry>--version</entry>
+<entry>
+<para>Version string to be associated with the release.
+Conventionally this will look like n.n or n.n.n, where each n
+is decimal digits.</para>
+</entry>
+</row>
+
+<row>
+<entry>Changes:</entry>           <entry>CHANGELOGTEXT</entry>
+<entry>-c</entry><entry>--changes</entry>
+<entry>
+<para>The Changes field.  Plain text, no more than 600 characters.  
+If no Changes field or option is already present, the changes text is taken
+from the body of the RFC-822 message on standard input.</para>
+</entry>
+</row>
+
+<row>
+<entry>Release-Focus:</entry>     <entry>-</entry>
+<entry>-r</entry><entry>--release-focus</entry>
+<entry>
+<para>Purpose of this release.  See the table of release-focus types 
+below.</para>
+</entry>
+</row>
+
+<row>
+<entry>Hide:</entry>              <entry>-</entry>
+<entry>-x</entry><entry>--hide</entry>
+<entry>
+<para>If this field is present and has the value &ldquo;Y&rdquo;, this
+release will not be visible on the project page.</para>
+</entry>
+</row>
+
+<row>
+<entry>License:</entry>          <entry>-</entry>
+<entry>-l</entry><entry>--license</entry>
+<entry>
+<para>Specify the license under which the release is issued.  Note
+that this is not copied from the RPM License field, because the 
+values don't map.</para>
+</entry>
+</row>
+
+<row>
+<entry>Home-Page-URL:</entry>    <entry>URL</entry>
+<entry>-H</entry><entry>--home-page-url</entry><entry>
+<para>Specify the project home page.</para>
+</entry>
+</row>
+
+<row>
+<entry>Gzipped-Tar-URL:</entry>  <entry>SOURCE</entry>
+<entry>-G</entry><entry>--gzipped-tar-url</entry>
+<entry>
+<para>Specify the URL where a gzipped tarball of source can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>Bzipped-Tar-URL:</entry>  <entry>SOURCE</entry>
+<entry>-B</entry><entry>--bzipped-tar-url</entry>
+<entry>
+<para>Specify the URL where a bzipped tarball of source can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>Zipped-Tar-URL:</entry>   <entry>-</entry>
+<entry>-Z</entry><entry>--zipped-tar-url</entry>
+<entry>
+<para>Specify the URL where a zipped tarball of source can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>Changelog-URL:</entry>           <entry>-</entry>
+<entry>-C</entry><entry>--changelog-url</entry>
+<entry>
+<para>Specify the URL where the project changelog can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>RPM-URL:</entry>                 <entry>-</entry>
+<entry>-R</entry><entry>--rpm-url</entry>
+<entry>
+<para>Specify the URL where an installable binary RPM can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>Debian-URL:</entry>      <entry>-</entry>
+<entry>-D</entry><entry>--debian-url</entry>
+<entry>
+<para>Specify the URL where an installable Debian package can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>OSX-URL:</entry>                 <entry>-</entry>
+<entry>-O</entry><entry>--osx-url</entry>
+<entry>
+<para>Specify the URL where an OS/X binary can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>BSD-Port-URL:</entry>     <entry>-</entry>
+<entry>-P</entry><entry>--bsdport-url</entry>
+<entry>
+<para>Specify the URL where a BSD Ports package can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>Purchase-URL:</entry>     <entry>-</entry>
+<entry>-U</entry><entry>--purchase-url</entry>
+<entry>
+<para>Specify the URL where the software can be purchased.</para>
+</entry>
+</row>
+
+<row>
+<entry>CVS-URL:</entry>                 <entry>-</entry>
+<entry>-S</entry><entry>--cvs-url</entry>
+<entry>
+<para>Specify the URL of the CVS for this package.</para>
+</entry>
+</row>
+
+<row>
+<entry>Mailing-List-URL:</entry> <entry>-</entry>
+<entry>-L</entry><entry>--mailing-list-url</entry>
+<entry>
+<para>Specify the URL where you can sign up for project mailing lists.</para>
+</entry>
+</row>
+
+<row>
+<entry>Mirror-Site-URL:</entry>  <entry>-</entry>
+<entry>-M</entry><entry>--mirror-site-url</entry>
+<entry>
+<para>Specify the URL where an official mirror site for the project
+can be found.</para>
+</entry>
+</row>
+
+<row>
+<entry>Demo-URL:</entry>        <entry>-</entry>
+<entry>-E</entry><entry>url-demo</entry>
+<entry>
+<para>Specify the URL where a demonstration site for the package
+can be found.</para>
+</entry>
+</row>
+
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>The license and all URL fields, when specified, actually change
+the branch record for the project.  Only the Changes, Version,
+Release-Focus, and Hide fields are actually stored for each
+version.</para>
+
+<para>Here are the release-focus types.  Either the string or the
+integer is acceptable.  Case of the string is ignored.</para>
+
+<informaltable>
+<tgroup cols='2' rowsep='1'>
+<tbody>
+<row><entry>initial freshmeat announcement</entry><entry>1</entry></row>
+<row><entry>documentation</entry><entry>2</entry></row>
+<row><entry>code cleanup</entry><entry>3</entry></row>
+<row><entry>minor feature enhancements</entry><entry>4</entry></row>
+<row><entry>major feature enhancements</entry><entry>5</entry></row>
+<row><entry>minor bugfixes</entry><entry>6</entry></row>
+<row><entry>major bugfixes</entry><entry>7</entry></row>
+<row><entry>minor security fixes</entry><entry>8</entry></row>
+<row><entry>major security fixes</entry><entry>9</entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+</refsect1>
+
+<refsect1><title>USAGE</title>
+
+<para>Here is an example of a release-information record that could be
+fed to <application>freshmeat-submit</application> on standard input:</para>
+
+<programlisting>
+Project: doclifter
+Version: 1.1
+Release-Focus: Major feature enhancements
+Hide: N
+Home-Page-URL: http://www.catb.org/~esr/doclifter/
+Gzipped-Tar-URL: http://www.catb.org/~esr/doclifter/doclifter-1.1.tar.gz
+RPM-URL: http://www.catb.org/~esr/doclifter/doclifter-1.1-1.i386.rpm
+
+Fixed a bug in conditional evaluation that twadmin(8) tickled.  Better
+detection of pure inclusions. Better blank-section elimination.
+Kleene star recognized as ... synonym in command synopses.  Correct
+some bugs in semantic-hint collection.  Recognize Qt manual pages and
+use their conventions.  Better lifting of mandoc-generated
+pages. Translate groff-style \[...] escapes, flag unknown ones.  Can
+now parse K&amp;R style function prototypes as well as ANSI ones. This
+version lifts 96% of 9829 manual pages in a full Red Hat 9
+installation with Fedora updates to *validated* XML-DocBook.
+</programlisting>
+
+<para>More typically, you will run this program in a directory where
+you have already made an RPM, giving it the RPM as a file argument.
+In that case, all you will normally need to supply is the Release-Focus
+field; the other required fields (including, most notably, the Changes
+field) will be mined out of the RPM.</para>
+</refsect1>
+
+<refsect1><title>RETURN VALUES</title>
+
+<para>0 on success, 1 on failure.  In case of failure, any error message
+passed back by the XML-RPC interface is issued to standard error.</para>
+
+
+</refsect1>
+<refsect1 id='author'><title>AUTHORS</title> 
+<para>Eric S. Raymond <email>esr@thyrsus.com</email>.</para> 
+</refsect1> 
+</refentry>