some feedback on the help.md/.1 guidelines

[jmtd]

Hi, I've been looking at this for the middleware images looked after by Cloud Enablement, and I have some early feedback. I will revise this issue/comments as my feedback develops.

It seems an interesting design choice to make the canonical in-image help file the roff/nroff/troff-formatted "help.1" file, especially if the intention is for the help information to be consumed by various other systems and republished. This appears to have been strongly influenced by the first (and so far, only?) tool to consume it. "atomic help" which (I presume) is acting as a thin pipe through to man(1). You don't stipulate precisely which roff language variation should be use here, I guess you are assuming the host system is using GNU man and whatever that implies for the format, but it would be good to state it.

The Markdown-formatted version of the file, I would have thought was more useful for other tools to parse, but my reading of the guidelines at the moment, it's strictly optional. If someone provides a .md file, it will be converted into the help.1 file by atomic reactor. But if you instead explicitly provided a help.1 file and added it to / yourself, it should stil work. (right?) Hence, the markdown file is not mandated by the guidelines.

Why would anyone do that you might ask? Well, in our case we are likely to be auto-generating the help page via a template. We use cekit to generate our Dockerfiles and associated artefacts from an input YAML file. We already template the Dockerfile, so we would likely template the help file too. And if we're doing that, we could skip markdown and go straight to the help.1. The main stated reason for providing the markdown in image sources would be to have them rendered nicely if the image sources were being browsed on GitHub, but if we are generating them, they would not be committed to our image sources anyway.

The other problem with the use of Markdown in these guidelines is you don't strictly specify which version of Markdown you actually mean. And we can't assume some safe subset of all popular implementations because your examples include a construction like this

MYSQL_PASSWORD=mypass
                The password set for the current MySQL user.

which is not a semantically meaningful construction in many markdown implementations (including, I think, GitHub-Flavored-Markdown) and a sequence of these will just be a run-on sentence.

Whilst investigating exactly which Markdown you are impling, I chased down the tool chain: atomic uses go-md2man (which states "** Work in Progress ** This still needs a lot of help to be complete, or even usable!" in it's README), go-md2man seems to punt the issue to its backend blackfriday, which says "markdown with common extensions", again, which markdown? the original? CommonMark?

So from a generator POV we side-step all the issues of Markdown version clarity by going straight to roff and we are left with just the issues of roff/troff/nroff ambiguity. But I can't help but think that the intention of the guidelines may have originally been to have the markdown itself be canonical, since it might be more easy to consume by other tools than roff, and it's just ended up a bit backwards because the first concrete tool ended up being "atomic help".

[jmtd]

Can anyone explain what is the purpose / what consumes the percent-prefixed lines in the examples? These lines

% IMAGE_NAME (1) Container Image Pages
% MAINTAINER
% DATE

I don't think this is legit markdown, is it something that is specifically consumed by the atomic tool to process the markdown into man format?

[jmtd]

It's been a couple of years since I raised this issue and I've circled around to looking at a documentation issue again so I've tried to remind myself of this specification. No feedback at all here. Did anyone actually adopt this guideline?

[LorbusChris]

@jmtd the canonical location of the container docs has been at https://github.com/containers/docs for a while now