<pre style='margin:0'>
Ryan Schmidt (ryandesign) pushed a commit to branch master
in repository macports-guide.

</pre>
<p><a href="https://github.com/macports/macports-guide/commit/ff6ebb3794be11092c5f8108dddcd5557381e386">https://github.com/macports/macports-guide/commit/ff6ebb3794be11092c5f8108dddcd5557381e386</a></p>
<pre style="white-space: pre; background: #F8F8F8"><span style='display:block; white-space:pre;color:#808000;'>commit ff6ebb3794be11092c5f8108dddcd5557381e386
</span>Author: Ryan Schmidt <ryandesign@macports.org>
AuthorDate: Sat Aug 22 07:04:03 2020 -0500

<span style='display:block; white-space:pre;color:#404040;'>    Rewrite description and long_description sections
</span>---
 guide/xml/portfile-keywords.xml | 44 +++++++++++++++++++++++++++++++++++------
 1 file changed, 38 insertions(+), 6 deletions(-)

<span style='display:block; white-space:pre;color:#808080;'>diff --git a/guide/xml/portfile-keywords.xml b/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;color:#808080;'>index ea61b59..5f65529 100644
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>--- a/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>+++ b/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -279,9 +279,9 @@
</span>       <term>description</term>
 
       <listitem>
<span style='display:block; white-space:pre;background:#ffe0e0;'>-        <para>A one-sentence description of the ported software.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <para>A short sentence fragment describing the software.</para>
</span> 
<span style='display:block; white-space:pre;background:#ffe0e0;'>-        <programlisting>description         A classic shooter arcade game.</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <programlisting>description         a classic shooter arcade game</programlisting>
</span>       </listitem>
     </varlistentry>
 
<span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -289,12 +289,44 @@
</span>       <term>long_description</term>
 
       <listitem>
<span style='display:block; white-space:pre;background:#ffe0e0;'>-        <para>A long description of the ported software. Break long lines with
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-        escaped newlines.</para>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-        <programlisting>long_description    A classic shooter arcade game derived from \
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <para>One or more sentences describing the software.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <para>The long description can be based on a description provided by the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        upstream project (e.g., in its readme or on its web site) but avoid
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        repeating information already present elsewhere in the Portfile, such as
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        the software's license (see the <varname>license</varname> keyword) or
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        the platforms on which it runs (see the <varname>platforms</varname>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        keyword), and avoid including information irrelevant to a MacPorts user,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        such as compilation instructions or other steps the Portfile has already
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        performed for the user. More specific usage instructions are best left
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        to the <varname>notes</varname> keyword.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <para>If a port provides a program that is different from the port name,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        it can be a good idea to include the program name in the long
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        description so that a user could find it by searching.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <para>Long descriptions are usually a single paragraph. MacPorts will
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        word-wrap long lines to the terminal width as needed. Break long lines
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        with escaped newlines for better legibility within the Portfile. If
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        literal newlines need to be displayed to the user, they can be inserted
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        using <literal>\n</literal>. Place the <literal>\n</literal> at the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        beginning of the next line, not at the end of the previous line. To
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        create a new paragraph, insert two newlines.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <para>Sometimes the port's name and short description are reused as part
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        of the long description. When referencing the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <varname>description</varname> keyword (or any other list keyword with
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        more than one item), it should be preceded with the expand
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        operator.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <programlisting>long_description    ${name} is {*}${description} derived from \
</span>                     the game alien-munchers.  Not suitable for \
                     children under two years old.</programlisting>
<span style='display:block; white-space:pre;background:#e0ffe0;'>+        <programlisting>long_description    foobar provides the following programs: \
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+                    \n \
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+                    \n* foo, a lorem ipsum utility \
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+                    \n* bar, a high-performance amet consectetur \
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+                    \n* baz, an eiusmod tempor converter</programlisting>
</span>       </listitem>
     </varlistentry>
 
</pre><pre style='margin:0'>

</pre>