Style question: writing multi-line usage messages

[Gary Jennejohn]

On Tue, 4 May 2010 19:17:49 +1000
Peter Jeremy <peterjeremy at acm.org> wrote:

> I would appreciate some input on the preferred style for writing
> multi-line usage messages.  Should:
> 1) printf() print a series of 1-line strings
> 2) should string gluing be used to turn multiple strings into one for printing
> 3) should continuation lines be used to create a single string
> 
> I can't see anything in style(9) to cover this.
> 
> Variants of the tunefs(8) usage() function follow as examples:
> 
> void
> usage(void)
> {
> 
> 	fprintf(stderr, "%s\n%s\n%s\n%s\n%s\n%s\n",
> "usage: tunefs [-A] [-a enable | disable] [-e maxbpg] [-f avgfilesize]",
> "              [-J enable | disable] [-j enable | disable]", 
> "              [-L volname] [-l enable | disable] [-m minfree]",
> "              [-N enable | disable] [-n enable | disable]",
> "              [-o space | time] [-p] [-S size] [-s avgfpdir]",
> "              special | filesystem");
> 	exit(2);
> }
> 

This version requires you to remmeber to add %s\n to the format if you
add a new line, something which I personally forget to do all the time.

> void
> usage(void)
> {
> 
> 	fprintf(stderr,
> "usage: tunefs [-A] [-a enable | disable] [-e maxbpg] [-f avgfilesize]\n"
> "              [-J enable | disable] [-j enable | disable]\n"
> "              [-L volname] [-l enable | disable] [-m minfree]\n"
> "              [-N enable | disable] [-n enable | disable]\n"
> "              [-o space | time] [-p] [-S size] [-s avgfpdir]\n"
> "              special | filesystem\n");
> 	exit(2);
> }
> 
> void
> usage(void)
> {
> 
> 	fprintf(stderr,
> "usage: tunefs [-A] [-a enable | disable] [-e maxbpg] [-f avgfilesize]\n\
>               [-J enable | disable] [-j enable | disable]\n\
>               [-L volname] [-l enable | disable] [-m minfree]\n\
>               [-N enable | disable] [-n enable | disable]\n\
>               [-o space | time] [-p] [-S size] [-s avgfpdir]\n\
>               special | filesystem\n");
> 	exit(2);
> }
> 

I personally don't see all that much difference between these.  The first variant
has the advantage that it's very clear that you're looking at strings, which might
be a good thing.

I vote for 2.

Couldn't you replace all the leading spaces with \t's?

--
Gary Jennejohn