From a59f7f697d40835a8eb0f179f066dac5c3b5955d Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Sat, 22 Jun 2019 11:34:20 +0000
Subject: [PATCH] Update UCL examples of short and multiline strings

Submitted by:	dbaio
Differential Revision:	https://reviews.freebsd.org/D20666
---
 .../porters-handbook/pkg-files/chapter.xml    | 63 +++++++++++--------
 1 file changed, 38 insertions(+), 25 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
index f4ae15e2eb..83ddf81d14 100644
--- a/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
@@ -164,30 +164,7 @@
 	</varlistentry>
       </variablelist>
 
-      <tip>
-	<para>UCL allows for two kind of strings, either delimited
-	  by double quotes
-	  <literal>"<replaceable>foo</replaceable>"</literal>, or as a
-	  here document.  These two
-	  are equivalent:</para>
-
-	<programlisting>[
-{ message: "Always displayed"
-}
-]</programlisting>
-
-	<programlisting>[
-{ message: &lt;&lt;EOM
-Always displayed
-EOM
-}
-]</programlisting>
-
-	<para>The here document delimiter (<literal>EOM</literal>
-	  here) must be uppercase.</para>
-      </tip>
-
-      <warning>
+      <important>
 	<para>To preserve the compatibility with non
 	  <acronym>UCL</acronym> <filename>pkg-message</filename>
 	  files, the first line of a <acronym>UCL</acronym>
@@ -196,7 +173,43 @@ EOM
 	  <quote><literal>[</literal></quote>, and the last line
 	  <emphasis>MUST be</emphasis> a single
 	  <quote><literal>]</literal></quote>.</para>
-      </warning>
+      </important>
+
+      <example xml:id="porting-message-ucl-short-ex">
+	<title><acronym>UCL</acronym> Short Strings</title>
+
+	<para>The message is delimited by double quotes
+	  <literal>"</literal>, this is used for simple single line
+	  strings:</para>
+
+	<programlisting>[
+{
+  message: "Simple message"
+}
+]</programlisting>
+      </example>
+
+      <example xml:id="porting-message-ucl-multiline-ex">
+	<title><acronym>UCL</acronym> Multiline Strings</title>
+
+	<para>Multiline strings use the standard here document
+	  notation.  The multiline delimiter <emphasis>must</emphasis>
+	  start just after <literal>&lt;&lt;</literal> symbols without
+	  any whitespace and it <emphasis>must</emphasis> consist of
+	  capital letters only.  To finish a multiline string, add the
+	  delimiter string on a line of its own without any
+	  whitespace.  The message from <xref
+	  linkend="porting-message-ucl-short-ex"/> can be written
+	  as:</para>
+
+	<programlisting>[
+{
+  message: &lt;&lt;EOM
+Simple message
+EOM
+}
+]</programlisting>
+      </example>
 
       <example xml:id="porting-message-ucl-ex1">
 	<title>Always Display a Message</title>