doc/guide: merge debug chapter into creating

That chapter was not really about debugging pkgsrc but about creating a
package.

5 files changed, 57 insertions, 152 deletions

diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index 4c33acfbfd8..8e2e23c2370 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.20 2020/01/04 12:14:22 ryoon Exp $
+# $NetBSD: Makefile,v 1.21 2020/06/20 05:31:10 rillig Exp $
 
 WEB_PREFIX?=		${.CURDIR}/../htdocs
 DBX_XML_CATALOG?=	${SGML_PREFIX}/docbook/4.5/catalog.xml
@@ -15,7 +15,6 @@ SRCS+=	bulk.xml
 SRCS+=	creating.xml
 SRCS+=	components.xml
 SRCS+=	configuring.xml
-SRCS+=	debug.xml
 SRCS+=	devfaq.xml
 SRCS+=	editing.xml
 SRCS+=	examples.xml
diff --git a/doc/guide/files/creating.xml b/doc/guide/files/creating.xml
index f528731a57c..814f6553198 100644
--- a/doc/guide/files/creating.xml
+++ b/doc/guide/files/creating.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: creating.xml,v 1.33 2020/04/29 23:24:43 gutteridge Exp $ -->
+<!-- $NetBSD: creating.xml,v 1.34 2020/06/20 05:31:10 rillig Exp $ -->
 
 <chapter id="creating">
 <title>Creating a new pkgsrc package from scratch</title>
@@ -10,15 +10,30 @@ few steps.</para>
 
 <procedure>
 
-<step><para>First, install the packages <filename
-role="pkg">pkgtools/url2pkg</filename> and <filename
-role="pkg">pkgtools/pkglint</filename>.</para></step>
+<step><para>In your &mk.conf;, set <code>PKG_DEVELOPER=yes</code> to
+enable the basic quality checks.</para></step>
 
-<step><para>Then, choose one of the top-level directories as the
-category in which you want to place your package. You can also create a
-directory of your own (maybe called <filename>local</filename>). In that
-category directory, create another directory for your package and change
-into it.</para></step>
+<step><para>Install the package <filename
+role="pkg">meta-pkgs/pkg_developer</filename>, which among others will
+install the utilities <command>url2pkg</command>,
+<command>pkglint</command>, <command>pkgvi</command> and
+<command>mkpatches</command>:</para>
+
+<screen>&uprompt; <userinput>cd /usr/pkgsrc</userinput>
+&uprompt; <userinput>(cd meta-pkgs/pkg_developer &amp;&amp; bmake update)</userinput></screen>
+
+</step>
+
+<step><para>Choose one of the top-level directories as the category in
+which you want to place your package. You can also create a directory of
+your own (maybe called <filename>local</filename>). In that category
+directory, create another directory for your package and change into
+it:</para>
+
+<screen>&uprompt; <userinput>mkdir <replaceable>category</replaceable>/<replaceable>package</replaceable></userinput>
+&uprompt; <userinput>cd <replaceable>category</replaceable>/<replaceable>package</replaceable></userinput></screen>
+
+</step>
 
 <step><para>Run the program <command>url2pkg</command>, which will ask
 you for a URL. Enter the URL of the distribution file (in most cases a
@@ -26,7 +41,11 @@ you for a URL. Enter the URL of the distribution file (in most cases a
 of your package are created automatically. The distribution file is
 extracted automatically to fill in some details in the
 <filename>Makefile</filename> that would otherwise have to be done
-manually.</para></step>
+manually:</para>
+
+<screen>&uprompt; <userinput>url2pkg <replaceable>https://www.example.org/packages/package-1.0.tar.gz</replaceable></userinput></screen>
+
+</step>
 
 <step><para>Examine the extracted files to determine the dependencies of
 your package. Ideally, this is mentioned in some
@@ -77,9 +96,8 @@ DEPENDS+=       screen>=4.0:../../misc/screen
 <step><para>Run <command>pkglint</command> to see what things still need
 to be done to make your package a <quote>good</quote> one. If you don't
 know what pkglint's warnings want to tell you, try <command>pkglint
---explain</command> or <command>pkglint
--e</command>, which outputs additional
-explanations.</para></step>
+--explain</command> or <command>pkglint -e</command>, which outputs
+additional explanations.</para></step>
 
 <step><para>In many cases the package is not yet ready to build. You can
 find instructions for the most common cases in the next section, <xref
@@ -94,7 +112,17 @@ directory, which may become wrong after you edited the
 
 <step><para>Now, run <command>bmake</command> to build the package. For
 the various things that can go wrong in this phase, consult <xref
-linkend="fixes"/>.</para></step>
+linkend="fixes"/>.</para>
+
+<para>If the extracted files from the package need to be fixed, run multiple rounds of these commands:</para>
+
+<screen>&uprompt; <userinput>make</userinput>
+&uprompt; <userinput>pkgvi ${WRKSRC}/some/file/that/does/not/compile</userinput>
+&uprompt; <userinput>mkpatches</userinput>
+&uprompt; <userinput>make mps</userinput>
+&uprompt; <userinput>make clean</userinput></screen>
+
+</step>
 
 <step><para>When the package builds fine, the next step is to install
 the package. Run <command>bmake install</command> and hope that
@@ -111,7 +139,7 @@ files looks plausible.</para></step>
 <filename>PLIST</filename> contains garbage or not.</para></step>
 
 <step><para>When you ran <command>bmake install</command>, the package
-has been registered in the database of installed files, but with an
+had been registered in the database of installed files, but with an
 empty list of files. To fix this, run <command>bmake deinstall</command>
 and <command>bmake install</command> again. Now the package is
 registered with the list of files from
@@ -120,6 +148,15 @@ registered with the list of files from
 <step><para>Run <command>bmake package</command> to create a binary
 package from the set of installed files.</para></step>
 
+<step><para>Run <command>bmake clean update</command> to run everything
+from above again in a single step, making sure that the PLIST is correct
+and the whole package is created as intended.</para></step>
+
+<step><para>Run <command>pkglint</command> to see if there's anything left to do.</para></step>
+
+<step><para>Commit the package to pkgsrc-wip or main pkgsrc; see <xref
+linkend="submit"/>.</para></step>
+
 </procedure>
 
 <sect1 id="creating.common">
diff --git a/doc/guide/files/debug.xml b/doc/guide/files/debug.xml
deleted file mode 100644
index cb007143dd6..00000000000
--- a/doc/guide/files/debug.xml
+++ /dev/null
@@ -1,130 +0,0 @@
-<!-- $NetBSD: debug.xml,v 1.8 2020/02/24 21:13:56 rillig Exp $ -->
-
-<chapter id="debug">
-  <title>Debugging</title>
-
-  <para>To check out all the gotchas when building a package, here are
-  the steps that I do in order to get a package working.  Please note
-  this is basically the same as what was explained in the previous
-  sections, only with some debugging aids.</para>
-
-  <itemizedlist>
-    <listitem>
-      <para>Be sure to set <varname>PKG_DEVELOPER=yes</varname> in &mk.conf;.</para>
-    </listitem>
-
-    <listitem>
-      <para>Install <filename role="pkg">pkgtools/url2pkg</filename>,
-      create a directory for a new package, change into it, then run
-      <command>url2pkg</command>:</para>
-
-      <screen>&cprompt; <userinput>mkdir /usr/pkgsrc/<replaceable>category</replaceable>/<replaceable>examplepkg</replaceable></userinput>
-&cprompt; <userinput>cd /usr/pkgsrc/<replaceable>category</replaceable>/<replaceable>examplepkg</replaceable></userinput>
-&cprompt; <userinput>url2pkg https://www.example.com/path/to/distfile.tar.gz</userinput></screen>
-    </listitem>
-
-    <listitem>
-      <para>Edit the <filename>Makefile</filename> as requested.</para>
-    </listitem>
-
-    <listitem>
-      <para>Fill in the <filename>DESCR</filename> file</para>
-    </listitem>
-
-    <listitem>
-      <para>Run <command>make configure</command></para>
-    </listitem>
-
-    <listitem>
-      <para>Add any dependencies glimpsed from documentation and the
-      configure step to the package's
-      <filename>Makefile</filename>.</para>
-    </listitem>
-
-    <listitem>
-      <para>Make the package compile, doing multiple rounds of</para>
-
-      <screen>&cprompt; <userinput>make</userinput>
-&cprompt; <userinput>pkgvi ${WRKSRC}/some/file/that/does/not/compile</userinput>
-&cprompt; <userinput>mkpatches</userinput>
-&cprompt; <userinput>patchdiff</userinput>
-&cprompt; <userinput>mv ${WRKDIR}/.newpatches/* patches</userinput>
-&cprompt; <userinput>make mps</userinput>
-&cprompt; <userinput>make clean</userinput></screen>
-
-      <para>Doing this step as non-root user will ensure that no files
-      are modified that shouldn't be, especially during the build
-      phase.  <command>mkpatches</command>,
-      <command>patchdiff</command> and <command>pkgvi</command> are
-      from the <filename role="pkg">pkgtools/pkgdiff</filename>
-      package.</para>
-    </listitem>
-
-    <listitem>
-      <para>Look at the <filename>Makefile</filename>, fix if
-      necessary; see <xref linkend="components.Makefile"/>.</para>
-    </listitem>
-
-    <listitem>
-      <para>Generate a <filename>PLIST</filename>:</para>
-
-      <screen>&rprompt; <userinput>make install</userinput>
-&rprompt; <userinput>make print-PLIST &gt;PLIST</userinput>
-&rprompt; <userinput>make deinstall</userinput>
-&rprompt; <userinput>make install</userinput>
-&rprompt; <userinput>make deinstall</userinput></screen>
-
-      <para>You usually need to be <username>root</username> to do
-      this.  Look if there are any files left:</para>
-
-      <screen>&rprompt; <userinput>make print-PLIST</userinput></screen>
-
-      <para>If this reveals any files that are missing in
-      <filename>PLIST</filename>, add them.</para>
-    </listitem>
-
-    <listitem>
-      <para>Now that the <filename>PLIST</filename> is OK, install the
-      package again and make a binary package:</para>
-
-      <screen>&rprompt; <userinput>make reinstall</userinput>
-&rprompt; <userinput>make package</userinput></screen>
-    </listitem>
-
-    <listitem>
-      <para>Delete the installed package:</para>
-
-      <screen>&rprompt; <userinput>pkg_delete <replaceable>examplepkg</replaceable></userinput></screen>
-    </listitem>
-
-    <listitem>
-      <para>Repeat the above <command>make print-PLIST</command>
-      command, which shouldn't find anything now:</para>
-
-      <screen>&rprompt; <userinput>make print-PLIST</userinput></screen>
-    </listitem>
-
-    <listitem>
-      <para>Reinstall the binary package:</para>
-
-      <screen>&rprompt; <userinput>pkg_add .../<replaceable>examplepkg</replaceable>.tgz</userinput></screen>
-    </listitem>
-
-    <listitem>
-      <para>Play with it.  Make sure everything works.</para>
-    </listitem>
-
-    <listitem>
-      <para>Run <command>pkglint</command> from <filename
-      role="pkg">pkgtools/pkglint</filename>, and fix the problems it
-      reports:</para>
-
-      <screen>&rprompt; <userinput>pkglint</userinput></screen>
-    </listitem>
-
-    <listitem>
-      <para>Submit (or commit, if you have cvs access); see <xref
-      linkend="submit"/>.</para>
-    </listitem>
-  </itemizedlist>
-</chapter>
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 96338d7001d..836433113d7 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<!-- $NetBSD: pkgsrc.xml,v 1.37 2020/06/20 04:52:26 rillig Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.38 2020/06/20 05:31:10 rillig Exp $ -->
 
 <!DOCTYPE book PUBLIC "-//NetBSD//DTD DocBook XML V4.5-Based DocBook Extension//EN" [
 
@@ -47,7 +47,7 @@
       <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.37 2020/06/20 04:52:26 rillig Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.38 2020/06/20 05:31:10 rillig Exp $</pubdate>
 
     <abstract>
 
@@ -97,7 +97,6 @@
     &chap.pkginstall;
     &chap.fixes;
     &chap.gnome;
-    &chap.debug;
     &chap.submit;
     &chap.devfaq;
   </part>
diff --git a/doc/guide/files/submit.xml b/doc/guide/files/submit.xml
index e4e970cae75..b7cd47e4306 100644
--- a/doc/guide/files/submit.xml
+++ b/doc/guide/files/submit.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: submit.xml,v 1.36 2020/04/29 23:09:48 gutteridge Exp $ -->
+<!-- $NetBSD: submit.xml,v 1.37 2020/06/20 05:31:10 rillig Exp $ -->
 
 <chapter id="submit"> <?dbhtml filename="submit.html"?>
 <title>Submitting and Committing</title>
@@ -20,7 +20,7 @@
 <title>Submitting source packages (for non-NetBSD-developers)</title>
 
 	<para>First, check that your package is complete, compiles and
-	runs well; see <xref linkend="debug"/> and the rest of this
+	runs well; see <xref linkend="creating"/> and the rest of this
 	document. Next, generate an uuencoded gzipped &man.tar.1;
 	archive that contains all files that make up the package.
 	Finally, send this package to the pkgsrc bug tracking system,