diff --git a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc index 146f32ad11..c39adf8a40 100644 --- a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc +++ b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc @@ -1,284 +1,323 @@ --- title: Chapter 5. The FreeBSD Documentation Build Process prev: books/fdp-primer/structure next: books/fdp-primer/asciidoctor-primer description: Describes the FreeBSD Documentation Build Process tags: ["build", "process", "make"] --- [[doc-build]] = The FreeBSD Documentation Build Process :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 5 toc::[] This chapter covers organization of the documentation build process and how man:make[1] is used to control it. [[doc-build-rendering]] == Rendering AsciiDoc into Output Different types of output can be produced from a single AsciiDoc source file. [cols="20%,20%,60%", frame="none", options="header"] |=== | Formats | File Type | Description |`html` |HTML |An `article` or `book` chapter. |`pdf` |PDF |Portable Document Format. |`epub` |EPUB |Electronic Publication. ePub file format. |=== [[doc-build-rendering-html]] === Rendering to html To render the documentation and the website to `html` use one of the following examples. [[documentation-build-example]] .Build the documentation [example] ==== [source,shell] .... % cd ~/doc/documentation % make .... ==== [[website-build-example]] .Build the website [example] ==== [source,shell] .... % cd ~/doc/website % make .... ==== [[project-build-example]] .Build the entire documentation project [example] ==== [source,shell] .... % cd ~/doc % make -j2 .... ==== +Advanced build examples are given below: + +[[documentation-build-example-verbose]] +.Build the documentation with verbose and debug messages +[example] +==== +[source,shell] +.... +% cd ~/doc/documentation +% make HUGO_ARGS="--verbose --debug --path-warnings" +.... +==== + +[[documentation-build-example-server]] +.Build and serve the content with Hugo’s internal webserver +[example] +==== +[source,shell] +.... +% cd ~/doc/documentation +% make run +.... +This webserver runs on `localhost`, port `1313` by default. + +To serve the content with Hugo’s internal webserver binding a specific IP address: + +[source,shell] +.... +% make run BIND=192.168.15.10 +.... + +A `hostname` can also be set as base url to Hugo’s internal webserver: + +[source,shell] +.... +% make run BIND=192.168.15.10 HOSTNAME=example.com +.... +==== + [[doc-build-rendering-pdf]] === Rendering to pdf To generate a document in `pdf` format use this command. In this example the English Handbook will be used. In order to export the document correctly all the extensions should be passed using the `-r` argument. [[document-pdf-example]] .Build a document in pdf [example] ==== [source,shell] .... % cd ~/doc/documentation % asciidoctor-pdf \ -r ./shared/lib/man-macro.rb \ -r ./shared/lib/git-macro.rb \ -r ./shared/lib/packages-macro.rb \ -r ./shared/lib/inter-document-references-macro.rb \ -r ./shared/lib/sectnumoffset-treeprocessor.rb \ --doctype=book \ -a skip-front-matter \ -a pdf-theme=./themes/default-pdf-theme.yml \ -o /tmp/handbook.pdf \ content/en/books/handbook/book.adoc .... ==== [[doc-build-toolset]] == The FreeBSD Documentation Build Toolset These are the tools used to build and install the FDP documentation. * The primary build tool is man:make[1], specifically Berkeley Make. * Python is used to generate the Table of Contents and other related Tables. * Hugo * AsciiDoctor * Git [[doc-build-makefile]] == Understanding the Makefile in the Documentation Tree There are three [.filename]#Makefile# files for building some or all of the documentation project. * The [.filename]#Makefile# in the [.filename]#documentation# directory will build only the documentation. * The [.filename]#Makefile# in the [.filename]#website# directory will build only the website. * The [.filename]#Makefile# at the top of the tree will build both the documentation and the website. The [.filename]#Makefile# appearing in subdirectories also support `make run` to serve built content with Hugo's internal webserver. This webserver runs on port 1313 by default. [[documentation-makefile]] === Documentation Makefile This [.filename]#Makefile# takes the following form: [source,shell] .... # Generate the FreeBSD documentation # # Copyright (c) 2020-2021, The FreeBSD Documentation Project # Copyright (c) 2020-2021, Sergio Carlavilla # # Targets intended for use on the command line # # all (default) - generate the books TOC and compile all the documentation # run - serves the built documentation site for local browsing # # The run target uses hugo's built-in webserver to make the documentation site # available for local browsing. The documentation should have been built prior # to attempting to use the `run` target. By default, hugo will start its # webserver on port 1313. MAINTAINER=carlavilla@FreeBSD.org <.> PYTHON_CMD = /usr/local/bin/python3 <.> HUGO_CMD = /usr/local/bin/hugo <.> LANGUAGES = en,es,pt_BR,de,ja,zh_CN,zh_TW,ru,el,hu,it,mn,nl,pl,fr <.> RUBYLIB = ../shared/lib .export RUBYLIB .ifndef HOSTNAME .HOST+=localhost .else .HOST+=$(HOSTNAME) .endif .ORDER: all run<.> .ORDER: starting-message generate-books-toc .ORDER: starting-message build .ORDER: generate-books-toc build all: starting-message generate-books-toc build <.> starting-message: .PHONY <.> @echo --------------------------------------------------------------- @echo Building the documentation @echo --------------------------------------------------------------- generate-books-toc: .PHONY <.> ${PYTHON_CMD} ./tools/books-toc-parts-creator.py -l ${LANGUAGES} ${PYTHON_CMD} ./tools/books-toc-creator.py -l ${LANGUAGES} ${PYTHON_CMD} ./tools/books-toc-figures-creator.py -l ${LANGUAGES} ${PYTHON_CMD} ./tools/books-toc-tables-creator.py -l ${LANGUAGES} ${PYTHON_CMD} ./tools/books-toc-examples-creator.py -l ${LANGUAGES} run: .PHONY <.> ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313" build: .PHONY <.> ${HUGO_CMD} --minify .... <.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile. <.> `PYTHON_CMD` flag specifies the location of the Python binary. <.> `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 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 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# takes the form of: [source,shell] .... # Generate the FreeBSD website # # Copyright (c) 2020-2021, The FreeBSD Documentation Project # Copyright (c) 2020-2021, Sergio Carlavilla # # Targets intended for use on the command line # # all (default) - generate the releases.toml and compile all the website # run - serves the built documentation site for local browsing # # The run target uses hugo's built-in webserver to make the documentation site # available for local browsing. The documentation should have been built prior # to attempting to use the `run` target. By default, hugo will start its # webserver on port 1313. MAINTAINER=carlavilla@FreeBSD.org <.> PYTHON_CMD = /usr/local/bin/python3 <.> HUGO_CMD = /usr/local/bin/hugo <.> RUBYLIB = ../shared/lib .export RUBYLIB .ifndef HOSTNAME .HOST+=localhost .else .HOST+=$(HOSTNAME) .endif .ORDER: all run<.> .ORDER: starting-message generate-releases .ORDER: starting-message build .ORDER: generate-releases build all: starting-message generate-releases run <.> starting-message: .PHONY <.> @echo --------------------------------------------------------------- @echo Building the website @echo --------------------------------------------------------------- generate-releases: .PHONY <.> ${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc run: .PHONY <.> ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313" build: .PHONY <.> ${HUGO_CMD} .... <.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile. <.> `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 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 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#. diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc index 2fef4f9b53..fcea50e851 100644 --- a/documentation/content/en/books/fdp-primer/overview/_index.adoc +++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc @@ -1,124 +1,117 @@ --- title: Chapter 1. Overview prev: books/fdp-primer/preface next: books/fdp-primer/tools description: Overview about the FreeBSD Documentation Process tags: ["overview", "FreeBSD Documentation Project", "quick start"] --- [[overview]] = Overview :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 1 include::shared/releases.adoc[] include::shared/en/mailing-lists.adoc[] Welcome to the FreeBSD Documentation Project (FDP). Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly. This document describes how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools. Everyone is welcome to contribute to the FDP. Willingness to contribute is the only membership requirement. This primer shows how to: * Identify which parts of FreeBSD are maintained by the FDP. * Install the required documentation tools and files. * Make changes to the documentation. * Submit changes back for review and inclusion in the FreeBSD documentation. [[overview-quick-start]] == Quick Start Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the {freebsd-doc}. Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet]. These people can help with questions or problems involving the documentation. [.procedure] ==== -. Install these packages. These packages are all of the software needed to edit and build FreeBSD documentation. The Git package is needed to obtain a working copy of the documentation and generate patches with. +. Install these packages. The `docproj` _meta-port_ installs all the applications required to do useful work with the FreeBSD documentation. + [source,shell] .... -# pkg install gohugo python3 git-lite rubygem-asciidoctor rubygem-rouge -.... -+ -. Optional: to generate PDF documentation install `asciidoctor-pdf` -+ -[source,shell] -.... -# pkg install rubygem-asciidoctor-pdf +# pkg install docproj python3 .... + . Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]). + [source,shell] .... % git clone https://git.FreeBSD.org/doc.git ~/doc .... + . 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 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. + [source,shell] .... % make .... + . When changes are complete and tested, generate a "diff file": + [source,shell] .... % cd ~/doc % git diff > bsdinstall.diff.txt .... + Give the diff file a descriptive name. In the example above, changes have been made to the [.filename]#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. ==== [[overview-doc]] == The FreeBSD Documentation Set The FDP is responsible for four categories of FreeBSD documentation. * _Handbook_: The Handbook is the comprehensive online resource and reference for FreeBSD users. * _FAQ_: The FAQ uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to FreeBSD. This format does not permit long and comprehensive answers. * _Manual pages_: The English language system manual pages are usually not written by the FDP, as they are part of the base system. However, the FDP can reword parts of existing manual pages to make them clearer or to correct inaccuracies. * _Web site_: This is the main FreeBSD presence on the web, visible at https://www.freebsd.org/[https://www.FreeBSD.org/] and many mirrors around the world. The web site is typically a new user's first exposure to FreeBSD. Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages are not translated at present. Documentation source for the FreeBSD web site, Handbook, and FAQ is available in the documentation repository at `https://cgit.freebsd.org/doc/`. Source for manual pages is available in a separate source repository located at `https://cgit.freebsd.org/src/`. Documentation commit messages are visible with `git log`. Commit messages are also archived at link:{git-doc-all}. Web frontends to both of these repositories are available at https://cgit.freebsd.org/doc/[] and https://cgit.freebsd.org/src/[]. Many people have written tutorials or how-to articles about FreeBSD. Some are stored as part of the FDP files. In other cases, the author has decided to keep the documentation separate. The FDP endeavors to provide links to as much of this external documentation as possible. diff --git a/documentation/content/en/books/fdp-primer/tools/_index.adoc b/documentation/content/en/books/fdp-primer/tools/_index.adoc index 459ce9aa5b..a5acaf0859 100644 --- a/documentation/content/en/books/fdp-primer/tools/_index.adoc +++ b/documentation/content/en/books/fdp-primer/tools/_index.adoc @@ -1,51 +1,51 @@ --- title: Chapter 2. Tools prev: books/fdp-primer/overview next: books/fdp-primer/working-copy description: Tools used in the FreeBSD Documentation Project tags: ["tools", "required tools", "optional tools"] --- [[tools]] = Tools :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 2 toc::[] Several software tools are used to manage the FreeBSD documentation and render it to different output formats. Some of these tools are required and must be installed before working through the examples in the following chapters. Some are optional, adding capabilities or making the job of creating documentation less demanding. [[tools-required]] == Required Tools -Install `gohugo` and `rubygem-asciidoctor` as shown in crossref:overview[overview,the overview chapter] from the Ports Collection. +Install `docproj` and `python3` as shown in crossref:overview[overview,the overview chapter] from the Ports Collection. These applications are required to do useful work with the FreeBSD documentation. Some further notes on particular components are given below. [[tools-optional]] == Optional Tools These applications are not required, but can make working on the documentation easier or add capabilities. [[tools-optional-software]] === Software Vim (package:editors/vim[]):: A popular editor for working with AsciiDoctor. Emacs (package:editors/emacs[]):: Both of these editors include a special mode for editing documents. This mode includes commands to reduce the amount of typing needed, and help reduce the possibility of errors.