1. 29

  2. 3

    As useful as this is, I still think that this is a case of –help vs man; some argue –help for summaries, and some argue man for all the information. I’d argue this should be in an INSTALL file for detailed docs, but some might also find this useful.

    1. 1


      1. 1

        Self-documenting make to get similar functionality to rake --tasks, fab --list, etc. is pretty useful, but I don’t think it should be the default behavior. The general structure of Makefiles is mostly pretty great, but lack of introspection can be a problem. I’ve always wanted to be able to run make --targets to get a list of targets, having their descriptions would be great too. Being able to feed something like make --targets --no-phony instead of ls or find into entr would be amazing, would save me the trouble of listing my targets twice.

        1. 1

          I do the same with my zsh function/script files. I put the help in a comment, then use sed to only print the relevant parts of $0 when I pass -h | -help | --help. The help message for the script would be

          # help message
          # ....

          And the command to extract and print the help message section is a simple sed script.

          sed -n -e '/^#\{2,\}/,/^#\{2,\}/ {s/^#\+ //; p; }' "$0"

          Works reasonably well and isn’t hard to maintain. You can even put in named help sections, assuming you adjust the patterns in the sed script. (One per file is sufficient for my needs.)