Bug 267002

Summary:

FreeBSD Handbook: incoherent sentences in kernel config section

Product:

Documentation

Reporter:

Luís Henriques <henrix>

Component:

Books & Articles

Assignee:

Sergio Carlavilla Delgado <carlavilla>

Status:

Closed FIXED

Severity:

Affects Some People

CC:

carlavilla, grahamperrin

Priority:

---

Version:

Latest

Hardware:

Any

OS:

Any

Bug Depends on:

Bug Blocks:

263315

Attachments:

Description	Flags
first patch	none
second patch	none

Description Luís Henriques 2022-10-12 20:53:25 UTC

Created attachment 237245 [details]
first patch

I'm attaching 2 patches to this bug report regarding some incoherent sentences (and one mistake) in the kernel configuration section.
The first patch has the following changes:

1. "ath wireless Ethernet driver" is incorrect; use "ath wireless network driver" instead.
2. "Source can be installed using Git and the instructions in <ref>" doesn't sound correct; rephased a bit.
3. The troubleshooting note starts with a very long and confusing sentence; rephrased.

The second patch is more an RFC: I don't think it's correct, or, at least, it isn't complete.  Basically, there are asciidoc mistakes in the documentation.  And I found some while reading the above mentioned section in the handbook.  As the patch description suggests, have a look at the paragraph that starts with "The format of the kernel configuration file is simple" in [1]. That paragraph misses two '#' characters.

Anyway, the details are all in that patch description, including how the patch was (automatically) generated (except for a manual change).
 
[1] https://docs.freebsd.org/en/books/handbook/kernelconfig/#kernelconfig-config

Comment 1 Luís Henriques 2022-10-12 20:54:12 UTC

Created attachment 237246 [details]
second patch

Comment 2 commit-hook freebsd_committer

2022-11-02 19:56:42 UTC

A commit in branch main references this bug:

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

commit 5821e118dd2b7f93e7f0e45b5cc6c6be798b38e7
Author:     Luís Henriques <henrix@camandro.org>
AuthorDate: 2022-11-02 19:53:59 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-11-02 19:53:59 +0000

    Escape correctly the # character and fix some typos

    PR:             267002

 .../content/en/books/developers-handbook/x86/_index.adoc     |  6 +++---
 .../en/books/handbook/advanced-networking/_index.adoc        |  4 ++--
 documentation/content/en/books/handbook/basics/_index.adoc   |  6 +++---
 documentation/content/en/books/handbook/config/_index.adoc   |  2 +-
 documentation/content/en/books/handbook/disks/_index.adoc    |  2 +-
 .../content/en/books/handbook/firewalls/_index.adoc          |  6 +++---
 .../content/en/books/handbook/kernelconfig/_index.adoc       | 12 ++++++------
 documentation/content/en/books/handbook/mail/_index.adoc     |  2 +-
 .../content/en/books/handbook/network-servers/_index.adoc    | 10 +++++-----
 .../content/en/books/handbook/ppp-and-slip/_index.adoc       |  2 +-
 documentation/content/en/books/handbook/security/_index.adoc |  2 +-
 .../content/en/books/handbook/virtualization/_index.adoc     |  2 +-
 12 files changed, 28 insertions(+), 28 deletions(-)

Comment 3 Sergio Carlavilla Delgado freebsd_committer

2022-11-02 19:57:06 UTC

Fixed. Thanks!