Page MenuHomeFreeBSD
Files F160380706

D47230.id.diff
No OneTemporary
Actions

D47230.id.diff
View Options

diff --git a/documentation/content/en/books/fdp-primer/workflow/_index.adoc b/documentation/content/en/books/fdp-primer/workflow/_index.adoc
--- a/documentation/content/en/books/fdp-primer/workflow/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/workflow/_index.adoc
@@ -47,7 +47,12 @@
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
-Creating new content, or modifying existing content requires an understanding of several coordinated processes, an understanding of how edits and content changes flow between them, and what happens at each step.
+Creating new content, or modifying existing content requires an understanding of:
+
+* Several coordinated processes,
+* How content changes as each process is applied, and
+* What happens at each step.
+
This section presents an overview of the Doc Team workflow and a detailed model that describes these steps.
[[workflow-overview]]
@@ -58,8 +63,7 @@
image::workflow-images01-overview.png["Doc Team Workflow Overview. Refer to paragraphs below."]
crossref:workflow[workflow-overview-image,Figure {counter:figure}]
-shows a high level overview of the current Doc Team workflow model (shaded green inside the dotted lines) and how it fits into the larger picture of FreeBSD development.
-
+shows a high level overview of the current Doc Team workflow model (shaded area inside the dotted lines) and how it fits into the larger picture of FreeBSD development.
The figure shows how the Doc Team workflow is similar to the workflow of other groups within the FreeBSD ecosystem such as the development teams and the porting teams.
Each group utilizes separate workflows and repositories to manage their own work.
@@ -130,7 +134,7 @@
At this point, the Author uses **git arc update** (12), with the same commit message, to update the original change set in Phabricator.
These latest changes are applied to the original change set as noted in (16).
-The Reviewer may request additional changes, in which case the above cycle is repeated until the Reviewer is satisfied that all changes have made (18).
+If the Reviewer requests additional changes, the above cycle is repeated until the Reviewer is satisfied that all changes have made (18).
The Reviewer then notifies (19) the Committer (20) that the changes are ready to be committed.
The Committer applies the commit (21) to the Doc Repository (2) and the process is complete.
====
@@ -141,7 +145,7 @@
[[workflow-git-references]]
== Git References
-The explanation above shows very basic usage of Phabricator, man:git[1], and the version of man:arcanist[1] integrated with man:git[1] used by the Doc Team.
+The explanation above shows very basic usage of Phabricator, man:git[1], and man:git-arc[1],the version of link:https://secure.phabricator.com/book/phabricator/article/arcanist/[arcanist] integrated with man:git[1] used by the Doc Team.
Access these resources for more information on man:git[1]:
* Pro Git Book – a free online comprehensive reference for using man:git[1].
@@ -152,5 +156,5 @@
* Seth Robertson's Documentation Projects with Git
** https://sethrobertson.github.io/
-References for man:arcanist[1] and Phabricator, along with additional examples, are shown in the next chapter.
+References for man:git-arc[1] and Phabricator, along with additional examples, are shown in the next chapter.
diff --git a/documentation/content/en/books/fdp-primer/working-copy/_index.adoc b/documentation/content/en/books/fdp-primer/working-copy/_index.adoc
--- a/documentation/content/en/books/fdp-primer/working-copy/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/working-copy/_index.adoc
@@ -376,7 +376,7 @@
====
Testing the manual page change can be done by using `textproc/mantra`, a program that can be found in the ports/packages collection.
-The man:mantra[1] package requires the use of man:tmux[1], a terminal multiplexer, but it is not necessary to know how to use man:tmux[1].
+The `textproc/mantra` package requires the use of man:tmux[1], a terminal multiplexer, but it is not necessary to know how to use man:tmux[1].
Navigate to the directory where the newly changed manual page can be found:
@@ -387,7 +387,7 @@
crossref:working-copy[working-copy-image-example1-testing-patch1,Figure {counter:figure}]
shows getting ready to test the patch.
-Run man:tmux[1] in this directory.
+Run `tmux` in this directory.
The screen will clear and a green status bar will appear at the bottom of the screen:
[[working-copy-image-example1-testing-patch2]]
@@ -395,7 +395,7 @@
image::working-copy-images10-starting-tmux.png["Starting tmux(1) to run mantra(1). Refer to paragraphs below."]
crossref:working-copy[working-copy-image-example1-testing-patch2,Figure {counter:figure}]
-shows starting man:tmux[1] in preparation to run man:mantra[1].
+shows starting `tmux` in preparation to run `mantra`.
Then run `mantra <filename>`.
Mantra will load and display the manual page file showing the corrections.
@@ -412,11 +412,20 @@
image::working-copy-images11-running-mantra.png["Running mantra(1) to Test Applied Patch. Refer to paragraphs below."]
crossref:working-copy[working-copy-image-example1-testing-patch3,Figure {counter:figure}]
-shows running man:mantra[1] to verify the patch.
+shows running `mantra` to verify the patch.
-If additional edits to the file are required, they can be applied while man:mantra[1] is running.
-man:mantra[1] will auto-reload to show the latest changes.
-When finished making and reviewing the changes, exit man:mantra[1] and man:tmux[1].
+If additional edits to the file are required, they can be applied while `mantra` is running.
+`mantra` will auto-reload to show the latest changes.
+
+Additional considerations for manual pages include:
+
+* Try to limit the line length for manual pages to about 72 characters.
+* The link:https://mandoc.bsd.lv[mandoc style guide] suggests that when wrapping lines, wrap as close to the middle as possible.
+* Try not to break up phrases when wrapping as it makes searching the source text more problematic.
+
+Following these suggestions will help future maintainers.
+
+When finished making and reviewing the changes, exit `mantra` and `tmux`.
Then, from the top of the src directory run `git add` to stage the change:

File Metadata

Mime Type
text/plain
Expires
Wed, Jun 24, 10:29 PM (20 h, 2 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34277278
Default Alt Text
D47230.id.diff (6 KB)

Event Timeline