* Add section on editing the pkgsrc guide

 * Fix capitalisation to be have only the first letter capitalized
 * Mention the pkgsrc developers as contributors to the guide

8 files changed, 122 insertions, 17 deletions

diff --git a/doc/guide/Makefile b/doc/guide/Makefile
index 5b360a18ded..c6a7d7d7789 100644
--- a/doc/guide/Makefile
+++ b/doc/guide/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.3 2004/10/21 23:28:57 hubertf Exp $
+# $NetBSD: Makefile,v 1.4 2004/10/22 00:24:48 hubertf Exp $
 #
 
 DISTNAME=		htdocs-share-20041021
@@ -25,7 +25,7 @@ PLIST_SRC=		${WRKDIR}/PLIST_DYNAMIC
 DOCDIR=			${PREFIX}/share/doc/pkgsrc
 
 BUILD_DEFS+=		OUTPUTS
-OUTPUTS?=		html html-split ascii
+OUTPUTS?=		html html-split ascii pdf
 
 # the html is needed to build the ascii version.
 .if !empty(OUTPUTS:Mascii)
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index 4c2ed10da9e..a9733e8c07d 100644
--- a/doc/guide/files/chapters.ent
+++ b/doc/guide/files/chapters.ent
@@ -1,7 +1,7 @@
 <!--
 	Creates entities for each chapter in the pkgsrc book.
 
-	$NetBSD: chapters.ent,v 1.1.1.1 2004/10/21 14:27:37 grant Exp $
+	$NetBSD: chapters.ent,v 1.2 2004/10/22 00:24:48 hubertf Exp $
 -->
 
 <!-- users-guide -->
@@ -21,4 +21,5 @@
 <!ENTITY chap.examples			SYSTEM "examples.xml">
 <!ENTITY chap.logs			SYSTEM "logs.xml">
 <!ENTITY chap.ftp-layout		SYSTEM "ftp-layout.xml">
+<!ENTITY chap.editing			SYSTEM "editing.xml">
 <!ENTITY chap.platform			SYSTEM "platforms.xml">
diff --git a/doc/guide/files/editing.xml b/doc/guide/files/editing.xml
new file mode 100644
index 00000000000..65fd37d45b3
--- /dev/null
+++ b/doc/guide/files/editing.xml
@@ -0,0 +1,100 @@
+<!-- $NetBSD: editing.xml,v 1.1 2004/10/22 00:26:56 hubertf 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>
+    <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>, which replaces
+  	<filename>pkgsrc/Packages.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>
+    </itemizedlist>
+  </sect1>
+
+  <sect1>
+    <title>Procedure</title>
+    
+    <para>
+      The procedure to edit the pkgsrc guide is:
+    </para>
+  
+    <itemizedlist>
+      <listitem>
+        <para>
+          Edit the XML file(s) in <filename>pkgsrc/doc/guide/files</filename>
+        </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>
+          Run <command>make OUTPUT=pdf</command> in
+          <filename>pkgsrc/doc/guide</filename> to build the PDF
+          version. Dont' omit this, as this does a very strict SGML
+          test, and doing this properly is important for getting proper
+          documentation on the web server!
+        </para>
+      </listitem>
+      
+      <listitem>
+        <para>
+          If all is well, run <command>make install-doc</command> to put
+          the generated files into <filename>pkgserc/doc</filename>. 
+        </para>
+      </listitem>
+      
+      <listitem>
+        <para>
+          <command>cvs commit pkgsrc/doc/guide/files</command>
+        </para>
+      </listitem>
+      
+      <listitem>
+        <para>
+          <command>cvs commit pkgsrc/doc/pkgsrc.{html,txt}</command>
+        </para>
+      </listitem>
+      
+    </itemizedlist>
+
+  </sect1>   
+</appendix>
diff --git a/doc/guide/files/features.xml b/doc/guide/files/features.xml
index 40e37fbcc9d..1b20b5a729d 100644
--- a/doc/guide/files/features.xml
+++ b/doc/guide/files/features.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: features.xml,v 1.1.1.1 2004/10/21 14:27:38 grant Exp $ -->
+<!-- $NetBSD: features.xml,v 1.2 2004/10/22 00:24:48 hubertf Exp $ -->
 
 <chapter id="features"> <?dbhtml filename="features.html"?>
 <title>FAQs &amp; features of the package system</title>
@@ -421,7 +421,7 @@ with the older version <quote>Xaw3d-1.3</quote>.
 
 
 <sect1>
-<title>Software which has a WWW Home Page</title>
+<title>Software which has a homepage</title>
 
 <para>
 The NetBSD packages system now supports a variable called
diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index 313080b7355..e165fb65e2f 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.2 2004/10/22 00:24:48 hubertf Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>Notes on fixes for packages</title>
@@ -831,7 +831,7 @@ pre-configure:
     </sect2>
 
     <sect2>
-      <title>User Interaction</title>
+      <title>User interaction</title>
 
       <para>Occasionally, packages require interaction from the user, and this can be
         in a number of ways:</para>
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 751eb899c9d..3097428a5ec 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.2 2004/10/21 15:07:47 grant Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.3 2004/10/22 00:24:48 hubertf Exp $ -->
 <!-- From: -->
 <!-- NetBSD: Packages.txt,v 1.362 2004/10/16 00:41:40 dan Exp $ -->
 
@@ -16,7 +16,7 @@
 <book>
   <bookinfo>
     <title>The pkgsrc guide</title>
-    <subtitle>Documentation on the NetBSD package system</subtitle>
+    <subtitle>Documentation on the NetBSD packages system</subtitle>
 
     <authorgroup>
       <author>
@@ -36,6 +36,9 @@
 	  <address><email>hubertf@NetBSD.org</email></address>
 	</affiliation>
       </author>
+      <corpauthor>
+        The pkgsrc Developers
+      </corpauthor>
     </authorgroup>
 
     <copyright>
@@ -44,7 +47,7 @@
       <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.2 2004/10/21 15:07:47 grant Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.3 2004/10/22 00:24:48 hubertf Exp $</pubdate>
 
     <abstract>
       <para>Information about using the NetBSD package system (pkgsrc)
@@ -56,7 +59,7 @@
   &chap.intro;
 
   <part id="users-guide"> <?dbhtml filename="users-guide.html"?>
-    <title id="users-guide.title">pkgsrc user's guide</title>
+    <title id="users-guide.title">The pkgsrc user's guide</title>
 
     &chap.getting;
     &chap.platform;
@@ -67,7 +70,7 @@
 
   <!-- "part II" (we need to rid the documentation of this reference) -->
   <part id="developers-guide"> <?dbhtml filename="developers-guide.html"?>
-    <title id="developers-guide.title">pkgsrc developer's guide</title>
+    <title id="developers-guide.title">The pkgsrc developer's guide</title>
 
     &chap.components;
     &chap.plist;
@@ -83,4 +86,5 @@
   &chap.examples;
   &chap.logs;
   &chap.ftp-layout;
+  &chap.editing;
 </book>
diff --git a/doc/guide/files/platforms.xml b/doc/guide/files/platforms.xml
index cfa366c3f19..cd1b73b7a51 100644
--- a/doc/guide/files/platforms.xml
+++ b/doc/guide/files/platforms.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: platforms.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ -->
+<!-- $NetBSD: platforms.xml,v 1.2 2004/10/22 00:24:48 hubertf Exp $ -->
 
 <chapter id="platforms">
   <title>Using pkgsrc on systems other than &os;</title>
@@ -203,7 +203,7 @@
 	in 3.0/3.1 is lack of pthreads.)</para>
 
       <sect3 id="platform.interix-sfu-install">
-	<title>When Installing Interix/SFU</title>
+	<title>When installing Interix/SFU</title>
 
 	<para>At an absolute minimum, the following packages must be installed from
 	  the Windows Services for Unix 3.5 distribution in order to use pkgsrc:</para>
diff --git a/doc/guide/files/submit.xml b/doc/guide/files/submit.xml
index dbb4b20f76f..eb034c8829c 100644
--- a/doc/guide/files/submit.xml
+++ b/doc/guide/files/submit.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: submit.xml,v 1.1.1.1 2004/10/21 14:27:40 grant Exp $ -->
+<!-- $NetBSD: submit.xml,v 1.2 2004/10/22 00:24:48 hubertf Exp $ -->
 
 <chapter id="submit"> <?dbhtml filename="submit.html"?>
 <title>Submitting and Committing</title>
@@ -99,7 +99,7 @@ packages here:
 </sect1>
 
 <sect1>
-<title>Updating a Package to a Newer Version</title>
+<title>Updating a package to a newer version</title>
 <para>
   Please always put a concise, appropriate and relevant summary of the
   changes between old and new versions into the commit log when updating
@@ -143,7 +143,7 @@ packages here:
 </sect1>
 
 <sect1>
-<title>Moving a Package in pkgsrc</title>
+<title>Moving a package in pkgsrc</title>
 
 <orderedlist>
 <listitem><para>Make a copy of the directory somewhere else.</para></listitem>