Date: Tue, 4 May 2010 12:26:29 +0200 From: Gary Jennejohn <gljennjohn@googlemail.com> To: Peter Jeremy <peterjeremy@acm.org> Cc: freebsd-arch@freebsd.org Subject: Re: Style question: writing multi-line usage messages Message-ID: <20100504122629.0aa4c2dc@ernst.jennejohn.org> In-Reply-To: <20100504091749.GA58464@server.vk2pj.dyndns.org> References: <20100504091749.GA58464@server.vk2pj.dyndns.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, 4 May 2010 19:17:49 +1000
Peter Jeremy <peterjeremy@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20100504122629.0aa4c2dc>