Hacker News Reader

Comment by ahnick | Hacker News Reader

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 contact@plyint.com 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

View on HN

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

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.

> is there any workaround for Mac?

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

If I understand your need correctly: pandoc.

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

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 contact@plyint.com 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

Thanks, this worked well on Mac.

> 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?

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.

Reply on news.ycombinator.com