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

[Mathieu Arnold]

Author: mat
Date: Tue Jun 20 11:29:58 2017
New Revision: 50386
URL: https://svnweb.freebsd.org/changeset/doc/50386

Log:
  Turn the diff/shar creation into examples.
  
  Sponsored by:	Absolight

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	Tue Jun 20 11:29:55 2017	(r50385)
+++ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml	Tue Jun 20 11:29:58 2017	(r50386)
@@ -357,21 +357,45 @@ lib/X11/oneko/mouse.xpm</programlisting>
 	now.</para>
     </important>
 
-    <para>Next, build the &man.shar.1; file.  Assuming the port is
-      called <literal>oneko</literal>, <command>cd</command> to the
-      directory above where the <literal>oneko</literal> directory
-      is located, and then type:
-      <command>shar `find oneko` > oneko.shar</command></para>
+    <para>Next, either create a &man.patch.1;, or a &man.shar.1; file.
+      Assuming the port is called <literal>oneko</literal> and is in
+      the <literal>games</literal> category.</para>
 
-    <para>A diff created from a <application>Subversion</application>
-      checkout of the ports tree is also acceptable.  Add all the
-      files with <command>svn add</command>.  <command>cd</command> to
-      the base of the ports tree so full paths to the changed files
-      are included in the diff, then generate the diff with
-      <command>svn diff</command>.  For example, <command>svn diff
-	games/oneko > oneko.diff</command>.</para>
+    <example xml:id="porting-submitting-diff">
+      <title>Creating a <filename>.diff</filename> for a New
+	Port</title>
 
-    <para>Submit <filename>oneko.shar</filename> or
+      <para>Add all the files with <command>svn add</command>.
+	<command>cd</command> to the base of the ports tree so full
+	paths to the changed files are included in the diff, then
+	generate the diff with <command>svn diff</command>.  For
+	example:</para>
+
+      <screen>&prompt.user; <userinput>svn add .</userinput>
+&prompt.user; <userinput>cd ../..</userinput>
+&prompt.user; <userinput>svn diff <replaceable>games/oneko</replaceable> > <replaceable>oneko.diff</replaceable></userinput></screen>
+
+      <important>
+	<para>To make it easier for committers to apply the patch on
+	  their working copy of the ports tree, please generate the
+	  <filename>.diff</filename> from the base of your ports
+	  tree.</para>
+      </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
 	xlink:href="https://bugs.freebsd.org/submit/">bug submission
 	form</link>.  Use product <quote>Ports &