[ahnick]

I like the idea of combining the header with the help documentation to reduce the number of areas to maintain in smaller scripts. For larger scripts though, I think I'd still prefer to have a separate function, so that the help documentation doesn't overwhelm the initial viewing of the actual code.

I also like to feed a heredoc directly into man, which allows you to achieve nicer formatting for the help documentation. Something like this...

  man -l - << EOF
  .\" Manpage for encpass.sh.
  .\" Email [e-mail] to correct errors or typos.
  .TH man 8 "06 March 2020" "1.0" "encpass.sh man page"
  .SH NAME
  encpass.sh \- Use encrypted passwords in shell scripts
  ...
  EOF

See encpass.sh for a working example of this -> https://github.com/plyint/encpass.sh/blob/master/encpass.sh

[sicromoft]

Note that this doesn't work on macOS, where the builtin `man` command doesn't support the `-l` option.

[ahnick]

Ah interesting, is there any workaround for Mac? Otherwise, I may just have to fallback to stripping the man page formatting and sending it to less.

[gpanders]

The actual `man` command does this:

    /usr/bin/tbl | /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c | /usr/bin/less -is

So you could do it "manually" that way. Not the cleanest or prettiest solution but it's much lighter weight than using something like pandoc.

EDIT: Full example:

    { /usr/bin/tbl | /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c | /usr/bin/less -is; } <<EOF
    .\" Manpage for encpass.sh.
    .\" Email [e-mail] to correct errors or typos.
    .TH man 8 "06 March 2020" "1.0" "encpass.sh man page"
    .SH NAME
    encpass.sh \- Use encrypted passwords in shell scripts
    ...
    EOF

[ahnick]

Thanks, this worked well on Mac.

[tobylane]

If I understand your need correctly: pandoc.

[ahnick]

pandoc is not installed on macOS out-of-the-box though right? The user would have to pull via homebrew or something?

[enriquto]

> is there any workaround for Mac?

Yeah, any regular unix will do, for example openbsd, freebsd or any linux distribution.

[lolsal]

> so that the help documentation doesn't overwhelm the initial viewing of the actual code.

That is a very strange argument to me. You find that more cumbersome than jumping around to random functions?

[ahnick]

No, I think the readability of the help documentation itself is largely the same whether it is placed in the header or in a dedicated function. When I'm viewing the shell script code though, often I want to jump right in and see the actual code, not look at the help documentation.

By having the help documentation in a function in the middle or towards the end of the file, I don't have to page down through the help documentation to get to the code that is actually doing things. If I'm really interested in the help documentation, then I'd prefer to look at the nicely formatted version output by the script (<script> --help or whatever) rather than looking in the actual script code anyway.

Admittedly, this may be more of a subjective personal preference item.