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.head 2 Sep 2015 13:11:30 -0000 1.42 >> +++ anoncvs.html.head 11 Sep 2015 22:10:15 -0000 > > 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, <tt>src.t >> </pre> >> >> <p> >> -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. >> >> <p> >> -You can also just use cvs(1) to "<b>checkout</b>" the source repository >> +You can also just use >> +<a >> href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvs&sektion=1&format=html";>cvs(1)</a> >> +to "<b>checkout</b>" 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&sec=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 <a href="#using">next section</a>. >> >> <p> >> @@ -160,16 +162,12 @@ from the <a href="errata.html">errata</a >> For more information on these "flavors" of OpenBSD, see >> <a href="faq/faq5.html#Flavors">here</a>. >> >> -<p>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 >> -<a href="#CVSROOT">below</a>. >> - >> <p> >> -Once you have chosen which <a href="#CVSROOT">Anonymous CVS Server</a> you >> will >> -use, you can start using cvs. For those of you >> +Once you have decided which tree to follow, and which <a >> href="#CVSROOT">Anonymous CVS Server</a> you will >> +use, you can start using <a >> href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvs&sektion=1&format=html";>cvs(1)</a>. >> 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, you're not going to do > well with OpenBSD (or computing in general) anyway... Not sure how to consistently handle this one, but I agree the pages can get cluttered with hrefs. I was just trying to be consistent with current practice (which seemed to be every time). > 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. Ok. > >> who have CDs you can start with the CVS checkout that is on the CD by using >> the method <a href="#starting">above</a> 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: >> >> <p> >> <ul><li>First, start out by `get'-ing an initial tree: >> @@ -210,9 +208,11 @@ Confirm this, and the fingerprint will t >> ... >> </pre> >> >> +<p> >> Note that the above format with SHA256 fingerprints was added after the >> release of OpenBSD 5.6; older versions only use MD5 fingerprints. >> >> +<p> >> <li> Anytime afterwards, to `update' this tree: >> <p> (If you are following <i>current</i>): >> <pre> >> @@ -234,7 +234,7 @@ to merge changes in. >> <li> NOTE: >> If you are updating a source tree that you initially fetched >> from a different server, or from a CD, you <strong>must</strong> >> -add the <em>-d [cvsroot]</em> option to cvs. >> +add the <em>-d [cvsroot]</em> option to cvs: >> <pre> >> # <strong>cd /usr/src</strong> >> # <strong>cvs -d anon...@anoncvs.ca.openbsd.org:/cvs -q up -Pd</strong> >> @@ -295,11 +295,11 @@ directory, and a subsequent update will >> >> <p> >> 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 > > I don't know about this one. I think the original, "gives fledgling > developers a chance to learn CVS operation and get thoroughly involved", > sound more correct. But English is not my first language so I may well > be mistaken. Maybe delete "operation/s" altogether? "... a chance to learn CVS and..."? > >> 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 > > Again with the reservation about my English, I have never really liked > the start of that sentence. (Not that you put it there, but while the > subject is up I might as well comment on it. :-) ) Would "Also, people > providing patches can create..." sound better perhaps? Or is it just me? Not sure. Maybe this is the type of change that I should stay away from proposing? > >> to the CVS tree, which will ease integration. >> >> <h3><a name="EXAMPLE"><font color="#0000e0">Example usages for cvs(1)</font> >> > > > Regards, > /Benny
