documentation: entity tweaks

for instance, use | not , for alternatives

diff --git a/configs/d.ipsec.conf/conn/subnet.xml b/configs/d.ipsec.conf/conn/subnet.xml
index 090fef8dd69f34cbb91e4f62fa43c4d0054188cf..8fff5ed35149fe5840386d95ab058b11ade307f1 100644 (file)
--- a/configs/d.ipsec.conf/conn/subnet.xml
+++ b/configs/d.ipsec.conf/conn/subnet.xml
@@ -1,9 +1,9 @@
 <varlistentry id='conn.subnet'>
   <term>
-    <option>leftsubnet=&ip_selector;[,...]</option>
+    <option>leftsubnet=&ip_selector;,...</option>
   </term>
   <term>
-    <option>rightsubnet=&ip_selector;[,...]</option>
+    <option>rightsubnet=&ip_selector;,...</option>
   </term>
   <listitem>
     <para>

diff --git a/configs/d.ipsec.conf/conn/subnets.xml b/configs/d.ipsec.conf/conn/subnets.xml
index ad512b3df49a4c0f60aa3ff4ae9158b0bc7dafac..85fc592874c3bcc28dc245554d753ab12e77a170 100644 (file)
--- a/configs/d.ipsec.conf/conn/subnets.xml
+++ b/configs/d.ipsec.conf/conn/subnets.xml
@@ -1,15 +1,15 @@
 <varlistentry id='conn.subnets'>
   <term>
-    <option>leftsubnets=&ip_subnet;[,...]</option>
+    <option>leftsubnets=&ip_subnet;,...</option>
   </term>
   <term>
-    <option>rightsubnets=&ip_subnet;[,...]</option>
+    <option>rightsubnets=&ip_subnet;,...</option>
   </term>
   <listitem>
     <para>
       Specify multiple private subnets behind the participant,
       expressed as
-      <option>networkA</option><option>/</option><option>netmaskA</option>,<option>networkB</option><option>/</option><option>netmaskB</option><option>[,...]</option>.
+      <option>networkA</option><option>/</option><option>netmaskA</option>,<option>networkB</option><option>/</option><option>netmaskB</option><option>,...</option>.
       If both a <option>leftsubnets=</option> and
       <option>rightsubnets=</option> are defined, all combinations of
       subnet tunnels will be established as separate IPsec tunnels.

diff --git a/configs/d.ipsec.conf/conn/xauthby.xml b/configs/d.ipsec.conf/conn/xauthby.xml
index 3f8b1307b26b44dbd03ace3d7839b16a25c32e7e..0882baffbc93dcb7ae5e8ee17d822eb2aecfb40b 100644 (file)
--- a/configs/d.ipsec.conf/conn/xauthby.xml
+++ b/configs/d.ipsec.conf/conn/xauthby.xml
@@ -1,15 +1,15 @@
 <varlistentry id='conn.xauthby'>
   <term>
-    <option>xauthby=</option>
+    <option>xauthby=&xauthby_option;</option>
   </term>
   <listitem>
     <para>
       When IKEv1 XAUTH support is available, set the method used by
       XAUTH to authenticate the user with IKEv1. The currently
-      supported values are &filelit;, &pam;, and &alwaysok;.
+      supported values are &file;, &pam;, and &alwaysok;.
     </para>
     <para>
-      The default is &filelit;.
+      The default is &file;.
     </para>
     <para>
       The password file is located at

diff --git a/configs/d.ipsec.conf/sect/units.xml b/configs/d.ipsec.conf/sect/units.xml
index 979bc3f04a34bf63be0e9b6a2ce2515e2259e7ad..fe813f896912b68e5eed28c5130f8ad770209be0 100644 (file)
--- a/configs/d.ipsec.conf/sect/units.xml
+++ b/configs/d.ipsec.conf/sect/units.xml
@@ -1,6 +1,6 @@
 <refsect1 id='sect.units'>
   <title>
-    SPECIFYING UNITS
+    UNITS
   </title>
 
   <refsect2 id='unit_bytes'>
@@ -13,27 +13,27 @@
       following multipliers as a suffix:
       <variablelist>
        <varlistentry>
-         <term><option>KiB</option></term>
+         <term><literal>KiB</literal></term>
          <listitem><para>kilobytes (1024 bytes)</para></listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>MiB</option></term>
+         <term><literal>MiB</literal></term>
          <listitem><para>megabytes (1024*1024 bytes)</para></listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>GiB</option></term>
+         <term><literal>GiB</literal></term>
          <listitem><para>gigabytes (1024*1024*1024 bytes)</para></listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>TiB</option></term>
+         <term><literal>TiB</literal></term>
          <listitem><para>terabytes (1024*1024*1024*1024 bytes)</para></listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>PiB</option></term>
+         <term><literal>PiB</literal></term>
          <listitem><para>petabytes (1024*1024*1024*1024*1024 bytes)</para></listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>EiB</option></term>
+         <term><literal>EiB</literal></term>
          <listitem><para>exabytes (1024*1024*1024*1024*1024*1024 bytes)</para></listitem>
        </varlistentry>
       </variablelist>
@@ -50,35 +50,79 @@
       the following multipliers as a suffix:
       <variablelist>
        <varlistentry>
-         <term><option>us</option></term>
-         <listitem><para>microseconds (1/1000000 seconds)</para></listitem>
+         <term>
+           <literal>us</literal>
+         </term>
+         <listitem>
+           <para>
+             microseconds (1/1_000_000 seconds)
+           </para>
+         </listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>ms</option></term>
-         <listitem><para>milliseconds (1/1000 seconds)</para></listitem>
+         <term>
+           <literal>ms</literal>
+         </term>
+         <listitem>
+           <para>
+             milliseconds (1/1_000 seconds)
+           </para>
+         </listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>s</option></term>
-       <listitem><para>seconds</para></listitem></varlistentry>
-       <varlistentry><term><option>m</option></term>
-       <listitem><para>minutes (60 seconds)</para></listitem>
+         <term>
+           <literal>s</literal>
+         </term>
+         <listitem>
+           <para>
+             seconds
+           </para>
+         </listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>h</option></term>
-         <listitem><para>hours (60*60 seconds)</para></listitem>
+         <term>
+           <literal>m</literal>
+         </term>
+         <listitem>
+           <para>
+             minutes (60 seconds)
+           </para>
+         </listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>d</option></term>
-         <listitem><para>days (24*60*60 seconds)</para></listitem>
+         <term>
+           <literal>h</literal>
+         </term>
+         <listitem>
+           <para>
+             hours (60*60 seconds)
+           </para>
+         </listitem>
        </varlistentry>
        <varlistentry>
-         <term><option>w</option></term>
-         <listitem><para>weeks (7*24*60*60 seconds)</para></listitem>
+         <term>
+           <literal>d</literal>
+         </term>
+         <listitem>
+           <para>
+             days (24*60*60 seconds)
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>
+           <literal>w</literal>
+         </term>
+         <listitem>
+           <para>
+             weeks (7*24*60*60 seconds)
+           </para>
+         </listitem>
        </varlistentry>
       </variablelist>
-      For instance, 1ms and 1000us, 0.5s and 500ms, 1.5h and 90m, are
-      each equivalent.
+      For instance, the following are each equivalent: 1ms and 1000us;
+      0.5s and 500ms; 1.5h and 90m.
     </para>
-</refsect2>
+  </refsect2>
 
 </refsect1>

diff --git a/configs/d.ipsec.conf/setup/dnssec-anchors.xml b/configs/d.ipsec.conf/setup/dnssec-anchors.xml
index 7b0704980c50ec1b9c85263cabd4d8f20fad161a..756b0e7667c03a2facaece54ba028767645e2425 100644 (file)
--- a/configs/d.ipsec.conf/setup/dnssec-anchors.xml
+++ b/configs/d.ipsec.conf/setup/dnssec-anchors.xml
@@ -1,13 +1,12 @@
 <varlistentry id='setup.dnssec-anchors'>
   <term>
-    <option>dnssec-anchors=&file;</option>
+    <option>dnssec-anchors=&filename;</option>
   </term>
   <listitem>
     <para>
-      The location of the <replaceable>file</replaceable> containing
-      additional DNSSEC Trust Anchors.  This can be used when a
-      network is using split-DNS and the internal hierarchy is using
-      DNSSEC trust anchors.
+      The file containing additional DNSSEC Trust Anchors.  This can
+      be used when a network is using split-DNS and the internal
+      hierarchy is using DNSSEC trust anchors.
     </para>
     <para>
       There is no default value.

diff --git a/configs/d.ipsec.conf/setup/dnssec-rootkey-file.xml b/configs/d.ipsec.conf/setup/dnssec-rootkey-file.xml
index e5576df0372a4bc034c83e01751e9d587ae6139b..b7df5c329c15b5ab2bf4586c073ef3463bb66706 100644 (file)
--- a/configs/d.ipsec.conf/setup/dnssec-rootkey-file.xml
+++ b/configs/d.ipsec.conf/setup/dnssec-rootkey-file.xml
@@ -1,10 +1,10 @@
 <varlistentry id='setup.dnssec-rootkey-file'>
   <term>
-    <option>dnssec-rootkey-file=&file;</option>
+    <option>dnssec-rootkey-file=&filename;</option>
   </term>
   <listitem>
     <para>
-      The location of the DNSSEC root zone public key file.
+      The file that contains the DNSSEC root zone public key.
     </para>
     <para>
       The default is <filename>@@DEFAULT_DNSSEC_ROOTKEY_FILE@@</filename>.

diff --git a/configs/d.ipsec.conf/setup/logfile.xml b/configs/d.ipsec.conf/setup/logfile.xml
index a9280b04a418e60074f74a12f99aa860405beacc..4a4d74fff388555b77a6fbcc50ad57879eb4a6e0 100644 (file)
--- a/configs/d.ipsec.conf/setup/logfile.xml
+++ b/configs/d.ipsec.conf/setup/logfile.xml
@@ -1,11 +1,11 @@
 <varlistentry id='setup.logfile'>
   <term>
-    <option>logfile=&file;</option>
+    <option>logfile=&filename;</option>
   </term>
   <listitem>
     <para>
       Instead of logging using &syslog.2; log to the specified
-      &file;.
+      &filename;.
     </para>
   </listitem>
 </varlistentry>

diff --git a/configs/d.ipsec.conf/setup/secretsfile.xml b/configs/d.ipsec.conf/setup/secretsfile.xml
index ebbd32662efe840872414871080d2f804caac3ff..ac39d689c262d5217dbdd65fd154910a1694b7d8 100644 (file)
--- a/configs/d.ipsec.conf/setup/secretsfile.xml
+++ b/configs/d.ipsec.conf/setup/secretsfile.xml
@@ -1,12 +1,11 @@
 <varlistentry id='setup.secretsfile'>
   <term>
-    <option>secretsfile=&file;</option>
+    <option>secretsfile=&filename;</option>
   </term>
   <listitem>
     <para>
-      pathname of the file that stores the secret credentials such as
-      preshared keys (PSKs). See <option>man ipsec.secrets</option>
-      for the syntax.
+      The file that stores the secret credentials such as preshared
+      keys (PSKs). See &ipsec.secrets.5; for the file syntax.
     </para>
     <para>
       The default is <filename>@@IPSEC_SECRETS@@</filename>.

diff --git a/mk/entities.xml b/mk/entities.xml
index 377daab285fd6c4bf15102193180193296fe37fd..f4886fcc9eda369ad10689af830ff105bf1cb205 100644 (file)
--- a/mk/entities.xml
+++ b/mk/entities.xml
@@ -141,6 +141,8 @@
 
 <!-- literals and options accepted by ipsec.conf -->
 
+<!-- NOTE: FILE is the literal, FILENAME is the replaceable -->
+
 <!ENTITY ah '<literal>ah</literal>'>
 <!ENTITY all '<literal>all</literal>'>
 <!ENTITY alwaysok '<literal>alwaysok</literal>'>
@@ -153,7 +155,7 @@
 <!ENTITY either '<literal>either</literal>'>
 <!ENTITY esp '<literal>esp</literal>'>
 <!ENTITY fallback '<literal>fallback</literal>'>
-<!ENTITY filelit '<literal>file</literal>'>
+<!ENTITY file '<literal>file</literal>'>
 <!ENTITY force '<literal>force</literal>'>
 <!ENTITY get '<literal>get</literal>'>
 <!ENTITY hard '<literal>hard</literal>'>
@@ -181,24 +183,24 @@
 <!ENTITY unlimited '<literal>unlimited</literal>'>
 <!ENTITY yes '<literal>yes</literal>'>
 
-<!ENTITY yn_option '{&yes;,&no;}'>
-<!ENTITY yna_option '{&yes;,&no;,&auto;}'>
-<!ENTITY ddos_mode_option '{&busy;,&unlimited;,&auto;}'>
-<!ENTITY http_method_option '{&get;,&post;}'>
-<!ENTITY failureshunt_option '{&none;,&pass;,&drop;,&reject;}'>
-<!ENTITY negotiationshunt_option '{&hold;,&pass;}'>
-<!ENTITY nic_offload_option '{&no;,&crypto;,&packet;}'>
-<!ENTITY enable_tcp_option '{&no;,&fallback;,&yes;}'>
-<!ENTITY ppk_option '{&no;,&propose;,&yes;,&insist;,&never;}'>
-<!ENTITY xauthfail_option '{&hard;,&soft;}'>
-<!ENTITY xauthby_opion '{&filelit;,&pam;,&alwaysok;}'>
-<!ENTITY keyexchange_option '{&ikev1;,&ikev2;}'>
-<!ENTITY type_option '{&tunnel;,&transport;,&passthrough;,&drop;}'>
-<!ENTITY nat_ikev1_method_option '{&drafts;,&rfc;,&both;,&none;}'>
-<!ENTITY sendca_option '{&none;,&issuer;,&all;}'>
-<!ENTITY esn_option '{&yes;,&no;,&either;}'>
-<!ENTITY phase2_option '{&esp;,&ah;}'>
-<!ENTITY autheap_option '{&none;,&tls;}'>
+<!ENTITY yn_option '{&yes;|&no;}'>
+<!ENTITY yna_option '{&yes;|&no;|&auto;}'>
+<!ENTITY ddos_mode_option '{&busy;|&unlimited;|&auto;}'>
+<!ENTITY http_method_option '{&get;|&post;}'>
+<!ENTITY failureshunt_option '{&none;|&pass;|&drop;|&reject;}'>
+<!ENTITY negotiationshunt_option '{&hold;|&pass;}'>
+<!ENTITY nic_offload_option '{&no;|&crypto;|&packet;}'>
+<!ENTITY enable_tcp_option '{&no;|&fallback;|&yes;}'>
+<!ENTITY ppk_option '{&no;|&propose;|&yes;|&insist;|&never;}'>
+<!ENTITY xauthfail_option '{&hard;|&soft;}'>
+<!ENTITY xauthby_option '{&file;|&pam;|&alwaysok;}'>
+<!ENTITY keyexchange_option '{&ikev1;|&ikev2;}'>
+<!ENTITY type_option '{&tunnel;|&transport;|&passthrough;|&drop;}'>
+<!ENTITY nat_ikev1_method_option '{&drafts;|&rfc;|&both;|&none;}'>
+<!ENTITY sendca_option '{&none;|&issuer;|&all;}'>
+<!ENTITY esn_option '{&yes;|&no;|&either;}'>
+<!ENTITY phase2_option '{&esp;|&ah;}'>
+<!ENTITY autheap_option '{&none;|&tls;}'>
 
 <!-- -->
 
@@ -207,29 +209,29 @@
 <!ENTITY ip_endpoint '<replaceable>address</replaceable>:<replaceable>protocol</replaceable>/<replaceable>port</replaceable>]'>
 <!ENTITY ip_pool '<replaceable>address</replaceable>[/<replaceable>prefix</replaceable>[/<replaceable>subnet-mask</replaceable>]|<replaceable>address</replaceable>-<replaceable>address</replaceable>'>
 <!ENTITY ip_port '<replaceable>port</replaceable>'>
-<!ENTITY ip_protoport '<replaceable>protocol</replaceable>/<replaceable>port</replaceable>]'>
-<!ENTITY ip_range '{<replaceable>address</replaceable>[/<replaceable>prefix</replaceable>],<replaceable>address</replaceable>-<replaceable>address</replaceable>}'>
+<!ENTITY ip_protoport '<replaceable>protocol</replaceable>[/<replaceable>port</replaceable>]'>
+<!ENTITY ip_range '{<replaceable>address</replaceable>[/<replaceable>prefix</replaceable>]|<replaceable>address</replaceable>-<replaceable>address</replaceable>}'>
 <!ENTITY ip_selector '<replaceable>address</replaceable>[/<replaceable>prefix</replaceable>[/<replaceable>protocol</replaceable>][/<replaceable>port</replaceable>]'>
-<!ENTITY ip_subnet '<replaceable>address</replaceable>[/<replaceable>prefix</replaceable>'>
+<!ENTITY ip_subnet '<replaceable>address</replaceable>[/<replaceable>prefix</replaceable>]'>
 
+<!ENTITY filename '<filename><replaceable>file</replaceable></filename>'>
 <!ENTITY directory '<filename><replaceable>directory</replaceable></filename>'>
-<!ENTITY file '<filename><replaceable>file</replaceable></filename>'>
 <!ENTITY string '<replaceable>string</replaceable>'>
 <!ENTITY URI '<replaceable>URI</replaceable>'>
 
-<!ENTITY hostname '{<replaceable>hostname</replaceable>,&ip_address;}'>
+<!ENTITY hostname '{<replaceable>hostname</replaceable>|&ip_address;}'>
 
-<!ENTITY byte_count_unit '{<literal>KiB</literal>,<literal>MiB</literal>,<literal>GiB</literal>,<literal>TiB</literal>,<literal>PiB</literal>,<literal>EiB</literal>}'>
-<!ENTITY byte_count '<replaceable>bytes</replaceable>[&byte_count_unit;]'>
+<!ENTITY byte_count_unit '[<literal>KiB</literal>|<literal>MiB</literal>|<literal>GiB</literal>|<literal>TiB</literal>|<literal>PiB</literal>|<literal>EiB</literal>]'>
+<!ENTITY byte_count '<replaceable>bytes</replaceable>&byte_count_unit;'>
 
-<!ENTITY count_unit '{<literal>Ki</literal>,<literal>Mi</literal>,<literal>Gi</literal>,<literal>Ti</literal>,<literal>Pi</literal>,<literal>Ei</literal>}'>
-<!ENTITY count '<replaceable>count</replaceable>[&count_unit;]'>
+<!ENTITY count_unit '[<literal>Ki</literal>|<literal>Mi</literal>|<literal>Gi</literal>|<literal>Ti</literal>|<literal>Pi</literal>|<literal>Ei</literal>]'>
+<!ENTITY count '<replaceable>count</replaceable>&count_unit;'>
 
 <!ENTITY percent '<replaceable>percent</replaceable><literal>;&#37;</literal>'>
 
-<!ENTITY duration_unit '{<literal>us</literal>,<literal>ms</literal>,<literal>s</literal>,<literal>m</literal>,<literal>h</literal>,<literal>d</literal>,<literal>w</literal>}'>
-<!ENTITY seconds '<replaceable>seconds</replaceable>[&duration_unit;]'>
-<!ENTITY milliseconds '<replaceable>milliseconds</replaceable>[&duration_unit;]'>
+<!ENTITY duration_unit '<literal>us</literal>|<literal>ms</literal>|<literal>s</literal>|<literal>m</literal>|<literal>h</literal>|<literal>d</literal>|<literal>w</literal>]'>
+<!ENTITY seconds '<replaceable>seconds</replaceable>&duration_unit;'>
+<!ENTITY milliseconds '<replaceable>milliseconds</replaceable>&duration_unit;'>
 
 <!ENTITY yes '<literal>yes</literal>'>
 <!ENTITY no '<literal>no</literal>'>