Updated the chapter on editing the pkgsrc guide. It had been outdated.

1 files changed, 92 insertions, 140 deletions

diff --git a/doc/guide/files/editing.xml b/doc/guide/files/editing.xml
index 580a1f9afa2..68917f57c1a 100644
--- a/doc/guide/files/editing.xml
+++ b/doc/guide/files/editing.xml
@@ -1,143 +1,95 @@
-<!-- $NetBSD: editing.xml,v 1.10 2006/02/12 14:44:59 rillig Exp $ -->
+<!-- $NetBSD: editing.xml,v 1.11 2006/06/30 09:25:34 rillig Exp $ -->
 
 <appendix id="editing">
-  <title>Editing guidelines for the pkgsrc guide</title>
-
-  <para>
-    This section contains information on editing the pkgsrc guide
-    itself.
-  </para>
-
-  <sect1 id="targets">
-    <title>Targets</title>
-
-    <para>
-      The pkgsrc guide's source code is stored in
-      <filename>pkgsrc/doc/guide/files</filename>, and several files are
-      created from it:
-    </para>
-
-    <itemizedlist>
-      <listitem>
-        <para>
-          <filename>pkgsrc/doc/pkgsrc.txt</filename>
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <filename>pkgsrc/doc/pkgsrc.html</filename>
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <filename>http://www.NetBSD.org/Documentation/pkgsrc/</filename>:
-  	the documentation on the NetBSD website will be built from
-  	pkgsrc and kept up to date on the web server itself. This
-  	means you <emphasis>must</emphasis> make sure that your
-  	changes haven't broken the build!
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <filename>http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.pdf</filename>:
-  	  PDF version of the pkgsrc guide.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <filename>http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps</filename>:
-  	  PostScript version of the pkgsrc guide.
-        </para>
-      </listitem>
-    </itemizedlist>
-  </sect1>
-
-  <sect1 id="procedure">
-    <title>Procedure</title>
-
-    <para>
-      The procedure to edit the pkgsrc guide is:
-    </para>
-
-    <itemizedlist>
-      <listitem>
-        <para>
-          Make sure you have the packages needed to re-generate the
-          pkgsrc guide (and other XML-based NetBSD documentation)
-          installed. These are <quote>netbsd-doc</quote> for creating the
-          ASCII and HTML versions, and
-          <quote>netbsd-doc-print</quote> for the PostScript and PDF
-          versions. You will need both packages installed, to make sure
-          documentation is consistent across all formats. The packages
-          can be found in
-          <filename>pkgsrc/meta-pkgs/netbsd-doc</filename> and
-          <filename>pkgsrc/meta-pkgs/netbsd-doc-print</filename>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Edit the XML file(s) in
-          <filename>pkgsrc/doc/guide/files</filename>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Run <command>make extract &amp;&amp; make do-lint</command> in
-          <filename>pkgsrc/doc/guide</filename> to check the XML
-          syntax, and fix it if needed.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Run <command>make</command> in
-          <filename>pkgsrc/doc/guide</filename> to build the HTML and
-          ASCII version.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If all is well, run <command>make install-doc</command> to put
-          the generated files into <filename>pkgsrc/doc</filename>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <command>cvs commit pkgsrc/doc/guide/files</command>
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <command>cvs commit -m re-generate pkgsrc/doc/pkgsrc.{html,txt}</command>
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Until the webserver on www.NetBSD.org is really updated
-          automatically to pick up changes to the pkgsrc guide
-          automatically, also run <command>make install-htdocs
-          HTDOCSDIR=../../../htdocs</command> (or similar, adjust
-          <varname>HTDOCSDIR</varname>!).
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <command>cvs commit htdocs/Documentation/pkgsrc</command>
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-  </sect1>
+<title>Editing guidelines for the pkgsrc guide</title>
+
+	<para>This section contains information on editing the pkgsrc
+	guide itself.</para>
+
+<sect1 id="targets">
+<title>Make targets</title>
+
+	<para>The pkgsrc guide's source code is stored in
+	<filename>pkgsrc/doc/guide/files</filename>, and several files
+	are created from it:</para>
+
+	<itemizedlist>
+
+	<listitem><para><filename>pkgsrc/doc/pkgsrc.txt</filename></para></listitem>
+
+	<listitem><para><filename>pkgsrc/doc/pkgsrc.html</filename></para></listitem>
+
+	<listitem><para><ulink
+	url="http://www.NetBSD.org/Documentation/pkgsrc/"/></para></listitem>
+
+	<listitem><para><ulink
+	url="http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.pdf"/>:
+	The PDF version of the pkgsrc guide.</para></listitem>
+
+	<listitem><para><ulink
+	url="http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps"/>:
+	PostScript version of the pkgsrc guide.</para></listitem>
+
+	</itemizedlist>
+
+</sect1>
+<sect1 id="procedure">
+<title>Procedure</title>
+
+	<para>The procedure to edit the pkgsrc guide is:</para>
+
+	<procedure>
+
+	<step><para>Make sure you have the packages needed to
+	re-generate the pkgsrc guide (and other XML-based NetBSD
+	documentation) installed. These are <filename
+	role="pkg">meta-pkgs/netbsd-doc</filename> for creating the
+	ASCII and HTML versions, and <filename
+	role="pkg">meta-pkgs/netbsd-doc-print</filename> for the
+	PostScript and PDF versions. You will need both packages
+	installed, to make sure documentation is consistent across all
+	formats.</para></step>
+
+	<step><para>Run <command>cd doc/guide</command> to get to the
+	right directory. All further steps will take place
+	here.</para></step>
+
+	<step><para>Edit the XML file(s) in
+	<filename>files/</filename>.</para></step>
+
+	<step><para>Run <command>bmake</command> to check the pkgsrc
+	guide for valid XML and to build the final output files. If you
+	get any errors at this stage, you can just edit the files, as
+	there are only symbolic links in the working directory, pointing
+	to the files in <filename>files/</filename>.</para></step>
+
+	<step><para><command>(cd files &amp;&amp; cvs
+	commit)</command></para></step>
+
+	<step><para>Run <command>bmake clean && bmake</command> to
+	regenerate the output files with the proper RCS
+	Ids.</para></step>
+
+	<step><para>Run <command>(cd .. &amp;&amp; cvs update pkgsrc.*)
+	&amp;&amp; bmake install-doc</command> to put the generated
+	files into <filename>pkgsrc/doc</filename>.</para></step>
+
+	<step><para>Run <command>(cd .. &amp;&amp; cvs commit -m
+	"regenerated." pkgsrc.{html,txt})</command> to commit the
+	generated documentation.</para></step>
+
+	<step><para>Run <command>(cd
+	../../../htdocs/Documentation/pkgsrc &amp;&amp; cvs update)
+	&amp;&amp; bmake install-htdocs</command> to generate all the
+	files for the web server.</para></step>
+
+	<step><para>Run <command>(cd
+	../../../htdocs/Documentation/pkgsrc &amp;&amp; cvs commit -m
+	"regenerated.")</command> to update the files on the web server.
+	If you have added a chapter, don't forget to run <command>cvs
+	add *.html</command> before you commit the files.</para></step>
+
+	</procedure>
+
+</sect1>
 </appendix>