Improve man pages
authorMichael Tremer <michael.tremer@ipfire.org>
Thu, 25 Sep 2014 12:50:27 +0000 (14:50 +0200)
committerMichael Tremer <michael.tremer@ipfire.org>
Thu, 25 Sep 2014 12:50:27 +0000 (14:50 +0200)
.gitignore
man/ddns.conf.xml
man/ddns.xml

index dc5d2d3..29e653d 100644 (file)
@@ -2,6 +2,8 @@
 /build-aux
 /ddns
 /ddns.conf
+/man/*.[0-9]
+/man/*.html
 /missing
 /src/ddns/__version__.py
 /tmp
index a00ccc6..9b113bc 100644 (file)
                                <surname>Schantl</surname>
                                <email>stefan.schantl@ipfire.org</email>
                        </author>
+
+                       <author>
+                               <contrib>Developer</contrib>
+                               <firstname>Michael</firstname>
+                               <surname>Tremer</surname>
+                               <email>michael.tremer@ipfire.org</email>
+                       </author>
                </authorgroup>
        </refentryinfo>
 
 
        <refnamediv>
                <refname>ddns.conf</refname>
-               <refpurpose>Configuration file for the DDNS update client.</refpurpose>
+               <refpurpose>Configuration file for the DDNS update client</refpurpose>
        </refnamediv>
 
        <refsect1>
                <title>Description</title>
 
                <para>
-                       The <filename>ddns.conf</filename> file is the main configuration file for the
-                       <command>ddns</command> update client. This file specifies some basic options
-                       for the programm and contain multiple sections which imply hostname and auth information
-                       for each used provider.
+                       The <filename>ddns.conf</filename> file is the main configuration file of the
+                       <command>ddns</command> update client.
+                       This file specifies runtime configuration parameters for the programm and
+                       contains configurations for dynamic host entries that are managed by
+                       <command>ddns</command>.
                </para>
 
                <para>
-                       Lines starting with a hash mark (''#'') and empty lines are ignored.
+                       The syntax of the configuration file is based on the INI configuration
+                       file format. Lines starting with hash (#) or semi-colon (;)
+                       are ignored.
                </para>
        </refsect1>
 
 
                                <listitem>
                                        <para>
-                                               Using this option allows the usage of a proxy server while
-                                               performing updates.
+                                               This option will configure the HTTP proxy server that is used to
+                                               communicate with the providers HTTP APIs.
                                        </para>
 
                                        <para>
                                                The proxy only can be contacted by using the HTTP protocol. The
-                                               server has to be specified by using its IP address and the used port.
-                                       </para>
-
-                                       <para>
-                                               Example: proxy = http://192.168.180.1:800
+                                               server has to be specified by using its IP address and port.
+                                               For example: <option>proxy = http://192.168.180.1:800</option>
                                        </para>
                                </listitem>
                        </varlistentry>
 
                        <varlistentry>
                                <term>
-                                       <option>guess_external_ip = [<emphasis>true</emphasis>|false]</option>
+                                       <option>guess_external_ip = [true|<emphasis>false</emphasis>]</option>
                                </term>
 
                                <listitem>
@@ -83,8 +90,9 @@
                                        </para>
 
                                        <para>
-                                               The default value if this setting is not configured is
-                                               <emphasis>true</emphasis>.
+                                               By default, this option is disabled and automatically enabled
+                                               if the client has only IP addresses defined in RFC1918 or
+                                               other reserved address space.
                                        </para>
                                </listitem>
                        </varlistentry>
                <title>Provider Configuration</title>
 
                <para>
-                       The DDNS client supports the configuration of an unlimited amount of entries on different providers.
-                       Each entry has to be configured as an own section which has to be initiated with the choosen FQDN
-                       (Fully Qualified Domain Name) inside of squared brackets.
+                       The DDNS client supports the configuration of an unlimited amount of entries for different providers.
+                       Each entry has to be configured as an own section named by the FQDN (Fully Qualified Domain Name)
+                       inside squared brackets.
                </para>
 
                <variablelist>
 
                                <listitem>
                                        <para>
-                                               Specifies the choosen FQDN composed of the hostname and the selected domain from the
-                                               desired dynamic DNS provider.
+                                               The FQDN of the dynamic host. This name will be resolved
+                                               by <command>ddns</command> and therfore must not be a handle or something
+                                               other than a FQDN.
                                        </para>
                                </listitem>
                        </varlistentry>
 
                                <listitem>
                                        <para>
-                                               The provider which is responsible for the configured FQDN.
+                                               The provider which is responsible for this host.
                                        </para>
 
                                        <para>
-                                               A list of all supported providers can be found in the <filename>ddns.conf.sample</filename>
-                                               or the <filename>README</filename> file shipped by the source code.
+                                               A list of all supported providers can be looked up by running
+                                               <command>ddns list-providers</command>.
                                        </para>
                                </listitem>
                        </varlistentry>
 
                                <listitem>
                                        <para>
-                                               The used username to authenticate against your providers update service.
+                                               The username to authenticate against the provider's update service.
                                        </para>
 
                                        <para>
                                                In most cases this will be the same username which can be used to login on
-                                               your providers webpage.
+                                               your provider's web page.
                                        </para>
                                </listitem>
                        </varlistentry>
 
                        <varlistentry>
                                <term>
-                                       <command>password = pass</command>
+                                       <command>password = password</command>
                                </term>
 
                                <listitem>
 
                                <listitem>
                                        <para>
-                                               Just the authentication token.
+                                               An authentication token.
                                        </para>
 
                                        <para>
-                                               If your dynamic DNS provider supports token-based auth, this method should
-                                               be prefered.
+                                               If your dynamic DNS provider supports token-based authentication,
+                                               this method should be prefered.
+                                               You do not need to specify the username if token-based authentication
+                                               is used.
                                        </para>
                                </listitem>
                        </varlistentry>
                <title>Examples</title>
 
                <example>
-                       <title>A provider which uses username and password for client authentication.</title>
+                       <title>For providers which use username and password for client authentication</title>
 
                        <simplelist>
                                <member>[somehost.provider.com]</member>
                </example>
 
                <example>
-                       <title>Provider which supports token based auth.</title>
+                       <title>For providers which supports token-based authentication</title>
 
                        <simplelist>
                                <member>[anotherhost.provider.com]</member>
                                <refentrytitle>ddns</refentrytitle>
                                <manvolnum>1</manvolnum>
                        </citerefentry>
-                       <citerefentry>
-                               <refentrytitle>ddns-devel</refentrytitle>
-                               <manvolnum>7</manvolnum>
-                       </citerefentry>
                </para>
        </refsect1>
 </refentry>
index 05f429a..dda4b94 100644 (file)
                                <surname>Schantl</surname>
                                <email>stefan.schantl@ipfire.org</email>
                        </author>
+
+                       <author>
+                               <contrib>Developer</contrib>
+                               <firstname>Michael</firstname>
+                               <surname>Tremer</surname>
+                               <email>michael.tremer@ipfire.org</email>
+                       </author>
                </authorgroup>
        </refentryinfo>
 
@@ -87,9 +94,7 @@
 
                                <listitem>
                                        <para>
-                                               Enables the debugging mode.
-                                               In this mode, there will be debug output on
-                                               the console and written to the log.
+                                               Enables the debugging output.
                                        </para>
                                </listitem>
                        </varlistentry>
                </para>
 
                <variablelist>
-                       <varlistentry>
-                               <term>
-                                       <command>update-all</command>
-                               </term>
-
-                               <listitem>
-                                       <para>
-                                               Update all configured dynamic DNS hosts.
-                                       </para>
-                               </listitem>
-                       </varlistentry>
 
                        <varlistentry>
                                <term>
-                                       <command>update <replaceable>HOSTNAME</replaceable></command>
+                                       <command>update <option>[--force]</option> <replaceable>HOSTNAME</replaceable></command>
                                </term>
 
                                <listitem>
                                        </para>
 
                                        <para>
-                                               Example: <command>ddns update somehost.provider.com</command>
+                                               When calling an update, the DDNS client automatically checks
+                                               if this update is required by testing whether the hostname points
+                                               to the current public IP address.
+                                               Therefore it is not guaranteed than an update is performed.
+                                       </para>
+
+                                       <para>
+                                               The <option>--force</option> switch can be used to skip that
+                                               check and perform an update. Please note that some providers
+                                               may block your account if unnecessary updates are repeatedly
+                                               performed.
                                        </para>
                                </listitem>
                        </varlistentry>
 
                        <varlistentry>
                                <term>
-                                       <option>--force</option>
+                                       <command>update-all <option>[--force]</option></command>
                                </term>
 
                                <listitem>
                                        <para>
-                                               When calling an update, the DDNS client automatically checks
-                                               if this update is required by testing whether the hostname points
-                                               to the current public IP address. If this test returns true, the call
-                                               can be droped and no request will be sent to the provider.
-                                       </para>
-
-                                       <para>
-                                               In cases an update request should be send nevertheless, the update can be
-                                               forced by using this switch.
+                                               Update all configured dynamic DNS hosts when an update is necessary.
                                        </para>
 
                                        <para>
-                                               Example: <command>ddns update somehost.provider.com --force</command> or
-                                               <command>ddns update-all --force</command>
+                                               The <option>--force</option> switch has the same effect as
+                                               with the <command>update</command> command.
                                        </para>
                                </listitem>
                        </varlistentry>
 
                                <listitem>
                                        <para>
-                                               Try to guess and print the hosts IPv4 and IPv6 addresses
-                                               based on the choosen method in the used config file.
+                                               Guesses the public IPv6 and IPv4 addresses with help of an
+                                               external server and prints them on the conole.
                                        </para>
-
-                                       <para>
-                                               The addresses can be obtained from the system or by
-                                               help of an external server. For systems behind a NAT the
-                                               second method is recommended.
-                                       </para>
-
-                                       <para>
-                                                For further details, please consult the
-                                                <citerefentry>
-                                                        <refentrytitle>ddns.conf</refentrytitle>
-                                                        <manvolnum>5</manvolnum>
-                                                </citerefentry>
-                                                manual page.
-                                        </para>
                                </listitem>
                        </varlistentry>
 
                                                This command will print out a list of all
                                                supported dynamic DNS providers.
                                        </para>
-
-                                       <para>
-                                               For details how to add support for new providers,
-                                               please consult the
-                                               <citerefentry>
-                                                       <refentrytitle>ddns-devel</refentrytitle>
-                                                       <manvolnum>7</manvolnum>
-                                               </citerefentry>
-                                               manual page.
-                                       </para>
                                </listitem>
                        </varlistentry>
                </variablelist>
                        <citerefentry>
                                <refentrytitle>ddns.conf</refentrytitle>
                                <manvolnum>5</manvolnum>
-                       </citerefentry>, 
-                       <citerefentry>
-                               <refentrytitle>ddns-devel</refentrytitle>
-                               <manvolnum>7</manvolnum>
                        </citerefentry>
                </para>
        </refsect1>