Markdown syntax problems in manpages

[DanLipsitt]

There are errors in the manpages because parameters in angle brackets aren't included in md2man output. For example,

**ADD ["<src>"... "<dest>"]** This form is required for paths containing whitespace.

renders as

ADD [""... ""] This form is required for paths containing whitespace.

Note the missing <src> and <dest>.
This can also be seen in GitHub's rendering of the text:

ADD [""... ""] This form is required for paths containing whitespace.

---

PROBLEM: man docs are often imporoperly formatted, using quotes or bolds when code blocks/segments are required

PROPOSED SOLUTION: man docs should be updated to use appropriate backticks for either inline or blocked code.
The dockerfile.5.md has already been gone through, but wouldn't hurt another set of eyes.

[jessfraz]

ping @cpuguy83

On Mon, Feb 9, 2015 at 12:41 PM, Dan Lipsitt notifications@github.com
wrote:

There are errors in the manpages because parameters in angle brackets
aren't included in md2man output. For example
https://github.com/docker/docker/blame/master/docs/man/Dockerfile.5.md#L137,

ADD [""... ""] This form is required for paths containing whitespace.

renders as

ADD [""... ""] This form is required for paths containing whitespace.

Note the missing and .
This can also be seen in GitHub's rendering of the text:

ADD [""... ""] This form is required for paths containing whitespace.

—
Reply to this email directly or view it on GitHub
#10667.

[cpuguy83]

Thanks, let me take a look.

[tianon]

Since this isn't fixed in docker/docker yet, I think it's appropriate that we leave this open. 😉

[cpuguy83]

Sorry, didn't realize GH would auto-close :)

[cpuguy83]

btw, I don't like the fix I put in since it's perfectly valid to use raw html in MD, but I think it's better than not rendering anything at all.

[DanLipsitt]

What happens if you use backticks to protect the params (<foo>)? Sorry I don't have time to experiment right now.

[thaJeztah]

Is using <something> the standard way to notate things in man-pages, or a convention that Docker uses?

Asking, because the same problem occurred on a couple of pages of the documentation as well; the values did not show up on GitHub when viewing the docs.

If it is not a standard notation in man-pages, perhaps Docker should use a different convention in stead of modifying md2man, because other MarkDown renderers have the same problem.

[cpuguy83]

@thaJeztah It's pretty common when writing CLI docs to use <something> as a way to indicate a required argument (vs [something] as not required)

[duglin]

can md2man be made to support < and > ?

[cpuguy83]

@duglin Can you open an issue on the repo with what you expect it to output?

[thaJeztah]

@cpuguy83 thanks for explaining.

btw, I don't like the fix I put in since it's perfectly valid to use raw html in MD, but I think it's better than not rendering anything at all.

Looking at the man-page on GitHub, the pages look mangled as well. I think the problem overall is that they use a bit of a "MarkDown-ish" syntax; everything is assumed to be "<pre>" and only a sub-set of MarkDown (Head (#), bold and italic) is used.

I think from that perspective, it's reasonable to not support HTML?

[tianon]

Yeah, I tend to agree that this looks like a bug in our use of Markdown here, not a bug in go-md2man.

[thaJeztah]

Perhaps call it MarkDown-flavoured plain-text, and change the file extension to .txt, to make it better readable on GitHub as well.

[duglin]

Opened issue in md2man: cpuguy83/go-md2man#11

[jessfraz]

so what was the outcome here @cpuguy83 can you triage and add the right labels so someone can contribute it to fix it if they see this issue

[cpuguy83]

Triaged

[cpuguy83]

Closing since these man pages were updated.
If anyone sees a specific problem, please open a new issue with that specific problem.

Thanks!