svn commit: r53177 - head/en_US.ISO8859-1/books/porters-handbook/pkg-files

[Mathieu Arnold]

Author: mat
Date: Sat Jun 22 11:34:20 2019
New Revision: 53177
URL: https://svnweb.freebsd.org/changeset/doc/53177

Log:
  Update UCL examples of short and multiline strings
  
  Submitted by:	dbaio
  Differential Revision:	https://reviews.freebsd.org/D20666

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml	Fri Jun 21 19:59:19 2019	(r53176)
+++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml	Sat Jun 22 11:34:20 2019	(r53177)
@@ -164,39 +164,52 @@
 	</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>
+      <important>
+	<para>To preserve the compatibility with non
+	  <acronym>UCL</acronym> <filename>pkg-message</filename>
+	  files, the first line of a <acronym>UCL</acronym>
+	  <filename>pkg-message</filename> <emphasis>MUST
+	    be</emphasis> a single
+	  <quote><literal>[</literal></quote>, and the last line
+	  <emphasis>MUST be</emphasis> a single
+	  <quote><literal>]</literal></quote>.</para>
+      </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: "Always displayed"
+{
+  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><<</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: <<EOM
-Always displayed
+{
+  message: <<EOM
+Simple message
 EOM
 }
 ]</programlisting>
-
-	<para>The here document delimiter (<literal>EOM</literal>
-	  here) must be uppercase.</para>
-      </tip>
-
-      <warning>
-	<para>To preserve the compatibility with non
-	  <acronym>UCL</acronym> <filename>pkg-message</filename>
-	  files, the first line of a <acronym>UCL</acronym>
-	  <filename>pkg-message</filename> <emphasis>MUST
-	    be</emphasis> a single
-	  <quote><literal>[</literal></quote>, and the last line
-	  <emphasis>MUST be</emphasis> a single
-	  <quote><literal>]</literal></quote>.</para>
-      </warning>
+      </example>
 
       <example xml:id="porting-message-ucl-ex1">
 	<title>Always Display a Message</title>