The used format of `-X, --long=VALUE` is not a valid option-list entry,
even though it is very commonly used all over the linux man-pages. Use
the supported format of `-X VALUE, --long=VALUE`, which will format
correctly in the man-page and html outputs.
For reference, these formats are valid in RST option-lists:
-a Short option
-c arg Short option with arg.
--long Long option.
-2, --two Aliases on a single line.
-f FILE, --file=FILE Aliases with arguments.
/V VMS/DOS-style option.
This rips out the `PIPELINE` section from osbuild(1) and instead adds a
new osbuild-manifest(5) man-page. This new man-page contains a rather
formal definition of the manifest, with a separate section for each
part of a manifest.
The man-page is exhaustive, in that it describes all available options.
However, it does *NOT* document the available stages, runners, and
assemblers. It does document the available (and supported) sources.
This should serve as an example how to document available stages and
assemblers in the future.
Note that it is not clear whether we should document these right now.
Once we decided to support the available stages for a reasonable
time-frame, we can start on documenting them as well.
This extends the EXAMPLES section with more examples, reduces their
complexity, and also restructures the layout to make it nicer to read
in the resulting TROFF file.
This adds a man-page `osbuild(1)` which documents the `osbuild`
executable. We use the python-native doc-utils and rely on
reStructuredText as documentation language.
While it is common with python libraries to use sphinx for documenting
the project, this commit explicitly does not import a full sphinx
documentation. Instead, it only adds the `rst` sources for man-pages.
These can be built by distributions via a simple:
rst2man docs/<manpage>.rst docs/<output-file>
