linbit-documentation

linbit-documentation copied to clipboard

= Using the LINBIT Documentation Framework

== Rendered version

=== User's Guides If you are interested in the rendered version of the User's Guide, please read them at https://docs.linbit.com[docs.linbit.com].

=== Tech Guides You can download PDF versions for free from https://www.linbit.com/tech-guides-overview/[our home page].

== Build dependencies 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:

=== HTML targets (UGs/tech-guides)

• asciidoctor

=== HTML targets (man pages)

• mandoc

=== PDF targets

• https://github.com/asciidoctor/asciidoctor-pdf[asciidoctor-pdf]

== Fonts === LINBIT Fonts 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 https://github.com/asciidoctor/asciidoctor-pdf/tree/main/data/fonts[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 https://ftp.gnu.org/gnu/unifont/[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.

=== Japanese Fonts Before you generate PDF versions of the Japanese user's guides, download this https://packages.linbit.com/public/genshingothic-20150607.zip[zip archive]. Extract the archive to a fonts/genshingothic-fonts directory in the root of the documentation directory (linbit-documentation).

=== Chinese Fonts Before you generate PDF versions of the Chinese user's guides, download these "Simplified Chinese" (sc) font files:

• https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/NotoSansCJKsc-VF.ttf
• https://github.com/googlefonts/noto-cjk/raw/main/Sans/Variable/TTF/Mono/NotoSansMonoCJKsc-VF.ttf

After downloading these files, place them in a fonts/noto-cn directory in the root of the documentation directory (linbit-documentation).

=== Using Docker to Generate PDF Versions of Translated 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.

== Tech Guides We do not publish the source of our tech guides, make sure that you cloned the internal tech-guides repository.

== Makefile interface/API for projects

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.

=== PDF and HTML targets 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.

=== pdf-finalize and html-finalize targets 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.

=== Docker targets 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.

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

[[work-public]] == Working on a Public Project

• cd to the project (e.g, cd UG9/en)
• modify sources accordingly
• make pdf or make 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.

== Working on a Private Project

• make sure you are at the top-level of the framework (linbit-documentation)
• git clone the private project
• follow <>

== Style:

• http://asciidoctor.org/docs/asciidoc-writers-guide/[Read it, learn it, live it!]
• 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: