FDP: Correct some grammar and mistakes

Correct some grammar, some factual information and a misrepresentation
of that the "word list" is.

Submitted by:	ceri
PR:		253467

documentation/content/en/books/fdp-primer/asciidoctor-primer/chapter.adoc

@@ -44,7 +44,7 @@ To remove [.filename]#/tmp/foo#, use man:rm[1].
 % rm /tmp/foo
 ----
 
-It is easy to see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document cannot. For this we need markup.
+It is easy for the reader to see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document cannot reliably determine this. For this we need markup.
 
 
 The previous example is actually represented in this document like this:
@@ -61,7 +61,7 @@ To remove [.filename]#/tmp/foo#, use man:rm[1].
 [[asciidoctor-headings]]
 == Headings
 
-AsciiDoctor support six headings levels. If the document type is `article` only one level 0 (`=`) can be used. If the document type is `book` can be multiple level 0 (`=`).
+AsciiDoctor supports six headings levels. If the document type is `article` only one level 0 (`=`) can be used. If the document type is `book` then there can be multiple level 0 (`=`) headings.
 
 This is an example of headings in an `article`.
 
@@ -101,12 +101,12 @@ The following syntax is not correct.
 
 Paragraphs don't require special markup in AsciiDoc. A paragraph is defined by one or more consecutive lines of text. To create a new paragraph leave one blank line.
 
-For example, this is a heading with two paragraphs
+For example, this is a heading with two paragraphs.
 
 ....
 = This is the heading
 
-This is the firts paragraph.
+This is the first paragraph.
 
 And this is the second paragraph.
 ....
@@ -114,7 +114,7 @@ And this is the second paragraph.
 [[asciidoctor-lists]]
 == Lists
 
-AsciiDoctor support two type of lists ordered and unordered. To get more information about lists check link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]
+AsciiDoctor supports two type of lists: ordered and unordered. To get more information about lists check link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]
 
 [[asciidoctor-ordered-lists]]
 === Ordered lists
@@ -142,7 +142,7 @@ And this would be rendered as.
 
 To create an unordered list use the `.` character.
 
-For example this is an unordered lists.
+For example this is an unordered list.
 
 ....
 . First item
@@ -172,7 +172,7 @@ link:https://www.FreeBSD.org[FreeBSD]
 
 [NOTE]
 ====
-As the AsciiDoctor documentation points the `link` macro is not required when the target starts with a URL scheme like `https`. But is a good practice to ensure that AsciiDoctor renders correctly the link. Specially in non-latin languages like Japanese.
+As the AsciiDoctor documentation describes, the `link` macro is not required when the target starts with a URL scheme like `https`. However, it is a good practice to do this anyway to ensure that AsciiDoctor renders the link correctly, especially in non-latin languages like Japanese.
 ====
 
 [[asciidoctor-links-internal]]
@@ -199,4 +199,4 @@ link:{ipsec-must}[IPSec-Must article]
 [[asciidoctor-conclusion]]
 == Conclusion
 
-That is the conclusion of this AsciiDoctor primer. For reasons of space and complexity, several things have not been covered in depth (or at all).
+This is the conclusion of this AsciiDoctor primer. For reasons of space and complexity, several things have not been covered in depth (or at all).

documentation/content/en/books/fdp-primer/doc-build/chapter.adoc

@@ -165,16 +165,16 @@ build: .PHONY <.>
 <.> `HUGO_CMD` flag specifies the location of the Hugo binary.
 <.> `LANGUAGES` flag specifies in which languages the table of contents has to be generated.
 <.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
-<.> `all` target generate the books TOCs, builds the documentation and puts the result in [.filename]#~/doc/documentation/public#.
+<.> `all` target generates the books' tables of contents ("TOCs"), builds the documentation and puts the result in [.filename]#~/doc/documentation/public#.
 <.> `starting-message` shows a message in the CLI to show the user that the process is running.
 <.> `generate-books-toc` calls the scripts to generate the books TOCs.
-<.> `run` runs hugo webserver in a random free port.
+<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.
 <.> `build` builds the documentation and puts the result in the [.filename]#~/doc/documentation/public#.
 
 [[website-makefile]]
 === Website Makefile
 
-This [.filename]#Makefile# take the form of:
+This [.filename]#Makefile# takes the form of:
 
 [source,bash]
 ....
@@ -225,8 +225,8 @@ build: .PHONY <.>
 <.> `PYTHON_CMD` flag specifies the location of the Python binary.
 <.> `HUGO_CMD` flag specifies the location of the Hugo binary.
 <.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
-<.> `all` target generate the books TOCs, builds the documentation and puts the result in [.filename]#~/doc/website/public#.
+<.> `all` target builds the website and puts the result in [.filename]#~/doc/website/public#.
 <.> `starting-message` shows a message in the CLI to show the user that the process is running.
 <.> `generate-releases` calls the script used to convert from AsciiDoc variables to TOML variables. With this conversion, the releases variables can be used in AsciiDoc and in the Hugo custom templates.
-<.> `run` runs hugo webserver on a random free port.
+<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.
 <.> `build` builds the website and puts the result in the [.filename]#~/doc/website/public#.

documentation/content/en/books/fdp-primer/editor-config/chapter.adoc

@@ -22,7 +22,7 @@ next: books/fdp-primer/see-also
 
 toc::[]
 
-Adjusting text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines.
+Adjusting your text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines.
 
 [[editor-config-vim]]
 == Vim

documentation/content/en/books/fdp-primer/examples/chapter.adoc

@@ -22,7 +22,7 @@ prev: books/fdp-primer/see-also/
 
 toc::[]
 
-These examples are not exhaustive-they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].
+These examples are not exhaustive - they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].
 
 [[examples-asciidoctor-book]]
 == AsciiDoctor `book`

documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc

@@ -242,7 +242,7 @@ Some very common macros will be shown here. For more usage examples, see man:mdo
 
 [source,bash]
 ....
-% find /usr/shared/man/man* | xargs zgrep '.Bd'
+% find /usr/share/man/man* | xargs zgrep '.Bd'
 ....
 
 [[manual-pages-markup-important-macros-organizational]]
@@ -467,7 +467,7 @@ Some manual pages are suitable as in-depth examples.
 |[.filename]#/usr/src/bin/cp/cp.1#
 
 |man:vt[4]
-|[.filename]#/usr/src/shared/man/man4/vt.4#
+|[.filename]#/usr/src/share/man/man4/vt.4#
 
 |man:crontab[5]
 |[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5#

documentation/content/en/books/fdp-primer/overview/chapter.adoc

@@ -78,7 +78,7 @@ Review the output and edit the file to fix any problems shown, then rerun the co
 +
 [source,bash]
 ....
-make generate
+make
 ....
 +
 . When changes are complete and tested, generate a "diff file":

documentation/content/en/books/fdp-primer/preface/chapter.adoc

@@ -102,7 +102,7 @@ Notes are represented like this, and contain information to take note of, as it
 [TIP]
 ====
 
-Tips are represented like this, and contain information helpful to the user, like showing an easier way to do something.
+Tips are represented like this, and contain information helpful to the user, such as showing an easier way to do something.
 ====
 
 [IMPORTANT]

documentation/content/en/books/fdp-primer/structure/chapter.adoc

@@ -41,7 +41,7 @@ There are three sections under [.filename]#doc/#, documentation and website shar
 | Usage
 
 |[.filename]#documentation#
-|Contains all the articles and books in AsciiDoc format. Contains subdirectories to further categorize the information by languages
+|Contains all the articles and books in AsciiDoc format. Contains subdirectories to further categorize the information by languages.
 
 |[.filename]#shared#
 |Contains files that are not specific to the various translations of the documentation. Contains subdirectories to further categorize the information by languages and three files to store the authors, releases and mirrors information. This directory is shared between `documentation` and the `website`.
@@ -53,7 +53,7 @@ There are three sections under [.filename]#doc/#, documentation and website shar
 [[structure-locale]]
 == The Directories
 
-These directories contain the documentation and the website. The documentation is split into up to some directories this level. Following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure].
+These directories contain the documentation and the website. The documentation is organized into subdirectories below this level, following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure].
 
 [cols="20%,80%", frame="none", options="header"]
 |===
@@ -133,7 +133,7 @@ The [.filename]#chapters-order.adoc# file stores the order of the book chapters.
 
 [IMPORTANT]
 ====
-Please be careful with this file. Is used by the Python `tools` to generate the Table of Contents of the books. In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team.
+Please be careful with this file. It is used by the Python `tools` to generate the Table of Contents of the books. In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team.
 ====
 
 [[structure-document-handbook-physical-chapters]]
@@ -178,7 +178,7 @@ The articles are organized as an AsciiDoc `article`. The articles are divided in
 [[structure-document-articles-physical]]
 === Physical Organization
 
-There are a one [.filename]#_index.adoc# file per article.
+There is one [.filename]#_index.adoc# file per article.
 
 [[structure-document-articles-physical-index]]
 ==== _index.adoc

documentation/content/en/books/fdp-primer/translations/chapter.adoc

@@ -44,7 +44,7 @@ mailto:freebsd-translators@freebsd.org[freebsd-translators@freebsd.org] for gene
 
 == Are more translators needed?
 
-Yes. The more people work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents.
+Yes. The more people that work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents.
 
 You do not have to be a professional translator to be able to help.
 
@@ -60,7 +60,7 @@ It is strongly recommended that you maintain a local copy of the FreeBSD Git rep
 
 [source,bash]
 ....
-% git clone https://git.FreeBSD.org/doc.git doc
+% git clone https://cgit.FreeBSD.org/doc.git doc
 ....
 
 https://cgit.FreeBSD.org/[cgit.FreeBSD.org] is a public `git` server.
@@ -97,7 +97,7 @@ Write an email to the Documentation Project mailing list, announcing that you ar
 
 If there is already someone in your country providing FreeBSD mirroring services you should contact them and ask if you can have some webspace for your project, and possibly an email address or mailing list services.
 
-Then pick a document and start translating. It is best to start with something fairly small-either the FAQ, or one of the tutorials.
+Then pick a document and start translating. It is best to start with something fairly small - either the FAQ, or one of the tutorials.
 
 == I have translated some documentation, where do I send it?
 

documentation/content/en/books/fdp-primer/writing-style/chapter.adoc

@@ -121,10 +121,10 @@ Acronyms should be defined the first time they appear in a document, as in: "Net
 
 All acronyms should be enclosed using the ` character.
 
-[[writing-style-word-list]]
-== Word List
+[[writing-style-special-characters]]
+== Special Character List
 
-This list of words shows the correct spelling and capitalization when used in FreeBSD documentation. If a word is not on this list, ask about it on the {freebsd-doc}.
+This list of special characters shows the correct syntax and the output when used in FreeBSD documentation. If a character is not on this list, ask about it on the {freebsd-doc}.
 
 [.informaltable]
 [cols="1,1,1", frame="none", options="header"]