From bf878495985b81731c620bbac26df79e6c98c9fd Mon Sep 17 00:00:00 2001
From: Sebastian Pipping <sebastian@pipping.org>
Date: Sun, 25 Apr 2021 18:16:14 +0200
Subject: [PATCH] xmlwf.1: Document arguments -a and -b

---
 doc/xmlwf.xml | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/doc/xmlwf.xml b/doc/xmlwf.xml
index 5e2a4ae..648b581 100644
--- a/doc/xmlwf.xml
+++ b/doc/xmlwf.xml
@@ -3,7 +3,7 @@
   <!ENTITY dhfirstname "<firstname>Scott</firstname>">
   <!ENTITY dhsurname   "<surname>Bronson</surname>">
   <!-- Please adjust the date whenever revising the manpage. -->
-  <!ENTITY dhdate      "<date>March 11, 2016</date>">
+  <!ENTITY dhdate      "<date>May 4, 2021</date>">
   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
        allowed: see man(7), man(1). -->
   <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
@@ -140,6 +140,50 @@ supports both.
     <variablelist>
 
       <varlistentry>
+        <term><option>-a</option> <replaceable>factor</replaceable></term>
+        <listitem>
+          <para>
+            Sets the maximum tolerated amplification factor
+            for protection against billion laughs attacks (default: 100.0).
+            The amplification factor is calculated as ..
+          </para>
+          <literallayout>
+            amplification := (direct + indirect) / direct
+          </literallayout>
+          <para>
+            .. while parsing, whereas
+            &lt;direct&gt; is the number of bytes read
+              from the primary document in parsing and
+            &lt;indirect&gt; is the number of bytes
+              added by expanding entities and reading of external DTD files,
+              combined.
+          </para>
+          <para>
+            <emphasis>NOTE</emphasis>:
+            If you ever need to increase this value for non-attack payload,
+            please file a bug report.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-b</option> <replaceable>bytes</replaceable></term>
+        <listitem>
+          <para>
+            Sets the number of output bytes (including amplification)
+            needed to activate protection against billion laughs attacks
+            (default: 8 MiB).
+            This can be thought of as an &quot;activation threshold&quot;.
+          </para>
+          <para>
+            <emphasis>NOTE</emphasis>:
+            If you ever need to increase this value for non-attack payload,
+            please file a bug report.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>-c</option></term>
         <listitem>
 		<para>
@@ -434,6 +478,7 @@ http://www.xml.com/pub/a/tools/ruwf/check.html
 <literallayout>
 The Expat home page:        http://www.libexpat.org/
 The W3 XML specification:   http://www.w3.org/TR/REC-xml
+Billion laughs attack:      https://en.wikipedia.org/wiki/Billion_laughs_attack
 </literallayout>
 
 	</para>
-- 
1.8.3.1