Just like the last commit, but now for manpages.
genMan still works with a buffer and returns []byte instead of working
directly with an io.Writer. This is because, in turn, md2man takes byte
slices instead of readers and writers.
Wrapping genMan around a writer is unnecessary especially since it's not
an exported function, and also because we'd still need a buffer to get
the output bytes.
This code was already using io.Writer, but was completely ignoring write
errors.
The most worrying part is how GenMarkdownTreeCustom used an unnecessary
buffer to then dump all of its contents on a file, and instead of
returning an error on file creation/writing, it would just exit the
entire program.
Since the switch from *bytes.Buffer to io.Writer, errors can no longer
be ignored. Also makes the reuse of GenBashCompletion in
GenBashCompletionFile without a buffer treat errors properly again.
* Move man_docs and md_docs into new doc pkg
* Replace *bytes.Buffer with io.Writer
* Replace c == cmd.helpCommand with c.IsHelpCommand()
* Remove redundant len(children) == 0 check in HasSeeAlso
* Duplicate test setup for doc generation
If the user did not define header.Title when calling GenManTree(),
reset it after each call to GenMan(), otherwise the entire man page tree
would be stuck with the full command name that was calculated for the
first man page, leaving all subsequent man pages with an identical
but incorrect title.
This patch fixes the problem where lexgrog fails to parse the NAME section
when the provided command contains space, e.g. "rootcmd subcmd".
Explanation from Lintian:
Each manual page should start with a "NAME" section, which lists the
name and a brief description of the page separated by "\-". The "NAME"
section is parsed by lexgrog and used to generate a database that's
queried by commands like apropos and whatis. This tag indicates that
lexgrog was unable to parse the NAME section of this manual page.
For manual pages that document multiple programs, functions, files, or
other things, the part before "\-" should list each separated by a comma
and a space. Each thing listed must not contain spaces; a man page for a
two-part command like "fs listacl" must use something like "fs_listacl"
in the "NAME" section so that it can be parsed by lexgrog.
Ref: lexgrog(1), groff_man(7), groff_mdoc(7)
Anthony Fok