# HG changeset patch
# User cli
# Date 1249576894 -7200
# Node ID dcc7e491fbc9f555ccb9c761b04da71756d71096
# Parent ad210aa137a495ba652e0bc56a6f6d94492eea88
Removing doc subdir which resides now in sonews-doc repository.
diff -r ad210aa137a4 -r dcc7e491fbc9 doc/config.xsl
--- a/doc/config.xsl Thu Aug 06 18:34:10 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,17 +0,0 @@
-<?xml version="1.0"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- xmlns:fo="http://www.w3.org/1999/XSL/Format"
- version="1.0">
- <xsl:param name="use.id.as.filename" select="1"/>
- <xsl:param name="admon.graphics" select="1"/>
- <xsl:param name="admon.graphics.path"></xsl:param>
- <xsl:param name="chunk.section.depth" select="0"></xsl:param>
- <xsl:param name="html.stylesheet" select="'sonews.css'"/>
-<xsl:template name="user.footer.navigation">
- <p class="copyright">
- <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/80x15.png" /></a> This work by <span xmlns:cc="http://creativecommons.org/ns#" property="cc:attributionName">Christian Lins</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0 License</a>.
- </p>
-</xsl:template>
-
-</xsl:stylesheet>
-
diff -r ad210aa137a4 -r dcc7e491fbc9 doc/makedoc
--- a/doc/makedoc Thu Aug 06 18:34:10 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-xmlto --skip-validation html -m config.xsl sonews.xml
diff -r ad210aa137a4 -r dcc7e491fbc9 doc/sonews.css
--- a/doc/sonews.css Thu Aug 06 18:34:10 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,35 +0,0 @@
-body
-{
- font-family: Liberation Sans,Verdana,sans-serif;
- font-size: 11pt;
-}
-
-.screen {
- font-family: monospace;
- font-size: 1em;
- display: block;
- padding: 10px;
- border: 1px solid #bbb;
- background-color: #eee;
- color: #000;
- overflow: auto;
- border-radius: 2.5px;
- -moz-border-radius: 2.5px;
- margin: 0.5em 2em;
-
-}
-
-.programlisting {
- font-family: monospace;
- font-size: 1em;
- display: block;
- padding: 10px;
- border: 1px solid #bbb;
- background-color: #ddd;
- color: #000;
- overflow: auto;
- border-radius: 2.5px;
- -moz-border-radius: 2.5px;
- margin: 0.5em 2em;
-}
-
diff -r ad210aa137a4 -r dcc7e491fbc9 doc/sonews.xml
--- a/doc/sonews.xml Thu Aug 06 18:34:10 2009 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,305 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY tex "TeX">
- <!ENTITY latex "LaTeX">
-]>
-<book id="sonews.xml" lang="en">
- <title>sonews Usenet News Server</title>
- <para>
- <emphasis role="bold">sonews</emphasis> is NNTP server than can provide
- access to both local and global Usenets newsgroups. It is written in
- <ulink url="http://java.sun.com/">Java</ulink> and uses a relational
- database as backend.
- </para>
- <para>
- <emphasis role="bold">2009/07/28</emphasis>:
- <emphasis>sonews/1.0.0</emphasis>
- (<ulink url="files/sonews-1.0.0.tar.bz2">binary tarball</ulink>,
- <ulink url="files/sonews-1.0.0-src.tar.bz2">source tarball</ulink>) new major release.
- A lot of refactoring was done to make the code more robust and
- maintainable. Of course, several bugs were fixed, too ;)
- The 0.5.x line moves from unstable to testing in the DEB repository although
- the 1.0.x seems no less stable. If in doubt choose 1.0.x.
- </para>
- <para>
- <emphasis role="bold">2009/07/01</emphasis>:
- <emphasis>sonews/0.5.1</emphasis>
- (<ulink url="files/sonews-0.5.1.tar.bz2">binary tarball</ulink>,
- <ulink url="files/sonews-0.5.1-src.tar.bz2">source tarball</ulink>) bugfix
- release.
- Broken Cancel-mechanism and broken buildscript fixed.
- See <ulink url="http://code.xerxys.info:8000/hgwebdir.cgi/sonews-0.5/log/287">
- changelog</ulink> for more details.
- </para>
- <para>
- <emphasis role="bold">2009/06/29</emphasis>:
- <emphasis>sonews/0.5.0</emphasis>
- (<ulink url="files/sonews-0.5.0.tar.bz2">binary tarball</ulink>,
- <ulink url="files/sonews-0.5.0-src.tar.bz2">source tarball</ulink>) final
- released.
- The setup is a little clumsy but the software is stable and works well.
- </para>
-
- <chapter>
- <title>Introduction</title>
- <para>sonews is a RCF3977 compliant NNTP Usenet server.
- It is written in Java and uses a relation database management system
- (RDBMS) as backend (currently
- <ulink url="http://www.postgresql.com/">PostgreSQL</ulink> and
- <ulink url="http://www.mysql.com/">MySQL</ulink>).
- sonews is highly multithreaded and uses Java NIO asynchronous sockets
- to handle thousands of concurrent connections.</para>
- <para>sonews is Free and Open Source Software (FOSS) licensed under the
- terms of the
- <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public License</ulink>
- Version 3 (or later).</para>
-
- <sect1 label="1.1">
- <title>History</title>
- <para>Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd)
- although there is very little code in sonews that can be identified
- as direct derivation.
- sonews was developed as diploma thesis project of Christian Lins at
- <ulink url="http://de.sun.com/">StarOffice development</ulink>
- in Hamburg and is now a Free Software project.</para>
- </sect1>
-
- <sect1 label="1.2">
- <title>Roadmap</title>
- <para>
- For sonews/1.1.x a plugin API for storage backends and command handlers
- is planned.
- See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
- issues with target sonews/1.1.x.
- </para>
- </sect1>
- </chapter>
-
- <chapter label="2">
- <title>Installation and initial setup</title>
- <sect1 label="2.1">
- <title>Download & Installation</title>
- <sect2 label="2.1.1">
- <title>Debian based systems</title>
- <para>You can install sonews with
- <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
- easily.
- Add the following line to /etc/apt/sources.list:</para>
- <screen>deb http://packages.xerxys.info/debian/ testing main # for sonews/0.5.x</screen>
- <screen>deb http://packages.xerxys.info/debian/ unstable main # for sonews/1.0.x</screen>
- <para>And add the GPG-Key for package authentification, see
- <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
- for more details.</para>
- <para>Then force an update of your local package list:</para>
- <screen># apt-get update</screen>
- <para>To install sonews and all prerequisites issue the following command:</para>
- <screen># apt-get install sonews</screen>
- <para>This method should work for all recent Debian-based distributions
-(<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
- </sect2>
-
- <sect2 label="2.1.2">
- <title>Other *nix systems</title>
- <para>See <ulink url="files/">Files Section</ulink> for recent binary and source tarballs.</para>
- <para>Use the binary archive and extract it in a directory of your choice. Make sure your system
-provides the necessary prerequisites:</para>
- <itemizedlist>
- <listitem>
- <para>Java6 compatible runtime (JRE)</para>
- </listitem>
- <listitem>
- <para>Java Mail API implementation, e.g. <ulink url="http://java.sun.com/products/javamail/">Sun Java Mail</ulink>.
-GNU JavaMail has a broken POP3 Provider and does not work with sonews.</para>
- </listitem>
- <listitem>
- <para>JSP Servlet Container (e.g.
- <ulink url="http://kitten.sonews.org/">Kitten</ulink>) [optional]</para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
- <sect1 label="2.2">
- <title>Initial database setup</title>
- <para>Before you start sonews, you must prepare the database. Currently sonews is known
-to work with PostgreSQL and MySQL.</para>
- <para>It is highly recommended to create an own database for every sonews instance, e.g.
-called 'sonews'. Additionally, it is recommended to create a unique database user
-for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews!
-The sonews user needs rights for SELECT, INSERT and UPDATE statements.
-Refer to the database's manual for instructions.</para>
- <para>You will find the SQL Schema definitions in the helpers subdirectory of
-the source and binary distributions. You can create the tables manually using
-this templates or you can use the setup helper:</para>
- <screen>user@debian$ sonews setup</screen>
- <para>or on other *nix systems:</para>
- <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup</screen>
- <para>The tool will ask for some information about your database environment,
-connect to the database, create the tables and creates a default bootstrap
-config file called sonews.conf.</para>
- </sect1>
- </chapter>
-
- <chapter label="3">
- <title>Running sonews</title>
- <sect1 label="3.1">
- <title>Configuration</title>
- <para>There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration
-in the database table config.</para>
- <para>There are various configuration values that can be adapted:</para>
- <variablelist>
- <varlistentry>
- <term>‘<literal>sonews.article.maxsize</literal>’</term>
- <listitem>
- <para>Maximum allowed body size of a news message given in kilobytes. Please note that
-for MySQL the ‘<literal>max_allowed_packet</literal>’ configuration variable must
-be set to a value higher than ‘<literal>sonews.article.maxsize</literal>’ otherwise posting
-of large mails will fail.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>‘<literal>sonews.debug</literal>’</term>
- <listitem>
- <para>
- If set to true every(!) data going through sonews' socket
- is written to sonews.log. After a high traffic night the logfile can be
- several gigabytes large, so be careful with this setting.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>‘<literal>sonews.hostname</literal>’</term>
- <listitem>
- <para>
- Canonical name of the server instance. This variable is part of
- the server's hello message to the client and used to generate
- Message-Ids.
- It is highly recommended to set sonews.hostname to the full
- qualified domain name (FQDN) of the host machine.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>‘<literal>sonews.timeout</literal>’</term>
- <listitem>
- <para>
- Socket timeout for client connections in seconds. Default as
- recommended in RFC3977 is 180 seconds.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>‘<literal>sonews.port</literal>’</term>
- <listitem>
- <para>
- Listening port of sonews daemon. This value can be overridden
- with the -p command line argument.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>‘<literal>sonews.xdaemon.host</literal>’</term>
- <listitem>
- <para>
- Hostname or IP address of the client machine that is allowed to
- use the XDAEMON command. Default: localhost
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
-
- <sect1 label="3.2">
- <title>Command line arguments</title>
- <para>If you like to start sonews directly, you can use one of the following
-arguments:</para>
- <screen>java -jar sonews.jar [arguments]
- where arguments:
- -c|-config <path to config file> if custom config file preferred
- -dumpjdbcdriver Prints out a list of available JDBC drivers
- -feed Enables feed daemon for pulling news from peer servers
- -h|-help This output
- -mlgw Enables the Mailinglist Gateway poller
- -p portnumber Port on which sonews is listening for incoming connections.
- Overrides port settings in config file and database.</screen>
- </sect1>
-
- <sect1 label="3.3">
- <title>Webinterface</title>
- <para>The package sonews-web provides an optional webinterface that can be used to
-review statistical information and configuration values of sonews.</para>
- <screen>sonews-web start|stop</screen>
- <para>The webinterface uses the the lightweight Servlet Container Kitten and is
-per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
- </sect1>
-
- <sect1 label="3.4">
- <title>Newsgroup configuration</title>
- <para>
- Currently some manual work is necessary to create a newsgroup hosted
- by a sonews instance.
- </para>
- <para>
- One possibility is to talk via Telnet to the sonews instance and
- use the non-standard command XDAEMON.
- <screen>telnet localhost 119</screen>
- <screen>XDAEMON GROUPADD local.test 0</screen>
- Please note that the XDAEMON command has restricted access and is only
- available via local connections (default, can be changed with config
- value sonews.xdaemon.host).
- </para>
- <para>
- You can also use the web interface to create newsgroups.
- </para>
- </sect1>
- </chapter>
-
- <chapter label="4">
- <title>Development</title>
- <para>You're welcome to create patches with bugfixes or additional features. The
-Mercurial DSCM makes this step an easy task.</para>
- <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
- <screen>hg clone http://code.xerxys.info:8000/hg/sonews/ sonews-trunk</screen>
- <para>Then make your changes, create a bundle of changesets and send this to me via email.
-Or ask for push access to the public repository.</para>
- <para>
- There is a nightly generated <ulink url="apidoc/">Javadoc API documentation</ulink> that will help
- you to get in touch with the sonews source.
- </para>
- <para>Some debugging hints: if the server blocks and does not longer respond you
-probably found a deadlock. Do not kill the process with "kill -9 <pid>"
-but send a SIGQUIT signal with "kill -3 <pid>" and the Java VM will output
-a stracktrace of all threads. This output is the most valuable information to
-fix the deadlock.</para>
-
- <sect1 label="4.1">
- <title>Contributors</title>
- <para>Maintainer and project lead:
-Christian Lins (contact christian.lins (at) fh-osnabrueck.de)</para>
- </sect1>
-
- <sect1 label="4.2">
- <title>Sponsors</title>
- <para>The author thanks <ulink url="http://www.sun.com/">Sun Microsystems</ulink> for fully
-financing the first version of sonews. A really free software supporting company!</para>
- <para>If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...),
- feel free to contact the project leader.
-A friendly email or a bug report is most welcome, too :-)</para>
- </sect1>
- </chapter>
-
- <chapter label="5">
- <title>Links and further information</title>
- <itemizedlist>
- <listitem>
- <para><ulink url="http://bugs.xerxys.info/">Bugtracker</ulink>, register necessary, see project 'sonews'.</para>
- </listitem>
- <listitem>
- <para><ulink url="http://www.sun.com/">Sun Microsystems</ulink>, friendly sponsor.</para>
- </listitem>
- <listitem>
- <para><ulink url="http://www.fh-osnabrueck">University of Applied Sciences Osnabrueck</ulink></para>
- </listitem>
- </itemizedlist>
- </chapter>
-</book>