Simplify getting instructions in the guide

To: tech-pkg%netbsd.org@localhost
Subject: Simplify getting instructions in the guide
From: Aleksej Saushev <asau%inbox.ru@localhost>
Date: Thu, 23 Dec 2010 07:41:23 +0300

  Hello!

Our guide is hard to comprehend, it is overloaded with useless
(or close to useless) information and thus is not helpful to
novice users. I propose to simplify "getting pkgsrc" part as
in patch attached.

I'd rather drop instructions how to use SUP, or move them to appendix
for the most curious. Do we have regular SUP users at all?

Prioritize: make CVS preferable to SUP.
Simplify CVS instructions:
- multiple steps are harder to understand than single step,
  and commands are black magic to novice user anyway;
- drop csh support, csh users have more troubles when following
  instructions already, they have to refer to their documentation;
- don't mention CVS_RSH, if there do exist systems that need this,
  there's text which is commented out;
- sort CVS subcommands in sample .cvsrc so that it could be more
  comprehensible (this should be moved into separate section in
  appendix or just go away).

Index: doc/guide/files/getting.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/getting.xml,v
retrieving revision 1.25
diff -u -r1.25 getting.xml
--- doc/guide/files/getting.xml 11 Oct 2009 20:50:48 -0000      1.25
+++ doc/guide/files/getting.xml 23 Dec 2010 04:30:18 -0000
@@ -24,8 +24,8 @@
        <literal>2009Q1</literal>.</para>
 
        <para>The second step is to decide <emphasis>how</emphasis> you
-       want to download pkgsrc. You can get it as a tar file, via SUP,
-       or via CVS. All three ways are described here.</para>
+       want to download pkgsrc. You can get it as a tar file, via CVS,
+       or via SUP. All three ways are described here.</para>
 
 <sect2 id="getting-via-tar">
 <title>As tar file</title>
@@ -71,78 +71,76 @@
 <screen>&uprompt; <userinput>ftp 
ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc.tar.gz</userinput></screen>
 
 </sect2>
-<sect2 id="getting-via-sup">
-<title>Via SUP</title>
-
-       <para>As an alternative to the tar file, you can get pkgsrc via
-       the Software Update Protocol, SUP. To do so, make sure your
-       supfile has a line
+<sect2 id="getting-via-cvs">
+<title>Via anonymous CVS</title>
 
-<programlisting>
-release=pkgsrc
-</programlisting>
+<para>To fetch a specific pkgsrc stable branch from scratch, run:</para>
 
-       in it, see the examples in
-       <filename>/usr/share/examples/supfiles</filename>, and that the
-       <filename>/usr/pkgsrc</filename> directory exists. Then, simply
-       run:</para>
+<screen>&uprompt; <userinput>cd /usr && cvs -q -z3 -d 
anoncvs%anoncvs.NetBSD.org@localhost:/cvsroot checkout -r 
<replaceable>pkgsrc-20xxQy</replaceable> -P pkgsrc</userinput>
+</screen>
 
-<screen>&uprompt; <userinput>sup -v 
<replaceable>/path/to/your/supfile</replaceable></userinput>.</screen>
+       <para>Where <replaceable>pkgsrc-20xxQy</replaceable> is the stable 
+       branch to be checked out, for example, 
<quote>pkgsrc-2009Q1</quote></para>
 
-</sect2>
-<sect2 id="getting-via-cvs">
-<title>Via anonymous CVS</title>
+       <para>This will create the directory <filename>pkgsrc/</filename> 
+       in your <filename>/usr/</filename> directory and all the package source 
+       will be stored under <filename>/usr/pkgsrc/</filename>.</para>
 
-       <para>To do an initial (full) checkout of pkgsrc, you first
-       have to set some environment variables. For the C-Shell,
-       type:</para>
+<para>To fetch the pkgsrc current branch, run:</para>
 
-<screen>&cprompt; <userinput>setenv CVSROOT 
anoncvs%anoncvs.NetBSD.org@localhost:/cvsroot</userinput>
-&cprompt; <userinput>setenv CVS_RSH ssh</userinput>
+<screen>&uprompt; <userinput>cd /usr && cvs -q -z3 -d 
anoncvs%anoncvs.NetBSD.org@localhost:/cvsroot checkout -P pkgsrc</userinput>
 </screen>
 
-       <para>Or, the same for the bourne shell:</para>
+<!--
+       <para>Refer to list of available CVS mirrors to choose faster 
one.</para>
+FIXME: do we have it?
+-->
+
+<!--
+       <para>On some older systems you may need to set CVS_RSH variable:</para>
 
-<screen>&uprompt; <userinput>export 
CVSROOT="anoncvs%anoncvs.NetBSD.org@localhost:/cvsroot"</userinput>
-&uprompt; <userinput>export CVS_RSH="ssh"</userinput>
+<screen>&uprompt; <userinput>cd /usr && CVS_RSH=ssh cvs -q -z3 -d 
anoncvs%anoncvs.NetBSD.org@localhost:/cvsroot checkout -P pkgsrc</userinput>
 </screen>
 
-       <para>By default, CVS doesn't do things like most people would
-       expect it to do. But there is a
-       way to convince CVS, by creating a file called
-       <filename>.cvsrc</filename> in your home directory and saving
-       the following lines to it. This file will save you lots of
-       headache and some bug reports, so we strongly recommend it. You
-       can find an explanation of this file in the CVS
-       documentation.</para>
+FIXME: what are those systems that need it?
+If they exist, bring this paragraph back, if not, drop it completely.
+-->
+
+<!-- FIXME: This should move into appendix or so. -->
+       <para>By default, CVS doesn't do things like most people would expect 
it to do.
+       But there is a way to convince CVS, by creating a file called 
<filename>.cvsrc</filename>
+       in your home directory and saving the following lines to it.
+       This file will save you lots of headache and some bug reports, so we 
strongly recommend it.
+       You can find an explanation of this file in the CVS 
documentation.</para>
 
 <programlisting>
 # recommended CVS configuration file from the pkgsrc guide
+cvs -q -z3
 checkout -P
 update -dP
-release -d
 diff -upN
-cvs -q -z3
 rdiff -u
+release -d
 </programlisting>
 
+</sect2>
+<sect2 id="getting-via-sup">
+<title>Via SUP</title>
 
-<para>To fetch a specific pkgsrc stable branch from scratch, run:</para>
-
-<screen>&uprompt; <userinput>cd /usr</userinput>
-&uprompt; <userinput>cvs checkout -r <replaceable>pkgsrc-20xxQy</replaceable> 
-P pkgsrc</userinput></screen>
-
-       <para>Where <replaceable>pkgsrc-20xxQy</replaceable> is the stable 
-       branch to be checked out, for example, 
<quote>pkgsrc-2009Q1</quote></para>
+       <para>As an alternative to the tar file, you can get pkgsrc via
+       the Software Update Protocol, SUP. To do so, make sure your
+       supfile has a line
 
-       <para>This will create the directory <filename>pkgsrc/</filename> 
-       in your <filename>/usr/</filename> directory and all the package source 
-       will be stored under <filename>/usr/pkgsrc/</filename>.</para>
+<programlisting>
+release=pkgsrc
+</programlisting>
 
-<para>To fetch the pkgsrc current branch, run:</para>
+       in it, see the examples in
+       <filename>/usr/share/examples/supfiles</filename>, and that the
+       <filename>/usr/pkgsrc</filename> directory exists. Then, simply
+       run:</para>
 
-<screen>&uprompt; <userinput>cd /usr</userinput>
-&uprompt; <userinput>cvs checkout -P pkgsrc</userinput></screen>
+<screen>&uprompt; <userinput>sup -v 
<replaceable>/path/to/your/supfile</replaceable></userinput>.</screen>
 
 </sect2>
 </sect1>

-- 
HE CE3OH...

Follow-Ups:
- Re: Simplify getting instructions in the guide
  - From: David Brownlee
- RE: Simplify getting instructions in the guide
  - From: Larson, Timothy E.

Prev by Date: daily pkgsrc CVS update output
Next by Date: Guide's "Configuring" chapter is rather misleading than helpful
Previous by Thread: daily pkgsrc CVS update output
Next by Thread: RE: Simplify getting instructions in the guide
Indexes:

Home | Main Index | Thread Index | Old Index