If you are interested in the rendered version of the User’s Guide, please read them at docs.linbit.com.
You can download PDF versions for free from our home page.
If you have docker, execute make dockerimage, which will generate a "linbit-documentation" base
Docker image containing all the dependencies for generating HTML and PDF outputs.
Otherwise you will need GNU make and you have to install the following dependencies:
We do not publish the official LINBIT fonts that are used to generate official LINBIT
documentation. Public projects have to be able to generate PDFs without LINBIT fonts, If you
have a public project, create a linbit-fonts directory in the documentation root directory
(linbit-documentation) and then download and extract into that directory the
necessary M+ fonts that are
used as a fallback font set:
-
mplus1mn-bold-subset.ttf
-
mplus1mn-bold_italic-subset.ttf
-
mplus1mn-italic-subset.ttf
-
mplus1mn-regular-subset.ttf
Public projects should also download the GNU Unifont font (available
here), rename the downloaded file unifont.ttf, and put it
into a linbit-fonts directory, along with the M+ font files.
Private projects are allowed to fail if the linbit-fonts directory does not exist.
Actually they should fail, which is the default anyways.
If you build official PDFs/private projects, make sure that you cloned the internal linbit-fonts repository.
Before you generate PDF versions of the Japanese user’s guides, download this
zip archive. Extract the archive to a
fonts/genshingothic-fonts directory in the root of the documentation directory
(linbit-documentation).
Before you generate PDF versions of the Chinese user’s guides, download these "Simplified
Chinese" (sc) font files:
After downloading these files, place them in a fonts/noto-cn directory in the root of the
documentation directory (linbit-documentation).
For Japanese and Chinese translated documentation, you can simply build the
linbit-documentation Docker image and the build process will bring in the necessary font files
for Japanese and Chinese PDF documentation building, as described above. You can then use the
-docker make targets for various documentation building tasks, while setting lang=
appropriately.
We do not publish the source of our tech guides, make sure that you cloned the internal tech-guides repository.
Projects are organized in subdirectories, for example the user’s guide for DRBD 9 is in UG9. The top level
Makefile contains HTML and PDF targets for these (e.g., make UG9-pdf-finalize). The final output is
generated in $project/$lang/output-$format-finalize (e.g. UG9/en/output-pdf-finalize).
Every project needs a proper Makefile that has the following targets:
-
pdf -
pdf-finalize -
html -
html-finalize
If a project only generates PDF output, implement the HTML targets as empty.
These generate their output to output-$format. It is perfectly fine that these directories contain temporary
files like symlinks. As already written, we want proper Makefiles, so if the source does not change
re-executing these targets should only process files that changed.
These generate their output to output-$format-finalize. This is the final output. The one that is
published to a web page/sent to a web developer. For example this generates tar archive files for UG9 that can be
sent to someone who puts it on the web page.
It is usually the final target that is executed after multiple iterations of make pdf/make html and it is
fine if that target alters the content of output-$format to generate output-$format-finalize. If possible
it should not, but it is not a strict requirement.
The top-level Makefile also contains targets that end in "-docker". These can be used to generate the
output with the previously described "linbit-documentation" base image. For example one can execute
make UG9-html-finalize-docker.
The -docker make targets depend on the "local" make targets. Using the Docker targets is preferred, for consistent results, unless you have a reason not to use them. As of January 2023, local make targets are untested and unsupported, except as they are run through the linbit-documentation Docker image.
The English version is the default, but if you want to build the Japanese version, you have to set the make
variable "lang" accordingly (e.g., make UG9-html-finalize-docker lang=ja).
Japanese version is created by English .adoc files and Japanese .po files.
Pot files used for localization can be created by the pot target,
(e.g, `make UG9-pot-docker).
Make sure created pot files include correct sentences.
-
cdto the project (e.g,cd UG9/en) -
modify sources accordingly
-
make pdformake html
Output is generated in output-$format. These directories (in contrast to output-$format-finalize) can
contain temporary files (symlinks, processed adoc files,…). When you are satisfied, make $format-finalize,
to generate the final output in output-$format-finalize.
-
make sure you are at the top-level of the framework (
linbit-documentation) -
git clonethe private project -
follow Working on a Public Project
-
Hostnames: 'bob' ⇒ 'bob'
-
Commands: `rm -rf` ⇒
rm -rf -
DRBD states: _Primary_ ⇒ Primary
-
Blocks: Add newline before and after the block. Delimit blocks using four (4) hyphens only. For example:
* Re-enable your DRBD resource:
----
# drbdadm up <resource>
----
* On one node, promote the DRBD resource: