svn commit: r54233 - head/en_US.ISO8859-1/books/porters-handbook/quick-porting

[Niclas Zeising]

Author: zeising
Date: Wed Jun 10 18:55:57 2020
New Revision: 54233
URL: https://svnweb.freebsd.org/changeset/doc/54233

Log:
  porters handbook: De-empasize the use of shar
  
  De-empasize the use of shar archives when submitting new ports.
  When we were still using gnats and CVS, shar was the best way of submitting
  new ports to the PR database, for inclusion in the ports tree.  These days,
  it is usually easier to use a patch from svn, or even git.
  
  Move the shar example further to the bottom of the page in the section about
  submitting ports to the FreeBSD project.
  
  Dicussed with:	many
  Reviewed by:	allanjude, bapt, bcr, emaste, mat
  Differential Revision:	https://reviews.freebsd.org/D25148

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml	Wed Jun 10 09:48:48 2020	(r54232)
+++ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml	Wed Jun 10 18:55:57 2020	(r54233)
@@ -358,7 +358,7 @@ lib/X11/oneko/mouse.xpm</programlisting>
 	now.</para>
     </important>
 
-    <para>Next, either create a &man.patch.1;, or a &man.shar.1; file.
+    <para>Next, create a &man.patch.1;, file.
       Assuming the port is called <literal>oneko</literal> and is in
       the <literal>games</literal> category.</para>
 
@@ -384,20 +384,7 @@ lib/X11/oneko/mouse.xpm</programlisting>
       </important>
     </example>
 
-    <example xml:id="porting-submitting-shar">
-      <title>Creating a <filename>.shar</filename> for a New
-	Port</title>
-
-      <para><command>cd</command> to the directory above where the
-	port directory is located, and use <command>shar</command> to
-	create the archive:</para>
-
-      <screen>&prompt.user; <userinput>cd ..</userinput>
-&prompt.user; <userinput>shar `find <replaceable>oneko</replaceable>` > <replaceable>oneko</replaceable>.shar</userinput></screen>
-    </example>
-
-    <para>Submit one of <filename>oneko.shar</filename> or
-      <filename>oneko.diff</filename> with the <link
+    <para>Submit <filename>oneko.diff</filename> with the <link
 	xlink:href="https://bugs.freebsd.org/submit/">bug submission
 	form</link>.  Use product <quote>Ports &
 	Packages</quote>, component <quote>Individual Port(s)</quote>,
@@ -405,7 +392,6 @@ lib/X11/oneko/mouse.xpm</programlisting>
       Add a short description of the program to the Description field
       of the PR (perhaps a short version of
       <varname>COMMENT</varname>), and remember to add
-      <filename>oneko.shar</filename> or
       <filename>oneko.diff</filename> as an attachment.</para>
 
     <note>
@@ -435,5 +421,21 @@ lib/X11/oneko/mouse.xpm</programlisting>
       added to the list of <link
 	xlink:href="&url.articles.contributors;/contrib-additional.html">Additional
 	&os; Contributors</link> and other files.</para>
+
+    <para>It is also possible to submit ports using a &man.shar.1; file.  Using
+      the previous example with the <literal>oneko</literal> port above.</para>
+
+    <example xml:id="porting-submitting-shar">
+    <title>Creating a <filename>.shar</filename> for a New Port</title>
+
+      <para>go to the directory above where the
+        port directory is located, and use <command>tar</command> to
+        create the shar archive:</para>
+
+        <screen>&prompt.user; <userinput>cd ..</userinput>
+	  &prompt.user; <userinput>tar cf <replaceable>oneko</replaceable>.shar --format shar <replaceable>oneko</replaceable></userinput></screen>
+    </example>
+    <para><filename>oneko.shar</filename> can then be submitted in the same way
+      as <filename>oneko.diff</filename> above.</para>
   </sect1>
 </chapter>