From 8d5b7e557b65cd547b55567ac3dfbb2ea3f65418 Mon Sep 17 00:00:00 2001
From: Phil Sutter <phil@nwl.cc>
Date: Mon, 12 Nov 2018 15:02:52 +0100
Subject: [PATCH] nft.8: Clarify 'index' option of add rule command

Documentation for add rule command might trick readers into believing
the optional 'index' argument does not need to be that of an existing
rule. This false assumption is fueled by the fact that iptables allows
to insert with last rule number + 1 to actually append to a chain.
Change the relevant sentence to clarify that.

While being at it, drop the deprecated 'position' option from
documentation - since this will likely go away at some point, don't
encourage users to use it although they should notice that they
shoudn't.

Signed-off-by: Phil Sutter <phil@nwl.cc>
Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
(cherry picked from commit f4e40e395af2b73cd72c5454e41fb879da8c5f61)

Conflicts:
	doc/nft.txt
-> Patch applied manually to doc/nft.xml from asciidoc source.

Signed-off-by: Phil Sutter <psutter@redhat.com>
---
 doc/nft.xml | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/doc/nft.xml b/doc/nft.xml
index 22d57ac630037..512724ed8f9a7 100644
--- a/doc/nft.xml
+++ b/doc/nft.xml
@@ -877,10 +877,7 @@ add table inet mytable
 				<replaceable>chain</replaceable>
 				<group choice="opt">
 					<arg>
-						<group choice="req">
-							<arg>handle</arg>
-							<arg>position</arg>
-						</group>
+						<literal>handle</literal>
 						<replaceable>handle</replaceable>
 					</arg>
 					<arg>
@@ -917,8 +914,8 @@ add table inet mytable
 		</para>
 		<para>
 			The <literal>add</literal> and <literal>insert</literal> commands support an optional
-			location specifier, which is either a <replaceable>handle</replaceable> of an existing
-			rule or an <replaceable>index</replaceable> (starting at zero).  Internally,
+			location specifier, which is either a <replaceable>handle</replaceable> or the
+			<replaceable>index</replaceable> (starting at zero) of an existing rule.  Internally,
 			rule locations are always identified by <replaceable>handle</replaceable> and the
 			translation from <replaceable>index</replaceable> happens in userspace. This has two
 			potential implications in case a concurrent ruleset change happens after the translation
@@ -935,8 +932,6 @@ add table inet mytable
 						Add a new rule described by the list of statements. The rule is appended to the
 						given chain unless a <literal>handle</literal> is specified, in which case the
 						rule is appended to the rule given by the <replaceable>handle</replaceable>.
-						The alternative name <literal>position</literal> is deprecated and should not be
-						used anymore.
 					</para>
 				</listitem>
 			</varlistentry>
-- 
2.19.0