Bug 252519 - Sentence fragments in books/
Summary: Sentence fragments in books/
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: Daniel Ebdrup Jensen
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2021-01-08 15:31 UTC by Ceri Davies
Modified: 2021-01-12 18:53 UTC (History)
2 users (show)

See Also:


Attachments
It's a patch (28.35 KB, patch)
2021-01-08 15:31 UTC, Ceri Davies
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Ceri Davies 2021-01-08 15:31:24 UTC
Created attachment 221389 [details]
It's a patch

As per 252493, here's the same for books/
I have avoided making changes to design-44bsd since that is an extract of a different book, and also in the x86 chapter of the developers-handbook since it says I shouldn't make changes.

FAQ could do with a <copyright /> bump as a result of this but I haven't included it in the patch.
Comment 1 Daniel Ebdrup Jensen freebsd_committer 2021-01-11 16:28:45 UTC
Could you please rebase this patch onto the latest tree?
It's a welcome change that I'd like to commit, but it doesn't apply cleanly.
Comment 2 Ceri Davies 2021-01-11 16:38:09 UTC
Hi, where are you having issues? I've applied it to a fresh git clone and it seems to go on ok.

Ceri
Comment 3 Daniel Ebdrup Jensen freebsd_committer 2021-01-11 18:15:48 UTC
Ah, it seems like there was a bit of overlap between the prior patch and this one, and I was not aware of git apply atomicity, so didn't account for the need to use --reject.

I'll just wait a while for a review or two, then go ahead and commit this change. :)
Comment 4 Ceri Davies 2021-01-11 18:26:03 UTC
Ace, thanks :)
Comment 5 Daniel Ebdrup Jensen freebsd_committer 2021-01-11 18:35:26 UTC
Also, make sure it's assigned to me. :)
Comment 6 PauAmma freebsd_triage 2021-01-11 23:47:51 UTC
(In reply to Ceri Davies from comment #0)

Overall, I like these changes. I suggested a few tweaks to both your patch and the surrounding text.

--- b/en_US.ISO8859-1/books/arch-handbook/boot/chapter.xml	
+++ b/en_US.ISO8859-1/books/arch-handbook/boot/chapter.xml	
[...]
@@ -1583,7 +1583,7 @@ init.3:		lea 0x8(%di),%di		# Next entry
       abstraction.  The IA-32 architecture demands the creation and
       use of <emphasis>at least</emphasis> one <acronym>TSS</acronym>
       if multitasking facilities are used or different privilege
-      levels are defined.  Because the <filename>boot2</filename>
+      levels are defined.  Since the <filename>boot2</filename>
       client is executed in privilege level 3, but the
       <acronym>BTX</acronym> server does in privilege level 0, a

Since you're touching that paragraph, might as well s/does/runs/ in the line above.

--- b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml	
+++ b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml	
@@ -375,7 +375,7 @@ 
         with PnP. This feature is not implemented in any existing
         driver and is not considered further in this document.</para>
 
-      <para>Because the PnP devices are disabled when probing the
+      <para>As the PnP devices are disabled when probing the
         legacy devices they will not be attached twice (once as legacy
         and once as PnP).  But in case of device-dependent identify

"in the case", maybe?

--- b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml	
+++ b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml	
[...]

@@ -1634,7 +1634,7 @@ 
       routine (or the other way around, the poll routine may be doing
       the real action and the interrupt routine would just call the
       poll routine).  Why bother about a separate function then?
-      Because of different calling conventions.  The
+      Due to different calling conventions.  The

That's a sentence fragment before and after the change. Perhaps combine with the previous sentence?

       <function>xxx_poll</function> routine gets the struct cam_sim
       pointer as its argument when the PCI interrupt routine by common

While here, I'd s/when/while/.

--- b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.xml	
+++ b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.xml	
@@ -822,13 +822,13 @@ fe80:2::%ep0/64               link#2                    UC          ep0</screen>
 	  packet processing code in the way BSD IPv4 code is
 	  implemented, kernel stack may overflow due to long function
 	  call chain.  sys/netinet6 code is carefully designed to
-	  avoid kernel stack overflow.  Because of this, sys/netinet6
+	  avoid kernel stack overflow, so sys/netinet6
 	  code defines its own protocol switch structure, as "struct
 	  ip6protosw" (see
 	  <filename>netinet6/ip6protosw.h</filename>).  There is no
 	  such update to IPv4 part (sys/netinet) for compatibility,
 	  but small change is added to its pr_input() prototype.  So
-	  "struct ipprotosw" is also defined.  Because of this, if you
+	  "struct ipprotosw" is also defined.  As a result, if you
 	  receive IPsec-over-IPv4 packet with massive number of IPsec
 	  headers, kernel stack may blow up.  IPsec-over-IPv6 is okay.

"the kernel stack may overflow" maybe?

 	  (Off-course, for those all IPsec headers to be processed,

Probably meant "Of course" above.

--- b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml	
+++ b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml	
@@ -214,7 +214,7 @@ 
 
     <para>A tag is used to identify where a particular element starts,
       and where the element ends.  <emphasis>The tag is not part of
-      the element itself</emphasis>.  Because each grammar was
+      the element itself</emphasis>.  As each grammar was
       normally written to mark up specific types of information, each
       one will recognize different elements, and will therefore have
       different names for the tags.</para>
@@ -596,7 +596,7 @@ example.xml:5: element head: validity error : Element head content does not foll
 	      council delegated this to the American National
 	      Standards Institute (<acronym>ANSI</acronym>).</para>
 
-	    <para>Because the &os; Project has not been registered,
+	    <para>Since the &os; Project has not been registered,
 	      the owner string is <literal>-//&os;</literal>.  As seen
 	      in the example, the <acronym>W3C</acronym> are not a

"is not", maybe? I think the whole documentation is supposed to use US English, in which collective nouns take the singular.

--- b/en_US.ISO8859-1/books/handbook/geom/chapter.xml	
+++ b/en_US.ISO8859-1/books/handbook/geom/chapter.xml	
[...]
@@ -1431,9 +1431,9 @@ ggate0
 
     <para>A better solution is to use <command>glabel</command> to
       label the disk devices and use the labels in
-      <filename>/etc/fstab</filename>.  Because
+      <filename>/etc/fstab</filename>.
       <command>glabel</command> stores the label in the last sector of

That leaves the sentence starting with a lowercase letter, but I'm not sure what the best fix is here. Perhaps "As <command>glabel</command> ..., the label ..." instead of "<command>glabel</command> ..., so the label ..."?

--- b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml	
+++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml	
@@ -839,7 +839,7 @@ kern.ipc.shmall=32768</programlisting>
 	    an <application>&xorg;</application> extension which
 	    allows a program to bypass the
 	    <application>&xorg;</application> server and directly
-	    alter the framebuffer.  Because it relies on a low level
+	    alter the framebuffer.  As it relies on a low level

s/low level/low-level/
Comment 7 Daniel Ebdrup Jensen freebsd_committer 2021-01-12 17:16:52 UTC
I'm ready to commit this with some of the changes pointed out, but I realized that I forgot to ask how you want to be credited for authorship. 
I assume "Ceri Davies <ceri@submonkey.net>" is fine, since that's what I used in the other commit and you didn't raise an issue with it?
Comment 8 Ceri Davies 2021-01-12 17:22:02 UTC
Hi; that's fine, thanks.  You could put ceri@ but I don't know if that address still works (it has been quite a while).
Comment 9 commit-hook freebsd_committer 2021-01-12 18:34:55 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=eab1c5d1f64d77131928469081729d6370841075

commit eab1c5d1f64d77131928469081729d6370841075
Author:     Ceri Davies <ceri@submonkey.net>
AuthorDate: 2021-01-12 17:57:32 +0000
Commit:     Daniel Ebdrup Jensen <debdrup@FreeBSD.org>
CommitDate: 2021-01-12 18:33:23 +0000

    books/: Address more instances of sentences beginning with 'Because...'

    As was the case with the previous commit, the intention is to avoid
    sentence fragments as well as sentences that can be mistaken for them,
    since the handbook isn't written in a style that makes use of
    subordinate conjunctions.

    While touching the relevant files, I also fixed a few issues pointed
    out by PauAmma, and reflowed a sentence as a result.

    PR:             252519
    Submitted by:   ceri@
    Reviewed by:    PauAmma

 en_US.ISO8859-1/books/arch-handbook/boot/chapter.xml     |  2 +-
 en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml     |  4 ++--
 .../books/developers-handbook/ipv6/chapter.xml           |  6 +++---
 .../books/developers-handbook/kerneldebug/chapter.xml    |  2 +-
 .../books/developers-handbook/secure/chapter.xml         |  2 +-
 .../books/developers-handbook/sockets/chapter.xml        |  6 +++---
 en_US.ISO8859-1/books/faq/book.xml                       |  4 ++--
 en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml    |  2 +-
 .../books/fdp-primer/po-translations/chapter.xml         |  8 ++++----
 en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml  |  6 +++---
 en_US.ISO8859-1/books/handbook/basics/chapter.xml        |  6 +++---
 en_US.ISO8859-1/books/handbook/boot/chapter.xml          |  2 +-
 en_US.ISO8859-1/books/handbook/config/chapter.xml        |  4 ++--
 en_US.ISO8859-1/books/handbook/geom/chapter.xml          | 16 ++++++++--------
 en_US.ISO8859-1/books/handbook/multimedia/chapter.xml    |  2 +-
 en_US.ISO8859-1/books/handbook/security/chapter.xml      |  4 ++--
 en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml   |  4 ++--
 en_US.ISO8859-1/books/handbook/zfs/chapter.xml           |  6 +++---
 18 files changed, 43 insertions(+), 43 deletions(-)
Comment 10 Daniel Ebdrup Jensen freebsd_committer 2021-01-12 18:53:25 UTC
Thanks for the patch, Ceri.
And thanks for the review, PauAmma.