3 ms·
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
by ahnick 6y ago
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 https://github.com/plyint/encpass.sh/blob/master/encpass.sh
- lolsal 6y ago> 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 6y agoNo, 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.
- sicromoft 6y agoNote that this doesn't work on macOS, where the builtin `man` command doesn't support the `-l` option.
- ahnick 6y agoAh 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.
- enriquto 6y ago> is there any workaround for Mac? Yeah, any regular unix will do, for example openbsd, freebsd or any linux distribution.
- tobylane 6y agoIf I understand your need correctly: pandoc.
- ahnick 6y agopandoc is not installed on macOS out-of-the-box though right? The user would have to pull via homebrew or something?
- gpanders 6y agoThe 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
- ahnick 6y agoThanks, this worked well on Mac.