help target

[kba]

Two proposals:

1. Make help the default target
2. simplify help to a series of echo commands

1. is a convention I really like because when it is not completely obvious what the default should be (and I argue it is not for this repo) then it's better not to do anything for the default and just print usage info.

2. Evaluating a variable that cats a heredoc string seems convoluted. Also why export HELP?

[bertsky]

I agree with 1, but I disagree with 2.

The reason to write a canned recipe for the help text is readibility (and extensibility). The heredoc and eval are necessary, because this one of the few ways which make echoing verbatim newlines possible. I fail to see any disadvantage in doing so.

In detail:

• the export is necessary, because HELP at that point is nothing more than a make variable (which incidentally contains a shell command).
• define is the only syntax in make that preserves newlines. But you could not just pass such a variable to echo in a recipe (even when it is quoted), because make does not know anything about quotes, it just passes them on verbatim (which would just result in the shell complaining Unterminated quoted string after the first newline). In fact, the only thing make does not pass on verbatim are newline escapes, but we don't want that here (or having to prefix every line with tab and @echo), because it's ugly and cumbersome for large texts.
• eval gets the heredoc executed

[kba]

make is now the same as make help, so I'm closing this.

But you could not just pass such a variable to echo in a recipe

I tend to generate the help file by parsing target and variable declarations with their comments and then outputting

help:
  echo "Targets"
  echo ""
  echo "  some-target   Comment describing some-target.

etc.

Not important enough to argue about.

[bertsky]

I tend to generate the help file by parsing target and variable declarations with their comments and then outputting

i know. I do it like that myself. For short texts. But as I said: readability and extensibility.

You forgot a closing quote BTW ;-)

[kba]

You forgot a closing quote BTW ;-)

Classic...