Removing doc subdir which resides now in sonews-doc repository.
authorcli
Thu, 06 Aug 2009 18:41:34 +0200
changeset 6dcc7e491fbc9
parent 5 ad210aa137a4
child 7 0b76e099eb96
Removing doc subdir which resides now in sonews-doc repository.
doc/config.xsl
doc/makedoc
doc/sonews.css
doc/sonews.xml
     1.1 --- a/doc/config.xsl	Thu Aug 06 18:34:10 2009 +0200
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,17 +0,0 @@
     1.4 -<?xml version="1.0"?>
     1.5 -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     1.6 -                xmlns:fo="http://www.w3.org/1999/XSL/Format"
     1.7 -                version="1.0">
     1.8 -  <xsl:param name="use.id.as.filename" select="1"/>
     1.9 -  <xsl:param name="admon.graphics" select="1"/>
    1.10 -  <xsl:param name="admon.graphics.path"></xsl:param>
    1.11 -  <xsl:param name="chunk.section.depth" select="0"></xsl:param>
    1.12 -  <xsl:param name="html.stylesheet" select="'sonews.css'"/>
    1.13 -<xsl:template name="user.footer.navigation">
    1.14 -  <p class="copyright">
    1.15 -  <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>.
    1.16 -  </p>
    1.17 -</xsl:template>
    1.18 -
    1.19 -</xsl:stylesheet>
    1.20 -
     2.1 --- a/doc/makedoc	Thu Aug 06 18:34:10 2009 +0200
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,1 +0,0 @@
     2.4 -xmlto --skip-validation html -m config.xsl sonews.xml
     3.1 --- a/doc/sonews.css	Thu Aug 06 18:34:10 2009 +0200
     3.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.3 @@ -1,35 +0,0 @@
     3.4 -body 
     3.5 -{
     3.6 -    font-family: Liberation Sans,Verdana,sans-serif;
     3.7 -    font-size: 11pt;
     3.8 -}
     3.9 -
    3.10 -.screen {
    3.11 -        font-family: monospace;
    3.12 -        font-size: 1em;
    3.13 -        display: block;
    3.14 -        padding: 10px;
    3.15 -        border: 1px solid #bbb;
    3.16 -        background-color: #eee;
    3.17 -        color: #000;   
    3.18 -        overflow: auto;
    3.19 -        border-radius: 2.5px;
    3.20 -        -moz-border-radius: 2.5px;
    3.21 -        margin: 0.5em 2em;
    3.22 - 
    3.23 -}
    3.24 -
    3.25 -.programlisting {
    3.26 -        font-family: monospace;
    3.27 -        font-size: 1em;
    3.28 -        display: block;
    3.29 -        padding: 10px;
    3.30 -        border: 1px solid #bbb;
    3.31 -        background-color: #ddd;
    3.32 -        color: #000;   
    3.33 -        overflow: auto;
    3.34 -        border-radius: 2.5px;
    3.35 -        -moz-border-radius: 2.5px;
    3.36 -        margin: 0.5em 2em;
    3.37 -}
    3.38 -
     4.1 --- a/doc/sonews.xml	Thu Aug 06 18:34:10 2009 +0200
     4.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.3 @@ -1,305 +0,0 @@
     4.4 -<?xml version="1.0"?>
     4.5 -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
     4.6 -  <!ENTITY tex "TeX">
     4.7 -  <!ENTITY latex "LaTeX">
     4.8 -]>
     4.9 -<book id="sonews.xml" lang="en">
    4.10 -  <title>sonews Usenet News Server</title>
    4.11 -  <para>
    4.12 -    <emphasis role="bold">sonews</emphasis> is NNTP server than can provide 
    4.13 -    access to both local and global Usenets newsgroups. It is written in 
    4.14 -    <ulink url="http://java.sun.com/">Java</ulink> and uses a relational
    4.15 -    database as backend.
    4.16 -  </para>
    4.17 -  <para>
    4.18 -    <emphasis role="bold">2009/07/28</emphasis>:
    4.19 -    <emphasis>sonews/1.0.0</emphasis>
    4.20 -    (<ulink url="files/sonews-1.0.0.tar.bz2">binary tarball</ulink>,
    4.21 -    <ulink url="files/sonews-1.0.0-src.tar.bz2">source tarball</ulink>) new major release.
    4.22 -    A lot of refactoring was done to make the code more robust and 
    4.23 -    maintainable. Of course, several bugs were fixed, too ;)
    4.24 -    The 0.5.x line moves from unstable to testing in the DEB repository although
    4.25 -    the 1.0.x seems no less stable. If in doubt choose 1.0.x.
    4.26 -  </para>
    4.27 -  <para>
    4.28 -    <emphasis role="bold">2009/07/01</emphasis>:
    4.29 -    <emphasis>sonews/0.5.1</emphasis>
    4.30 -    (<ulink url="files/sonews-0.5.1.tar.bz2">binary tarball</ulink>,
    4.31 -    <ulink url="files/sonews-0.5.1-src.tar.bz2">source tarball</ulink>) bugfix
    4.32 -    release.
    4.33 -    Broken Cancel-mechanism and broken buildscript fixed.
    4.34 -    See <ulink url="http://code.xerxys.info:8000/hgwebdir.cgi/sonews-0.5/log/287">
    4.35 -      changelog</ulink> for more details.
    4.36 -  </para>
    4.37 -  <para>
    4.38 -    <emphasis role="bold">2009/06/29</emphasis>: 
    4.39 -    <emphasis>sonews/0.5.0</emphasis> 
    4.40 -    (<ulink url="files/sonews-0.5.0.tar.bz2">binary tarball</ulink>,
    4.41 -    <ulink url="files/sonews-0.5.0-src.tar.bz2">source tarball</ulink>) final 
    4.42 -    released. 
    4.43 -    The setup is a little clumsy but the software is stable and works well.
    4.44 -  </para>
    4.45 -  
    4.46 -  <chapter>
    4.47 -    <title>Introduction</title>
    4.48 -    <para>sonews is a RCF3977 compliant NNTP Usenet server. 
    4.49 -    It is written in Java and uses a relation database management system
    4.50 -    (RDBMS) as backend (currently
    4.51 -    <ulink url="http://www.postgresql.com/">PostgreSQL</ulink> and
    4.52 -    <ulink url="http://www.mysql.com/">MySQL</ulink>).
    4.53 -    sonews is highly multithreaded and uses Java NIO asynchronous sockets
    4.54 -    to handle thousands of concurrent connections.</para>
    4.55 -    <para>sonews is Free and Open Source Software (FOSS) licensed under the 
    4.56 -    terms of the
    4.57 -    <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public License</ulink>
    4.58 -    Version 3 (or later).</para>
    4.59 -
    4.60 -    <sect1 label="1.1">
    4.61 -      <title>History</title>
    4.62 -      <para>Ancestor of sonews is probably the Neat NNTP Daemon (n3tpd) 
    4.63 -      although there is very little code in sonews that can be identified
    4.64 -      as direct derivation.
    4.65 -      sonews was developed as diploma thesis project of Christian Lins at
    4.66 -      <ulink url="http://de.sun.com/">StarOffice development</ulink>
    4.67 -      in Hamburg and is now a Free Software project.</para>
    4.68 -    </sect1>
    4.69 -
    4.70 -    <sect1 label="1.2">
    4.71 -      <title>Roadmap</title>
    4.72 -        <para>
    4.73 -        For sonews/1.1.x a plugin API for storage backends and command handlers
    4.74 -        is planned. 
    4.75 -        See <ulink url="http://bugs.xerxys.info/">Bugtracker</ulink> for
    4.76 -        issues with target sonews/1.1.x.
    4.77 -        </para>
    4.78 -    </sect1>
    4.79 -  </chapter>
    4.80 -
    4.81 -  <chapter label="2">
    4.82 -    <title>Installation and initial setup</title>
    4.83 -    <sect1 label="2.1">
    4.84 -      <title>Download &amp; Installation</title>
    4.85 -      <sect2 label="2.1.1">
    4.86 -        <title>Debian based systems</title>
    4.87 -        <para>You can install sonews with 
    4.88 -        <ulink url="http://www.debian.org/doc/manuals/apt-howto/">APT</ulink>
    4.89 -        easily.
    4.90 -        Add the following line to /etc/apt/sources.list:</para>
    4.91 -        <screen>deb http://packages.xerxys.info/debian/ testing main # for sonews/0.5.x</screen>
    4.92 -        <screen>deb http://packages.xerxys.info/debian/ unstable main # for sonews/1.0.x</screen>
    4.93 -        <para>And add the GPG-Key for package authentification, see 
    4.94 -        <ulink url="http://packages.xerxys.info/debian/">Xerxys Debian Repository</ulink>
    4.95 -        for more details.</para>
    4.96 -        <para>Then force an update of your local package list:</para>
    4.97 -        <screen># apt-get update</screen>
    4.98 -        <para>To install sonews and all prerequisites issue the following command:</para>
    4.99 -        <screen># apt-get install sonews</screen>
   4.100 -        <para>This method should work for all recent Debian-based distributions
   4.101 -(<ulink url="http://www.debian.org/">Debian</ulink>, <ulink url="http://www.ubuntu.com/">Ubuntu</ulink>, etc.).</para>
   4.102 -      </sect2>
   4.103 -
   4.104 -      <sect2 label="2.1.2">
   4.105 -        <title>Other *nix systems</title>
   4.106 -        <para>See <ulink url="files/">Files Section</ulink> for recent binary and source tarballs.</para>
   4.107 -        <para>Use the binary archive and extract it in a directory of your choice. Make sure your system
   4.108 -provides the necessary prerequisites:</para>
   4.109 -        <itemizedlist>
   4.110 -          <listitem>
   4.111 -            <para>Java6 compatible runtime (JRE)</para>
   4.112 -          </listitem>
   4.113 -          <listitem>
   4.114 -            <para>Java Mail API implementation, e.g. <ulink url="http://java.sun.com/products/javamail/">Sun Java Mail</ulink>.
   4.115 -GNU JavaMail has a broken POP3 Provider and does not work with sonews.</para>
   4.116 -          </listitem>
   4.117 -          <listitem>
   4.118 -            <para>JSP Servlet Container (e.g. 
   4.119 -            <ulink url="http://kitten.sonews.org/">Kitten</ulink>) [optional]</para>
   4.120 -          </listitem>
   4.121 -        </itemizedlist>
   4.122 -      </sect2>
   4.123 -    </sect1>
   4.124 -
   4.125 -    <sect1 label="2.2">
   4.126 -      <title>Initial database setup</title>
   4.127 -      <para>Before you start sonews, you must prepare the database. Currently sonews is known
   4.128 -to work with PostgreSQL and MySQL.</para>
   4.129 -      <para>It is highly recommended to create an own database for every sonews instance, e.g.
   4.130 -called 'sonews'. Additionally, it is recommended to create a unique database user
   4.131 -for sonews, e.g. 'sonewsuser'. Please do not use the root user for sonews!
   4.132 -The sonews user needs rights for SELECT, INSERT and UPDATE statements.
   4.133 -Refer to the database's manual for instructions.</para>
   4.134 -      <para>You will find the SQL Schema definitions in the helpers subdirectory of
   4.135 -the source and binary distributions. You can create the tables manually using
   4.136 -this templates or you can use the setup helper:</para>
   4.137 -      <screen>user@debian$ sonews setup</screen>
   4.138 -      <para>or on other *nix systems:</para>
   4.139 -      <screen>user@nix$ java -jar sonews.jar org.sonews.util.DatabaseSetup</screen>
   4.140 -      <para>The tool will ask for some information about your database environment,
   4.141 -connect to the database, create the tables and creates a default bootstrap
   4.142 -config file called sonews.conf.</para>
   4.143 -    </sect1>
   4.144 -  </chapter>
   4.145 -
   4.146 -  <chapter label="3">
   4.147 -    <title>Running sonews</title>
   4.148 -    <sect1 label="3.1">
   4.149 -      <title>Configuration</title>
   4.150 -      <para>There is a bootstrap configuration in /etc/sonews/sonews.conf and a regular configuration
   4.151 -in the database table config.</para>
   4.152 -      <para>There are various configuration values that can be adapted:</para>
   4.153 -      <variablelist>
   4.154 -        <varlistentry>
   4.155 -          <term>&lsquo;<literal>sonews.article.maxsize</literal>&rsquo;</term>
   4.156 -          <listitem>
   4.157 -            <para>Maximum allowed body size of a news message given in kilobytes. Please note that
   4.158 -for MySQL the &lsquo;<literal>max_allowed_packet</literal>&rsquo; configuration variable must
   4.159 -be set to a value higher than &lsquo;<literal>sonews.article.maxsize</literal>&rsquo; otherwise posting
   4.160 -of large mails will fail.</para>
   4.161 -          </listitem>
   4.162 -        </varlistentry>
   4.163 -          <varlistentry>
   4.164 -          <term>&lsquo;<literal>sonews.debug</literal>&rsquo;</term>
   4.165 -          <listitem>
   4.166 -            <para>
   4.167 -            If set to true every(!) data going through sonews' socket
   4.168 -            is written to sonews.log. After a high traffic night the logfile can be
   4.169 -            several gigabytes large, so be careful with this setting.
   4.170 -            </para>
   4.171 -          </listitem>
   4.172 -        </varlistentry>
   4.173 -        <varlistentry>
   4.174 -          <term>&lsquo;<literal>sonews.hostname</literal>&rsquo;</term>
   4.175 -          <listitem>
   4.176 -            <para>
   4.177 -              Canonical name of the server instance. This variable is part of
   4.178 -              the server's hello message to the client and used to generate
   4.179 -              Message-Ids.
   4.180 -              It is highly recommended to set sonews.hostname to the full
   4.181 -              qualified domain name (FQDN) of the host machine.
   4.182 -            </para>
   4.183 -          </listitem>
   4.184 -        </varlistentry>
   4.185 -        <varlistentry>
   4.186 -          <term>&lsquo;<literal>sonews.timeout</literal>&rsquo;</term>
   4.187 -          <listitem>
   4.188 -            <para>
   4.189 -              Socket timeout for client connections in seconds. Default as
   4.190 -              recommended in RFC3977 is 180 seconds.
   4.191 -            </para>
   4.192 -          </listitem>
   4.193 -        </varlistentry>
   4.194 -        <varlistentry>
   4.195 -          <term>&lsquo;<literal>sonews.port</literal>&rsquo;</term>
   4.196 -          <listitem>
   4.197 -            <para>
   4.198 -              Listening port of sonews daemon. This value can be overridden
   4.199 -              with the -p command line argument.
   4.200 -            </para>
   4.201 -          </listitem>
   4.202 -        </varlistentry>
   4.203 -        <varlistentry>
   4.204 -          <term>&lsquo;<literal>sonews.xdaemon.host</literal>&rsquo;</term>
   4.205 -          <listitem>
   4.206 -            <para>
   4.207 -              Hostname or IP address of the client machine that is allowed to
   4.208 -              use the XDAEMON command. Default: localhost
   4.209 -            </para>
   4.210 -          </listitem>
   4.211 -        </varlistentry>
   4.212 -      </variablelist>
   4.213 -    </sect1>
   4.214 -
   4.215 -    <sect1 label="3.2">
   4.216 -      <title>Command line arguments</title>
   4.217 -      <para>If you like to start sonews directly, you can use one of the following
   4.218 -arguments:</para>
   4.219 -      <screen>java -jar sonews.jar [arguments]
   4.220 -        where arguments:
   4.221 -    -c|-config         &lt;path to config file&gt; if custom config file preferred
   4.222 -    -dumpjdbcdriver    Prints out a list of available JDBC drivers
   4.223 -    -feed              Enables feed daemon for pulling news from peer servers
   4.224 -    -h|-help           This output
   4.225 -    -mlgw              Enables the Mailinglist Gateway poller
   4.226 -    -p portnumber      Port on which sonews is listening for incoming connections.
   4.227 -                       Overrides port settings in config file and database.</screen>
   4.228 -    </sect1>
   4.229 -
   4.230 -    <sect1 label="3.3">
   4.231 -      <title>Webinterface</title>
   4.232 -      <para>The package sonews-web provides an optional webinterface that can be used to
   4.233 -review statistical information and configuration values of sonews.</para>
   4.234 -      <screen>sonews-web start|stop</screen>
   4.235 -      <para>The webinterface uses the the lightweight Servlet Container Kitten and is
   4.236 -per default listening on HTTP-Port 8080 (go to http://localhost:8080/sonews).</para>
   4.237 -    </sect1>
   4.238 -
   4.239 -    <sect1 label="3.4">
   4.240 -      <title>Newsgroup configuration</title>
   4.241 -      <para>
   4.242 -        Currently some manual work is necessary to create a newsgroup hosted
   4.243 -        by a sonews instance.
   4.244 -      </para>
   4.245 -      <para>
   4.246 -        One possibility is to talk via Telnet to the sonews instance and
   4.247 -        use the non-standard command XDAEMON.
   4.248 -      <screen>telnet localhost 119</screen>
   4.249 -      <screen>XDAEMON GROUPADD local.test 0</screen>
   4.250 -      Please note that the XDAEMON command has restricted access and is only
   4.251 -      available via local connections (default, can be changed with config
   4.252 -      value sonews.xdaemon.host).
   4.253 -      </para>
   4.254 -      <para>
   4.255 -        You can also use the web interface to create newsgroups.
   4.256 -      </para>
   4.257 -    </sect1>
   4.258 -  </chapter>
   4.259 -
   4.260 -  <chapter label="4">
   4.261 -    <title>Development</title>
   4.262 -    <para>You're welcome to create patches with bugfixes or additional features. The
   4.263 -Mercurial DSCM makes this step an easy task.</para>
   4.264 -    <para>Just clone the public <ulink url="http://www.selenic.com/mercurial/">Mercurial</ulink> repository:</para>
   4.265 -    <screen>hg clone http://code.xerxys.info:8000/hg/sonews/ sonews-trunk</screen>
   4.266 -    <para>Then make your changes, create a bundle of changesets and send this to me via email.
   4.267 -Or ask for push access to the public repository.</para>
   4.268 -    <para>
   4.269 -        There is a nightly generated <ulink url="apidoc/">Javadoc API documentation</ulink> that will help
   4.270 -        you to get in touch with the sonews source.
   4.271 -    </para>
   4.272 -    <para>Some debugging hints: if the server blocks and does not longer respond you
   4.273 -probably found a deadlock. Do not kill the process with "kill -9 &lt;pid&gt;"
   4.274 -but send a SIGQUIT signal with "kill -3 &lt;pid&gt;" and the Java VM will output
   4.275 -a stracktrace of all threads. This output is the most valuable information to
   4.276 -fix the deadlock.</para>
   4.277 -
   4.278 -    <sect1 label="4.1">
   4.279 -      <title>Contributors</title>
   4.280 -      <para>Maintainer and project lead:
   4.281 -Christian Lins (contact christian.lins (at) fh-osnabrueck.de)</para>
   4.282 -    </sect1>
   4.283 -
   4.284 -    <sect1 label="4.2">
   4.285 -      <title>Sponsors</title>
   4.286 -      <para>The author thanks <ulink url="http://www.sun.com/">Sun Microsystems</ulink> for fully
   4.287 -financing the first version of sonews. A really free software supporting company!</para>
   4.288 -      <para>If you like to support sonews with a donation of any kind (hardware, books, money, donuts,...),
   4.289 - feel free to contact the project leader.
   4.290 -A friendly email or a bug report is most welcome, too :-)</para>
   4.291 -    </sect1>
   4.292 -  </chapter>
   4.293 -
   4.294 -  <chapter label="5">
   4.295 -    <title>Links and further information</title>
   4.296 -    <itemizedlist>
   4.297 -      <listitem>
   4.298 -        <para><ulink url="http://bugs.xerxys.info/">Bugtracker</ulink>, register necessary, see project 'sonews'.</para>
   4.299 -      </listitem>
   4.300 -      <listitem>
   4.301 -        <para><ulink url="http://www.sun.com/">Sun Microsystems</ulink>, friendly sponsor.</para>
   4.302 -      </listitem>
   4.303 -      <listitem>
   4.304 -        <para><ulink url="http://www.fh-osnabrueck">University of Applied Sciences Osnabrueck</ulink></para>
   4.305 -      </listitem>
   4.306 -    </itemizedlist>
   4.307 -  </chapter>
   4.308 -</book>