From 862b2b51c6fc22b49f4d9909cd407fad919262c2 Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Thu, 1 Oct 2015 14:34:20 +0000
Subject: [PATCH] Restructurate the custom keywords section in subsections.

Reviewed by:	brd, wblock
Sponsored by:	Absolight
Differential Revision:	https://reviews.freebsd.org/D3755
---
 .../books/porters-handbook/plist/chapter.xml  | 85 ++++++++++++-------
 1 file changed, 56 insertions(+), 29 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
index 3b470afa65..e567182039 100644
--- a/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
@@ -667,14 +667,45 @@ PLIST_SUB+=	X11I386="@comment "
 	directory.  The settings for each keyword are stored in a
 	<acronym>UCL</acronym> file named
 	<filename><replaceable>keyword</replaceable>.ucl</filename>.
-	The file must contain at least one of the next
-	sections:</para>
+	The file must contain at least one of these sections:</para>
 
-      <variablelist>
-	<varlistentry xml:id="plist-keywords-attributes">
-	  <term><literal>attributes</literal></term>
+      <itemizedlist>
+	<listitem>
+	  <para><literal>attributes</literal></para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>action</literal></para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>pre-install</literal></para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>post-install</literal></para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>pre-deinstall</literal></para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>post-deinstall</literal></para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>pre-upgrade</literal></para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>post-upgrade</literal></para>
+	</listitem>
+      </itemizedlist>
+
+	<sect3 xml:id="plist-keywords-attributes">
+	  <title><literal>attributes</literal></title>
 
-	  <listitem>
 	    <para>Changes the owner, group, or mode used by the
 	      keyword.  Contains an associative array where the
 	      possible keys are <literal>owner</literal>,
@@ -683,13 +714,11 @@ PLIST_SUB+=	X11I386="@comment "
 	      and a file mode.  For example:</para>
 
 	    <programlisting>attributes: { owner: "games", group: "games", mode: 0555 }</programlisting>
-	  </listitem>
-	</varlistentry>
+	</sect3>
 
-	<varlistentry xml:id="plist-keywords-action">
-	  <term><literal>action</literal></term>
+	<sect3 xml:id="plist-keywords-action">
+	  <title><literal>action</literal></title>
 
-	  <listitem>
 	    <para>Defines what happens to the keyword's parameter.
 	      Contains an array where the possible values are:</para>
 
@@ -783,13 +812,11 @@ PLIST_SUB+=	X11I386="@comment "
 		</listitem>
 	      </varlistentry>
 	    </variablelist>
-	  </listitem>
-	</varlistentry>
+	</sect3>
 
-	<varlistentry xml:id="plist-keywords-arguments">
-	  <term><literal>arguments</literal></term>
+	<sect3 xml:id="plist-keywords-arguments">
+	  <title><literal>arguments</literal></title>
 
-	  <listitem>
 	    <para>If set to <literal>true</literal>, adds argument
 	      handling, splitting the whole line, <literal>%@</literal>,
 	      into numbered arguments, <literal>%1</literal>,
@@ -810,18 +837,16 @@ other.content</programlisting>
 	      argument number must be specified.  For example:</para>
 
 	    <programlisting>actions: [file(1)]</programlisting>
-	  </listitem>
-	</varlistentry>
+	</sect3>
 
-	<varlistentry xml:id="plist-keywords-pre-post">
-	  <term><literal>pre-install</literal></term>
-	  <term><literal>post-install</literal></term>
-	  <term><literal>pre-deinstall</literal></term>
-	  <term><literal>post-deinstall</literal></term>
-	  <term><literal>pre-upgrade</literal></term>
-	  <term><literal>post-upgrade</literal></term>
+	<sect3 xml:id="plist-keywords-pre-post">
+	  <title><literal>pre-install</literal>,
+	    <literal>post-install</literal>,
+	    <literal>pre-deinstall</literal>,
+	    <literal>post-deinstall</literal>,
+	    <literal>pre-upgrade</literal>,
+	    <literal>post-upgrade</literal></title>
 
-	  <listitem>
 	    <para>These keywords contains a &man.sh.1; script to be
 	      executed before or after installation, deinstallation,
 	      or upgrade of the package.  In addition to the usual
@@ -831,9 +856,10 @@ other.content</programlisting>
 		linkend="plist-keywords-base-exec"/>, there is a new
 	      one, <literal>%@</literal>, which represents the
 	      argument of the keyword.</para>
-	  </listitem>
-	</varlistentry>
-      </variablelist>
+	</sect3>
+
+      <sect3 xml:id="plist-keywords-examples">
+	<title>Custom Keyword Examples</title>
 
       <example xml:id="plist-keywords-fc-example">
 	<title>Example of a <literal>@dirrmtryecho</literal>
@@ -888,6 +914,7 @@ pre-deinstall: &lt;&lt;EOD
   fi
 EOD</programlisting>
       </example>
+      </sect3>
     </sect2>
   </sect1>
 </chapter>