Re: anoncvs.html.head

[Rob Pierce]

> Thanks Stuart. I am preparing a new diff which I will send shortly.

I am holding off on sending the next diff until I figure out how to ensure
that my diff does not get mangled by my email client. In particular, a
hash (#) in an HTML anchor tag seems to get hosed by my zimbra web client.

Playing with fetchmail, sendmail and mutt on my new OpenBSD desktop.

Almost there...

Rob

Re: anoncvs.html.head

[Rob Pierce]

- Original Message -
> From: "Stuart Henderson" <s...@spacehopper.org>
> To: "misc" <misc@openbsd.org>
> Sent: Saturday, September 12, 2015 11:58:29 AM
> Subject: Re: anoncvs.html.head

> On 2015-09-11, Rob Pierce <r...@2keys.ca> wrote:
>>src - Houses all source code for the OpenBSD Operating System.
>>ports - Houses the OpenBSD 
>> Ports.
>> -  www - Houses all OpenBSD web pages. (Including this one).
>> +  www - Houses all OpenBSD web pages (including this one).
> 
> I like that
> 
>>xenocara - Houses OpenBSD's active X.org v7 source tree.
>>X11 and XF4 - Houses OpenBSD's adaptation of the
>>http://www.XFree86.org/;>XFree86-3 and XFree86-4
>> @@ -122,7 +122,7 @@ with only one part of the tree.  The two
>>  which contains the files used to create the kernel, and src.tar.gz
>>  which contains all the other "userland" utilities.
>>  In general, however, you will usually want both of them installed.
>> -Assuming the downloaded files, src.tar.gz,
>> +Assuming the downloaded files src.tar.gz,
>> sys.tar.gz and xenocara.tar.gz are in /usr:
> 
> I think this was OK as it was
> 
>> 
>> -Not all people will wish to unpack all the file sets, but as the system
>> +Not all people will wish to unpack all the source file, but as the system
>>  must be kept in sync, you will generally need to set up all trees.
> 
> and this (and the new sentence doesn't quite make sense)
> 
>> 
>> -You can also just use cvs(1) to "checkout" the source repository
>> +You can also just use
>> +> href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1)
>> +to "checkout" the source repository
>>  for you. This is discussed in the next section.
> 
> OK I guess, though I don't think we need to hyperlink every instance of
> a program name
> 
>> @@ -160,16 +162,12 @@ from the errata>  For more information on these "flavors" of OpenBSD, see
>> here.
>>  
>> -Once you have decided which tree to follow, you must choose which 
>> Anonymous
>> -CVS server you are going to use.  A list of these servers is
>> -below.
>> -
>> 
>> -Once you have chosen which Anonymous CVS Server you 
>> will
>> -use, you can start using cvs. For those of you
>> +Once you have decided which tree to follow, and which > href="#CVSROOT">Anonymous CVS Server you will
> 
> Please try and keep <80 columns in the source file where sensible
> 
>> +use, you can start using > href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1).
>> For those of you
>>  who have CDs you can start with the CVS checkout that is on the CD by using
>>  the method above to get the sources onto your 
>> system.
>> -If you don't have a CD handy, use the method below to checkout the sources.
>> +If you don't have a CD handy, use the method below to checkout the sources:
>>  
>> 
>> First, start out by `get'-ing an initial tree:
>> @@ -210,9 +208,11 @@ Confirm this, and the fingerprint will t
>>  ...
>> 
>>  
>> +
>>  Note that the above format with SHA256 fingerprints was added after the
>>  release of OpenBSD 5.6; older versions only use MD5 fingerprints.
>>  
>> +
>>  Anytime afterwards, to `update' this tree:
>>  (If you are following current):
>> 
>> @@ -234,7 +234,7 @@ to merge changes in.
>>  NOTE:
>>  If you are updating a source tree that you initially fetched
>>  from a different server, or from a CD, you must
>> -add the -d [cvsroot] option to cvs.
>> +add the -d [cvsroot] option to cvs:
>> 
>>  # cd /usr/src
>>  # cvs -d anon...@anoncvs.ca.openbsd.org:/cvs -q up -Pd
>> @@ -295,11 +295,11 @@ directory, and a subsequent update will
>>  
>> 
>>  The anoncvs service gives fledgling developers a chance to learn CVS
>> -operation and get thoroughly involved in the development process
>> +operations and get thoroughly involved in the development process
> 
> "operation" already seem ok
> 
>>  before getting "commit" access -- as a result of showing useful
>>  skills and high quality results they will naturally later be given
>>  developer access.
>> -As well, people providing patches can create their "diff"s relative
>> +As well, people providing patches can create their diffs relative
>>  to the CVS tree, which will ease integration.
>>  
> > Example usages for cvs(1)

Thanks Stuart. I am preparing a new diff which I will send shortly.

Re: anoncvs.html.head

[Stuart Henderson]

On 2015-09-11, Rob Pierce  wrote:
>src - Houses all source code for the OpenBSD Operating System.
>ports - Houses the OpenBSD 
> Ports.
> -  www - Houses all OpenBSD web pages. (Including this one).
> +  www - Houses all OpenBSD web pages (including this one).

I like that

>xenocara - Houses OpenBSD's active X.org v7 source tree.
>X11 and XF4 - Houses OpenBSD's adaptation of the
>http://www.XFree86.org/;>XFree86-3 and XFree86-4
> @@ -122,7 +122,7 @@ with only one part of the tree.  The two
>  which contains the files used to create the kernel, and src.tar.gz
>  which contains all the other "userland" utilities.
>  In general, however, you will usually want both of them installed.
> -Assuming the downloaded files, src.tar.gz,
> +Assuming the downloaded files src.tar.gz,
> sys.tar.gz and xenocara.tar.gz are in /usr:

I think this was OK as it was

> 
> -Not all people will wish to unpack all the file sets, but as the system
> +Not all people will wish to unpack all the source file, but as the system
>  must be kept in sync, you will generally need to set up all trees.

and this (and the new sentence doesn't quite make sense)

> 
> -You can also just use cvs(1) to "checkout" the source repository
> +You can also just use
> + href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1)
> +to "checkout" the source repository
>  for you. This is discussed in the next section.

OK I guess, though I don't think we need to hyperlink every instance of
a program name

> @@ -160,16 +162,12 @@ from the errata  For more information on these "flavors" of OpenBSD, see 
> here.
>  
> -Once you have decided which tree to follow, you must choose which 
> Anonymous
> -CVS server you are going to use.  A list of these servers is
> -below.
> -
> 
> -Once you have chosen which Anonymous CVS Server you 
> will
> -use, you can start using cvs. For those of you
> +Once you have decided which tree to follow, and which  href="#CVSROOT">Anonymous CVS Server you will

Please try and keep <80 columns in the source file where sensible

> +use, you can start using  href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1).
>  For those of you
>  who have CDs you can start with the CVS checkout that is on the CD by using
>  the method above to get the sources onto your system.
> -If you don't have a CD handy, use the method below to checkout the sources.
> +If you don't have a CD handy, use the method below to checkout the sources:
>  
> 
> First, start out by `get'-ing an initial tree:
> @@ -210,9 +208,11 @@ Confirm this, and the fingerprint will t
>   ...
> 
>  
> +
>  Note that the above format with SHA256 fingerprints was added after the
>  release of OpenBSD 5.6; older versions only use MD5 fingerprints.
>  
> +
>  Anytime afterwards, to `update' this tree:
>  (If you are following current):
> 
> @@ -234,7 +234,7 @@ to merge changes in.
>  NOTE:
>  If you are updating a source tree that you initially fetched
>  from a different server, or from a CD, you must
> -add the -d [cvsroot] option to cvs.
> +add the -d [cvsroot] option to cvs:
> 
>   # cd /usr/src
>   # cvs -d anon...@anoncvs.ca.openbsd.org:/cvs -q up -Pd
> @@ -295,11 +295,11 @@ directory, and a subsequent update will 
>  
> 
>  The anoncvs service gives fledgling developers a chance to learn CVS
> -operation and get thoroughly involved in the development process
> +operations and get thoroughly involved in the development process

"operation" already seem ok

>  before getting "commit" access -- as a result of showing useful
>  skills and high quality results they will naturally later be given
>  developer access.
> -As well, people providing patches can create their "diff"s relative
> +As well, people providing patches can create their diffs relative
>  to the CVS tree, which will ease integration.
>  
> Example usages for cvs(1)

Re: anoncvs.html.head

[Benny Lofgren]

Hi Rob,

On 2015-09-12 01:15, Rob Pierce wrote:
> This diff is a resend against the correct file:
>  - some punctuation, line spacing and minor grammar fixes
>  - "file sets" has a special meaning, so don't refer to src.tar.gz, 
> xenocara.tar.gc,ports.tar.gz as "file sets"
>  - cvs(1) hrefs
>  - "diffs" is already used earlier on the page, so don't quote it
> Index: anoncvs.html.head
> ===
> RCS file: /cvs/www/build/mirrors/anoncvs.html.head,v
> retrieving revision 1.42
> diff -u -p -r1.42 anoncvs.html.head
> --- anoncvs.html.head 2 Sep 2015 13:11:30 -   1.42
> +++ anoncvs.html.head 11 Sep 2015 22:10:15 -

Just a few comments inline below. I think you posted this or a similar
diff to tech@ the other day, so maybe this is in the wrong place, but
I'll leave the comment as well in misc@ to avoid confusion.


...
> @@ -135,11 +135,13 @@ Assuming the downloaded files, src.t
>  
>  
>  
> -Not all people will wish to unpack all the file sets, but as the system
> +Not all people will wish to unpack all the source file, but as the system

I think "source files" (plural), alternatively "all of the source file"
depending on your intention?

>  must be kept in sync, you will generally need to set up all trees.
>  
>  
> -You can also just use cvs(1) to "checkout" the source repository
> +You can also just use
> + href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1)
> +to "checkout" the source repository

Is that the correct URL? The use of "sektion" (which is a Swedish,
Danish or German spelling :-) ) instead of "sec" caught my eye.

When I do the same search directly from www.openbsd.org I get this:

http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/cvs.1?query=cvs=1

(I realize that the link you used is the same one already used elsewhere
in this page. But even if I copy and paste that link into my browser,
the web server redirects it to the one I pasted here. Maybe there is
some legacy stuff going on here, perhaps a server side change not yet
reflected in all of the html pages?)

>  for you. This is discussed in the next section.
>  
>  
> @@ -160,16 +162,12 @@ from the errata  For more information on these "flavors" of OpenBSD, see 
>  here.
>  
> -Once you have decided which tree to follow, you must choose which 
> Anonymous
> -CVS server you are going to use.  A list of these servers is
> -below.
> -
>  
> -Once you have chosen which Anonymous CVS Server you 
> will
> -use, you can start using cvs. For those of you
> +Once you have decided which tree to follow, and which  href="#CVSROOT">Anonymous CVS Server you will
> +use, you can start using  href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1).
>  For those of you

I don't know about you or the developers, but personally I kind of
prefer the original wording and paragraph division, except I would
change the second paragraph's repetitious use of "Once you have..." to
something like "When you have..." instead.


And maybe remove the second href to the cvs server list. I don't know
about official policy here, but having several identical links so close
to each other in a text always confuses me and makes me click on all of
them, only to be annoyed I end up in the same place. :-)

One objection to this would be that people who only read the second
paragraph in this example would miss the link altogether. I would then
contend that if you don't have the habit and patience of reading ALL the
relevant parts of a given piece of documentation, you're not going to do
well with OpenBSD (or computing in general) anyway...


Also, while here, maybe it would make more sense to write "If you have
CDs" rather than "For those of you who have CDs", since the rest of the
page is phrased such that the reader is addressed with "you" rather than
as a teacher would address a lecture hall full of students.

>  who have CDs you can start with the CVS checkout that is on the CD by using
>  the method above to get the sources onto your system.
> -If you don't have a CD handy, use the method below to checkout the sources.
> +If you don't have a CD handy, use the method below to checkout the sources:
>  
>  
>  First, start out by `get'-ing an initial tree:
> @@ -210,9 +208,11 @@ Confirm this, and the fingerprint will t
>   ...
>  
>  
> +
>  Note that the above format with SHA256 fingerprints was added after the
>  release of OpenBSD 5.6; older versions only use MD5 fingerprints.
>  
> +
>   Anytime afterwards, to `update' this tree:
>   (If you are following current):
>  
> @@ -234,7 +234,7 @@ to merge changes in.
>   NOTE:
>  If you are updating a source tree that you initially fetched
>  from a different server, or from a CD, you must
> -add the -d [cvsroot] option to cvs.
> +add the -d [cvsroot] option to cvs:
>  
>   # cd /usr/src
>   # cvs -d anon...@anoncvs.ca.openbsd.org:/cvs -q up -Pd
> @@ -295,11 +295,11 @@ directory, 

Re: anoncvs.html.head

[Rob Pierce]

Thanks Benny. I will review again and resubmit.

Some responses in-line below.

- Original Message -
> From: "Benny Lofgren" <bl-li...@lofgren.biz>
> To: "misc" <misc@openbsd.org>
> Sent: Saturday, September 12, 2015 8:01:58 AM
> Subject: Re: anoncvs.html.head

> Hi Rob,
> 
> On 2015-09-12 01:15, Rob Pierce wrote:
>> This diff is a resend against the correct file:
>>  - some punctuation, line spacing and minor grammar fixes
>>  - "file sets" has a special meaning, so don't refer to src.tar.gz,
>>  xenocara.tar.gc,ports.tar.gz as "file sets"
>>  - cvs(1) hrefs
>>  - "diffs" is already used earlier on the page, so don't quote it
>> Index: anoncvs.html.head
>> ===
>> RCS file: /cvs/www/build/mirrors/anoncvs.html.head,v
>> retrieving revision 1.42
>> diff -u -p -r1.42 anoncvs.html.head
>> --- anoncvs.html.head2 Sep 2015 13:11:30 -   1.42
>> +++ anoncvs.html.head11 Sep 2015 22:10:15 -
> 
> Just a few comments inline below. I think you posted this or a similar
> diff to tech@ the other day, so maybe this is in the wrong place, but
> I'll leave the comment as well in misc@ to avoid confusion.
> 
> 
> ...
>> @@ -135,11 +135,13 @@ Assuming the downloaded files, src.t
>>  
>>  
>>  
>> -Not all people will wish to unpack all the file sets, but as the system
>> +Not all people will wish to unpack all the source file, but as the system
> 
> I think "source files" (plural), alternatively "all of the source file"
> depending on your intention?

Yes, I missed that - thanks.

> 
>>  must be kept in sync, you will generally need to set up all trees.
>>  
>>  
>> -You can also just use cvs(1) to "checkout" the source repository
>> +You can also just use
>> +> href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1)
>> +to "checkout" the source repository
> 
> Is that the correct URL? The use of "sektion" (which is a Swedish,
> Danish or German spelling :-) ) instead of "sec" caught my eye.
> 
> When I do the same search directly from www.openbsd.org I get this:
> 
> http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/cvs.1?query=cvs=1
> 
> (I realize that the link you used is the same one already used elsewhere
> in this page. But even if I copy and paste that link into my browser,
> the web server redirects it to the one I pasted here. Maybe there is
> some legacy stuff going on here, perhaps a server side change not yet
> reflected in all of the html pages?)

I will look into that. I must admit that I tend to grab existing text to
complete an href, but in the future I will do the lookup and grab the
actual URL. I was wondering were sektion came from!

>>  for you. This is discussed in the next section.
>>  
>>  
>> @@ -160,16 +162,12 @@ from the errata>  For more information on these "flavors" of OpenBSD, see
>>  here.
>>  
>> -Once you have decided which tree to follow, you must choose which 
>> Anonymous
>> -CVS server you are going to use.  A list of these servers is
>> -below.
>> -
>>  
>> -Once you have chosen which Anonymous CVS Server you 
>> will
>> -use, you can start using cvs. For those of you
>> +Once you have decided which tree to follow, and which > href="#CVSROOT">Anonymous CVS Server you will
>> +use, you can start using > href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1).
>> For those of you
> 
> I don't know about you or the developers, but personally I kind of
> prefer the original wording and paragraph division, except I would
> change the second paragraph's repetitious use of "Once you have..." to
> something like "When you have..." instead.

Ok. I should stay away from "style" changes, and stick to obvious corrections
and/or functional text changes. This just seemed a bit awkward to me.

> 
> 
> And maybe remove the second href to the cvs server list. I don't know
> about official policy here, but having several identical links so close
> to each other in a text always confuses me and makes me click on all of
> them, only to be annoyed I end up in the same place. :-)
> 
> One objection to this would be that people who only read the second
> paragraph in this example would miss the link altogether. I would then
> contend that if you don't have the habit and patience of reading ALL the
> relevant parts of a given piece of documentation

Re: anoncvs.html.head

[Rob Pierce]

See attached.

- Original Message -
From: "Rob Pierce" 
To: "misc" 
Sent: Friday, September 11, 2015 6:30:33 PM
Subject: anoncvs.html.head

This diff is a resend against the correct file:

 - some punctuation, line spacing and minor grammar fixes
 - "file sets" has a special meaning, so don't refer to src.tar.gz, 
xenocara.tar.gc,ports.tar.gz as "file sets"
 - cvs(1) hrefs
 - "diffs" is already used earlier on the page, so don't quote it

Rob
Index: anoncvs.html.head
===
RCS file: /cvs/www/build/mirrors/anoncvs.html.head,v
retrieving revision 1.42
diff -u -p -r1.42 anoncvs.html.head
--- anoncvs.html.head   2 Sep 2015 13:11:30 -   1.42
+++ anoncvs.html.head   11 Sep 2015 22:10:15 -
@@ -39,7 +39,7 @@ source repositories:
 
   src - Houses all source code for the OpenBSD Operating System.
   ports - Houses the OpenBSD 
Ports.
-  www - Houses all OpenBSD web pages. (Including this one).
+  www - Houses all OpenBSD web pages (including this one).
   xenocara - Houses OpenBSD's active X.org v7 source tree.
   X11 and XF4 - Houses OpenBSD's adaptation of the
   http://www.XFree86.org/;>XFree86-3 and XFree86-4
@@ -122,7 +122,7 @@ with only one part of the tree.  The two
 which contains the files used to create the kernel, and src.tar.gz
 which contains all the other "userland" utilities.
 In general, however, you will usually want both of them installed.
-Assuming the downloaded files, src.tar.gz,
+Assuming the downloaded files src.tar.gz,
 sys.tar.gz and xenocara.tar.gz are in /usr:
 
 
@@ -135,11 +135,13 @@ Assuming the downloaded files, src.t
 
 
 
-Not all people will wish to unpack all the file sets, but as the system
+Not all people will wish to unpack all the source file, but as the system
 must be kept in sync, you will generally need to set up all trees.
 
 
-You can also just use cvs(1) to "checkout" the source repository
+You can also just use
+http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1)
+to "checkout" the source repository
 for you. This is discussed in the next section.
 
 
@@ -160,16 +162,12 @@ from the erratahere.
 
-Once you have decided which tree to follow, you must choose which Anonymous
-CVS server you are going to use.  A list of these servers is
-below.
-
 
-Once you have chosen which Anonymous CVS Server you will
-use, you can start using cvs. For those of you
+Once you have decided which tree to follow, and which Anonymous CVS Server you will
+use, you can start using http://www.openbsd.org/cgi-bin/man.cgi?query=cvssektion=1format=html;>cvs(1).
 For those of you
 who have CDs you can start with the CVS checkout that is on the CD by using
 the method above to get the sources onto your system.
-If you don't have a CD handy, use the method below to checkout the sources.
+If you don't have a CD handy, use the method below to checkout the sources:
 
 
 First, start out by `get'-ing an initial tree:
@@ -210,9 +208,11 @@ Confirm this, and the fingerprint will t
...
 
 
+
 Note that the above format with SHA256 fingerprints was added after the
 release of OpenBSD 5.6; older versions only use MD5 fingerprints.
 
+
  Anytime afterwards, to `update' this tree:
  (If you are following current):
 
@@ -234,7 +234,7 @@ to merge changes in.
  NOTE:
 If you are updating a source tree that you initially fetched
 from a different server, or from a CD, you must
-add the -d [cvsroot] option to cvs.
+add the -d [cvsroot] option to cvs:
 
# cd /usr/src
# cvs -d anon...@anoncvs.ca.openbsd.org:/cvs -q up -Pd
@@ -295,11 +295,11 @@ directory, and a subsequent update will 
 
 
 The anoncvs service gives fledgling developers a chance to learn CVS
-operation and get thoroughly involved in the development process
+operations and get thoroughly involved in the development process
 before getting "commit" access -- as a result of showing useful
 skills and high quality results they will naturally later be given
 developer access.
-As well, people providing patches can create their "diff"s relative
+As well, people providing patches can create their diffs relative
 to the CVS tree, which will ease integration.
 
 Example usages for cvs(1)