= 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
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
- inkscape

=== 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 in that repository. Public projects have to be able to generated
pdfs without LINBIT's fonts, private ones 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 you cloned the internal `linbit-fonts` repository.

=== Japanese Fonts
If you intend to generate the `pdf` versions of the Japanese users guides, make sure you downloaded this
https://packages.linbit.com/public/genshingothic-20150607.zip[zip archive]. Extract the archive to a
`genshingothic-fonts` directory in the root of the documentation.

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

== Makefile interface/API for projects
Projects are organized in sub directories, for example the users 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 ``Makefile``s, 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-balls 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 describe "linbit-documentation" base image. For example one can execute
`make UG9-html-finalize-docker`.

=== 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 <<work-public>>

== 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 of the block.
```
* Re-enable your DRBD resource:

----------------------------
# drbdadm up <resource>
----------------------------

* On one node, promote the DRBD resource:
```
