WIP: Use mdoc(7) and review documentation. #2

Closed

Ghost wants to merge 2 commits from documentation-review into master

Ghost commented

2018-12-29 04:54:15 +01:00

First-time contributor

This pull request suggests a change to the mdoc(7) documentation language, instead of the jack-of-all-trades / master-of-none markdown.

It also reviews a lot of the documentation and fixes some mistakes in the english.

Some of my objections to markdown as a documentation language can be found here

But I do have a few specific reasons:

mdoc(7) encodes more information than markdown and can be converted into it with mandoc(1), this is impossible to do with pandoc.
mandoc -T lint and makewhatis -t can be used to make sure our man(1) pages are valid, I am not aware of any tools to do this in the markdown ecosystem.
mdoc(7) is the official language for man(1) pages in Debian, OpenBSD and many other operating systems, this makes packaging and porting easier, as pandoc is a pretty large dependency to inflict on port maintainers.
The documentation is easier to read and search in the command line, as proper mdoc(7) can be indexed by makewhatis(8) and searched with apropos(1).

The new documentation is certain to have errors and missing information, so please review in detail using Gitea's pretty good review feature. I'm mostly worried about the values I used for the various defaults.

You can preview the man(1) pages with mandoc bkctl.8

This pull request suggests a change to the `mdoc(7)` documentation language, instead of the jack-of-all-trades / master-of-none `markdown`. It also reviews a lot of the documentation and fixes some mistakes in the english. Some of my objections to `markdown` as a documentation language can be found [here](https://undeadly.org/cgi?action=article&sid=20170304230520) But I do have a few specific reasons: 1. `mdoc(7)` encodes more information than `markdown` and can be converted into it with `mandoc(1)`, this is impossible to do with `pandoc`. 2. `mandoc -T lint` and `makewhatis -t` can be used to make sure our `man(1)` pages are valid, I am not aware of any tools to do this in the `markdown` ecosystem. 3. `mdoc(7)` is the official language for `man(1)` pages in Debian, OpenBSD and many other operating systems, this makes packaging and porting easier, as `pandoc` is a pretty large dependency to inflict on port maintainers. 4. The documentation is easier to read and search in the command line, as proper `mdoc(7)` can be indexed by `makewhatis(8)` and searched with `apropos(1)`. The new documentation is certain to have errors and missing information, so please review in detail using Gitea's pretty good review feature. I'm mostly worried about the values I used for the various defaults. You can preview the `man(1)` pages with `mandoc bkctl.8`