diff options
Diffstat (limited to 'documentation/content/en/books/fdp-primer/overview/_index.adoc')
| -rw-r--r-- | documentation/content/en/books/fdp-primer/overview/_index.adoc | 52 |
1 files changed, 29 insertions, 23 deletions
diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc index c1a907a89f9..c316176b05e 100644 --- a/documentation/content/en/books/fdp-primer/overview/_index.adoc +++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc @@ -6,7 +6,8 @@ description: Overview about the FreeBSD Documentation Process tags: ["overview", "FreeBSD Documentation Project", "quick start"] showBookMenu: true weight: 2 -path: "/books/fdp-primer/" +params: + path: "/books/fdp-primer/overview/" --- [[overview]] @@ -129,13 +130,24 @@ These people can help with questions or problems involving the documentation. Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved. + -. *_Always_* build and test the changes before submitting them. Running `make` in the top-level directory of the documentation will generate that documentation in HTML format. +. *_Always_* build and review the changes before submitting them. Running `make` in the `documentation` or `website` subdirectories will generate the documentation in HTML format. + [source,shell] .... % make .... + +To reduce compile time, only one language can be compiled: ++ +[source,shell] +.... +% make DOC_LANG=en +.... ++ +The build output is stored in [.filename]#~/doc/documentation/public/en/articles/# and [.filename]#~/doc/documentation/public/en/books/#. ++ +. Review the build output and ensure the edits are free from typos, layout problems, or errors. If any errors are found during the build process, edit the problematic files to fix any issues that show up, then run the build command again until all errors are resolved. ++ . Add all the files with `git add .`, then review the diff with `git diff`. For example: + [source,shell] @@ -163,7 +175,7 @@ please generate the [.filename]#.diff# from the base of your documentation tree. + In the example above, changes have been made to the *bsdinstall* portion of the Handbook. + -. Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system. +. Submit the patch or diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the patch or diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system. ==== [[gnu-linux-installation-process]] @@ -171,11 +183,6 @@ In the example above, changes have been made to the *bsdinstall* portion of the [.procedure] ==== -[TIP] -====== -Hugo version 0.90 or higher must be used -====== - . Install these packages in apt-based systems like Debian or Ubuntu. On other GNU/Linux distributions the package names may change. Consult your distribution's package manager if in doubt. @@ -197,7 +204,7 @@ Consult your distribution's package manager if in doubt. Review the output and edit the files to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved. + -. Always build and test the changes before submitting them. Running `bmake` in the top-level directory of the documentation will generate that documentation in HTML format. +. Always build and test the changes before submitting them. Running `bmake` in the `documentation` or `website` subdirectories will generate the documentation in HTML format. + [source,shell] .... @@ -229,11 +236,11 @@ To make it easier for committers to apply the patch on their working copy of the please generate the [.filename]#.diff# from the base of your documentation tree. ====== + -. Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. +. Submit the patch or diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the problem in the _Summary_ field and add _patch_ to the _Keywords_ field. -Use the btn:[Add an attachment] button to attach the diff file. +Use the btn:[Add an attachment] button to attach the patch or diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system. ==== @@ -242,30 +249,29 @@ Finally, use the btn:[Submit Bug] button to submit your diff to the problem repo [.procedure] ==== -[TIP] -====== -Hugo version 0.90 or higher must be used -====== . Install these packages using link:https://brew.sh/[Homebrew] and link:https://rubygems.org/[RubyGem]. + [source,shell] .... -$ brew install hugo ruby git bmake asciidoctor +$ brew install hugo ruby git bmake .... + . Add Ruby to the Path. + [source,shell] .... -$ echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc +$ echo 'export PATH="$(brew --prefix ruby)/bin:$PATH"' >> ~/.zshrc +$ echo 'export PATH="$(brew --prefix hugo)/bin:$PATH"' >> ~/.zshrc +$ echo 'export GEM_PATH="$(gem environment gemdir)"' >> ~/.zshrc +$ echo 'export PATH="${GEM_PATH}/bin:$PATH"' >> ~/.zshrc +$ source ~/.zshrc .... -+ . Install the rouge package using RubyGem. + [source,shell] .... -$ sudo gem install rouge +$ sudo gem install rouge asciidoctor asciidoctor-pdf asciidoctor-epub3 .... + . Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]). @@ -280,11 +286,11 @@ $ git clone https://git.FreeBSD.org/doc.git ~/doc Review the output and edit the files to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved. + -. Always build and test the changes before submitting them. Running `bmake` in the top-level directory of the documentation will generate that documentation in HTML format. +. Always build and test the changes before submitting them. Running `bmake` in the `documentation` or `website` subdirectories will generate the documentation in HTML format. + [source,shell] .... -$ bmake run LOCALBASE=/usr +$ bmake run USE_RUBYGEMS=YES RUBY_CMD="$(brew --prefix ruby)/bin/ruby" HUGO_CMD="$(brew --prefix hugo)/bin/hugo" .... . Add all the files with `git add .`, then review the diff with `git diff`. For example: + @@ -311,11 +317,11 @@ To make it easier for committers to apply the patch on their working copy of the please generate the [.filename]#.diff# from the base of your documentation tree. ====== + -. Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. +. Submit the patch or diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the problem in the _Summary_ field and add _patch_ to the _Keywords_ field. -Use the btn:[Add an attachment] button to attach the diff file. +Use the btn:[Add an attachment] button to attach the patch or diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system. ==== |