Feedback on container "help" file specification

[jmtd]

Hi, three years I filed a similar issue in the older projeect atomic repository projectatomic/container-best-practices#131, and most of the points I made then are still a problem now.

Looking at modules/ROOT/pages/guidelines/help_file.adoc:

• it's not clear what dialect of Markdown or features that are supported
• It does not make clear whether you can include the help.1 file directly to skip OSBS generating it
• It does not state whether the help.md file gets copied into the container too
• What tooling either consumes or produces these files?

The Red Hat OpenJDK container images include a help.md file which is generated by the tooling we use (cekit) and based on the earlier guidelines from the projectatomic repository. This uses a very limited subset of MarkDown functionality to reduce the risk of conversion problems with the tooling. In particular we do not use tables, although it would be very useful to do so, as we want to document ~100 environment variables in some manner easy to read. The current scheme survived the conversion to ROFF format but is pretty inadequate.

I also notice that, somewhere along the way, RH OSBS stopped generating or including the help.1 file in the final images anyway.

I really like the idea of including structured help in containers and having a consistent format for the included information. Is anyone else actually using this stuff?