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.
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.
Hi, where are you having issues? I've applied it to a fresh git clone and it seems to go on ok. Ceri
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. :)
Ace, thanks :)
Also, make sure it's assigned to me. :)
(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/
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?
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).
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(-)
Thanks for the patch, Ceri. And thanks for the review, PauAmma.