[3/3] route: update documentation

Submitted by Jonatan Schlag on June 7, 2017, 6:17 a.m.

Details

Message ID 1496816259-6219-3-git-send-email-jonatan.schlag@ipfire.org
State New
Headers show

Commit Message

Jonatan Schlag June 7, 2017, 6:17 a.m.
This patch updates the documentation to follow the change from route to route static.
The network-route manpage is now a generical one wich just list which types of routes we support like static or later dynamic.

In the network-route-static are the explanation for static routes.
This documents represents the previous network-route manpage .

Signed-off-by: Jonatan Schlag <jonatan.schlag@ipfire.org>
---
 Makefile.am                  |   1 +
 man/network-route-static.xml | 183 +++++++++++++++++++++++++++++++++++++++++++
 man/network-route.xml        | 108 +++----------------------
 3 files changed, 197 insertions(+), 95 deletions(-)
 create mode 100644 man/network-route-static.xml

Patch hide | download patch | download mbox

diff --git a/Makefile.am b/Makefile.am
index acf5a71..15a98e6 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -340,6 +340,7 @@  MANPAGES = \
 	man/network-port-batman-adv-port.8 \
 	man/network-quick-start.8 \
 	man/network-route.8 \
+	man/network-route-static.8
 	man/network-settings.8 \
 	man/network-zone.8 \
 	man/network-zone-6to4-tunnel.8 \
diff --git a/man/network-route-static.xml b/man/network-route-static.xml
new file mode 100644
index 0000000..d43eb62
--- /dev/null
+++ b/man/network-route-static.xml
@@ -0,0 +1,183 @@ 
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS/DTD DocBook XML V4.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="network-route-static">
+	<refentryinfo>
+		<title>network-route-static</title>
+		<productname>network</productname>
+
+		<authorgroup>
+			<author>
+				<contrib>Developer</contrib>
+				<firstname>Michael</firstname>
+				<surname>Tremer</surname>
+				<email>michael.tremer@ipfire.org</email>
+			</author>
+		</authorgroup>
+	</refentryinfo>
+
+	<refmeta>
+		<refentrytitle>network-route-static</refentrytitle>
+		<manvolnum>8</manvolnum>
+	</refmeta>
+
+	<refnamediv>
+		<refname>network-route-static</refname>
+		<refpurpose>Network Configuration Control Program</refpurpose>
+	</refnamediv>
+
+	<refsynopsisdiv>
+		<cmdsynopsis>
+			<command>network route static <arg choice="plain">COMMAND</arg></command>
+		</cmdsynopsis>
+	</refsynopsisdiv>
+
+	<refsect1>
+		<title>Description</title>
+
+		<para>
+			The <command>route static</command> helps to manage static routes.
+		</para>
+	</refsect1>
+
+	<refsect1>
+		<title>Commands</title>
+
+		<para>
+			The following commands are understood:
+		</para>
+
+		<variablelist>
+			<varlistentry>
+				<term>
+					<command>add <replaceable>NETWORK</replaceable> [<option>--gateway=GATEWAY</option>, <option>--unreachable</option>, <option>--prohibit</option>, <option>--blackhole</option>] [<option>--mtu=MTU</option>]</command>
+				</term>
+
+				<listitem>
+					<para>
+						A new route may be added by the <command>add</command> command.
+						It is always required to pass a valid network prefix
+						<replaceable>NETWORK</replaceable>, which can be either
+						IPv6 or IPv4.
+					</para>
+					<para>
+						For unicast routes, the <option>--gateway=GATEWAY</option>
+						option must be passed, where <varname>GATEWAY</varname>
+						is a valid IP address of the same protocol type as the
+						network prefix is.
+					</para>
+					<para>
+						Use <option>--unreachable</option>, <option>--prohibit</option>,
+						<option>--blackhole</option> can be used to create of that
+						type. See <emphasis>ROUTE TYPES</emphasis> below for more
+						information about these options.
+					</para>
+					<para>
+						The optional <option>--mtu=MTU</option> parameter defines the
+						MTU along the path to the destination and must be an integer
+						number. This will show you very detailed information about
+						the given device.
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term>
+					<command>remove <replaceable>NETWORK</replaceable></command>
+				</term>
+
+				<listitem>
+					<para>
+						A route can be removed with the command.
+					</para>
+					<para>
+						<replaceable>NETWORK</replaceable> is the network prefix
+						of an existing route.
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term>
+					<command>list [<option>--protocol=ipv6|ipv4</option>]</command>
+				</term>
+
+				<listitem>
+					<para>
+						Shows a list of all configured routes.
+					</para>
+					<para>
+						Pass the protocol option to filter the output only for the
+						given protocol.
+					</para>
+				</listitem>
+			</varlistentry>
+		</variablelist>
+	</refsect1>
+
+	<refsect1>
+		<title>Route Types</title>
+
+		<refsect2>
+			<title>unicast</title>
+
+			<para>
+				A unicast route is the most common route in routing tables.
+				It is a route to a destination network address, which describes
+				the path to the destination.
+				Use the <option>--gateway=GATEWAY</option> option to create such
+				a route.
+			</para>
+		</refsect2>
+
+		<refsect2>
+			<title>unreachable</title>
+
+			<para>
+				When a route is determined and the routing decision process
+				returns a destination with an unreachable route type, an ICMP
+				unreachable message is generated and returned to the source
+				address.
+			</para>
+		</refsect2>
+
+		<refsect2>
+			<title>prohibit</title>
+
+			<para>
+				This works like an <emphasis>unreachable</emphasis> route, but
+				the returned ICMP message is an ICMP prohibited message.
+			</para>
+		</refsect2>
+
+		<refsect2>
+			<title>blackhole</title>
+
+			<para>
+				Packets matching this kind of route are silently discarded.
+				There will be no ICMP message sent to the source and no packet
+				be forwarded.
+			</para>
+		</refsect2>
+	</refsect1>
+
+	<refsect1>
+		<title>See Also</title>
+
+		<para>
+			<citerefentry>
+				<refentrytitle>network</refentrytitle>
+				<manvolnum>8</manvolnum>
+			</citerefentry>,
+			<citerefentry>
+				<refentrytitle>network-route</refentrytitle>
+				<manvolnum>8</manvolnum>
+			</citerefentry>,
+			<citerefentry>
+				<refentrytitle>ip-route</refentrytitle>
+				<manvolnum>8</manvolnum>
+			</citerefentry>
+		</para>
+	</refsect1>
+</refentry>
diff --git a/man/network-route.xml b/man/network-route.xml
index cd49de7..207a5ce 100644
--- a/man/network-route.xml
+++ b/man/network-route.xml
@@ -37,7 +37,7 @@ 
 		<title>Description</title>
 
 		<para>
-			The <command>route</command> helps to manage static routes.
+			The <command>route</command> helps to manage routes.
 		</para>
 	</refsect1>
 
@@ -51,116 +51,34 @@ 
 		<variablelist>
 			<varlistentry>
 				<term>
-					<command>add <replaceable>NETWORK</replaceable> [<option>--gateway=GATEWAY</option>, <option>--unreachable</option>, <option>--prohibit</option>, <option>--blackhole</option>] [<option>--mtu=MTU</option>]</command>
+					<command>static</command>
 				</term>
 
 				<listitem>
 					<para>
-						A new route may be added by the <command>add</command> command.
-						It is always required to pass a valid network prefix
-						<replaceable>NETWORK</replaceable>, which can be either
-						IPv6 or IPv4.
-					</para>
-					<para>
-						For unicast routes, the <option>--gateway=GATEWAY</option>
-						option must be passed, where <varname>GATEWAY</varname>
-						is a valid IP address of the same protocol type as the
-						network prefix is.
-					</para>
-					<para>
-						Use <option>--unreachable</option>, <option>--prohibit</option>,
-						<option>--blackhole</option> can be used to create of that
-						type. See <emphasis>ROUTE TYPES</emphasis> below for more
-						information about these options.
-					</para>
-					<para>
-						The optional <option>--mtu=MTU</option> parameter defines the
-						MTU along the path to the destination and must be an integer
-						number. This will show you very detailed information about
-						the given device.
+						Static routes are managed by the <command>static</command> command
+						followed by the options for static routes which are described in:
+						<citerefentry>
+							<refentrytitle>network-route-static</refentrytitle>
+							<manvolnum>8</manvolnum>
+						</citerefentry>
 					</para>
 				</listitem>
 			</varlistentry>
-
-			<varlistentry>
-				<term>
-					<command>remove <replaceable>NETWORK</replaceable></command>
-				</term>
-
-				<listitem>
-					<para>
-						A route can be removed with the command.
-					</para>
-					<para>
-						<replaceable>NETWORK</replaceable> is the network prefix
-						of an existing route.
-					</para>
-				</listitem>
-			</varlistentry>
-
-			<varlistentry>
-				<term>
-					<command>list [<option>--protocol=ipv6|ipv4</option>]</command>
-				</term>
-
-				<listitem>
-					<para>
-						Shows a list of all configured routes.
-					</para>
-					<para>
-						Pass the protocol option to filter the output only for the
-						given protocol.
-					</para>
-				</listitem>
-			</varlistentry>
-		</variablelist>
+	</variablelist>
 	</refsect1>
 
 	<refsect1>
 		<title>Route Types</title>
 
 		<refsect2>
-			<title>unicast</title>
-
-			<para>
-				A unicast route is the most common route in routing tables.
-				It is a route to a destination network address, which describes
-				the path to the destination.
-				Use the <option>--gateway=GATEWAY</option> option to create such
-				a route.
-			</para>
-		</refsect2>
-
-		<refsect2>
-			<title>unreachable</title>
-
-			<para>
-				When a route is determined and the routing decision process
-				returns a destination with an unreachable route type, an ICMP
-				unreachable message is generated and returned to the source
-				address.
-			</para>
-		</refsect2>
-
-		<refsect2>
-			<title>prohibit</title>
-
-			<para>
-				This works like an <emphasis>unreachable</emphasis> route, but
-				the returned ICMP message is an ICMP prohibited message.
-			</para>
-		</refsect2>
-
-		<refsect2>
-			<title>blackhole</title>
+			<title>static</title>
 
 			<para>
-				Packets matching this kind of route are silently discarded.
-				There will be no ICMP message sent to the source and no packet
-				be forwarded.
+				A static route is a route which does not change when the network changes.
 			</para>
 		</refsect2>
-	</refsect1>
+</refsect1>
 
 	<refsect1>
 		<title>See Also</title>
@@ -171,7 +89,7 @@ 
 				<manvolnum>8</manvolnum>
 			</citerefentry>,
 			<citerefentry>
-				<refentrytitle>ip-route</refentrytitle>
+				<refentrytitle>network-route-static</refentrytitle>
 				<manvolnum>8</manvolnum>
 			</citerefentry>
 		</para>