macOS® installation process

Tip	Hugo version 0.90 or higher must be used

1. Install these packages using Homebrew.

   $ brew install hugo ruby git bmake asciidoctor

2. Add Ruby and binaries installed by gem to the PATH.

   $ echo 'export GEM_PATH="/usr/local/lib/ruby/gems/3.1.0/bin"' >> ~/.zshrc
   $ echo 'export PATH="$GEM_PATH:/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

3. Install the rouge package using RubyGem.

   $ gem install rouge

4. Install a local working copy of the documentation from the FreeBSD repository in ~/doc (see crossref:working-copy[working-copy,The Working Copy]).

   $ git clone https://git.FreeBSD.org/doc.git ~/doc

5. Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input.

   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.

6. XXX Patch Makefile. XXX

   $ sed -i "" -e "s|\${LOCALBASE}/bin/rougify|\${GEM_PATH}/rougify|" ~/doc/documentation/Makefile

7. 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.

   $ bmake run

8. Add all the files with git add ., then review the diff with git diff. For example:

   % git add .
   % git diff --staged

   Make sure that all required files are included, then commit the change to your local branch and generate a patch with git format-patch

   % git commit
   % git format-patch origin/main

   Patch generated with git format-patch will include author identity and email addresses, making it easier for developers to apply (with git am) and give proper credit.

   Important

   To make it easier for committers to apply the patch on their working copy of the documentation tree, please generate the .diff from the base of your documentation tree.

9. Submit the patch or diff file using the web-based 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 patch or diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system.