Re: [PATCH] - Added command synopsis in code and edited them in manual

[Junio C Hamano <gitster@pobox.com>]

imyousuf@gmail.com writes:

> From: Imran M Yousuf <imyousuf@smartitengineering.com>
>
> Added the command synopsis so that they are available for
> any future command additions.

I think you are talking about the comments you added at the beginning of
the script; I do not particularly see it as improvement.  Rather, it
is just an additional maintenance burden that risks going out of sync with
the documentation.

It may make more sense to make your added lines into one line per
subcommand descriptions in LONG_USAGE, and shorten USAGE to just mention
"git submodule <command> <options>".  The command is multi-featured enough
that it can afford to have a long on-line usage text, and I am reasonably
sure you would agree with me if you read your later patches that cram tons
of options on a single line USAGE.  It simply is unreadable, no matter how
wide your terminal is.

By the way, please use imperative, e.g. "Add gostak so that doshes are
properly distimmed", instead of past tense "Added synopsis".

> In the init/update command synopsis either of them is required
> command as is add in its synopsis, so removed the square brackets
> around them from the documentation

But without grouping, the reader cannot tell where the alternation begins
and ends.  Typically we use () in our documentation set.

That reminds me of the topic of marking "either this or that, you must
have one" with { this | that }, and that is more in line with other
systems' documentation, and is also consistent with what POSIX recommends.
I think the list atmosphere back then was "Yeah, {} may be more kosher,
but we have been consistently using () and that is not misleading, so
unless we convert everything consistently, using {} at only a few places
makes it even worse."  I personally do not mind patches to convert
everybody to {} if we are confident that we can finish it before -rc1.