From 774fa4fc7d3795471b48a76e5eda2f14b99afa97 Mon Sep 17 00:00:00 2001
From: Niclas Zeising <zeising@FreeBSD.org>
Date: Wed, 10 Jun 2020 18:55:57 +0000
Subject: [PATCH] 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
---
 .../quick-porting/chapter.xml                 | 34 ++++++++++---------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
index 2df723f156..849148758b 100644
--- a/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
@@ -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>` &gt; <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 &amp;
 	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>