<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>