Re: [StGit PATCH 1/3] Auto-generate man pages for all StGit commands

From: Karl Hasselström <kha@treskal.com>
Date: Sep 11, 2008, 06:58 UTC
Message-ID: <20080911065832.GA6409@diana.vm.bytemark.co.uk>
In-Reply-To: <b0943d9e0809101456w3c74b86fm9d311fb2594bcf4f@mail.gmail.com>

On 2008-09-10 22:56:55 +0100, Catalin Marinas wrote:

Show 7 quoted lines

> On 08/09/2008, Karl Hasselström <kha@treskal.com> wrote:
>
> > Auto-generate man pages based on the docs that are in each
> > stgit/commands/<cmd>.py file. That doc format is extended in order
> > to support both brief command help output and manpage text.
>
> Really great stuff. Thanks.

Glad you like it. Now all we have to do is feed the system with high-quality input ... :-)

> I can see a slight difference in behaviour but I don't have any
> issue with it - previously "stg help <cmd>" showed the full
> description while "stg <cmd> --help" only the short one.

Yes, that's intentional. I tried to say something about it in the commit message, but I guess I didn't do a very good job about it.

The interactive help now uses only the one-line command description; the multiline description goes only to the man page/html. There are two reasons for this:

  1. The interactive help should be short and sweet. If the user wants
     to spend a minute or more learning about a command, she is better
     served by the "real" reference docs.

  2. The multiline descriptions (both for the command itself and for
     its flags) contain, or should contain, asciidoc markup. If we
     wanted to display this text in the interactive help we'd need to
     at least be able to strip the markup out, something which I
     haven't even tried to do.

Show 5 quoted lines

> An additional point on naming - should we use StGIT or StGit? The
> original name was StGIT since GIT looked like an acronym. It looks
> like now more people name it Git hence our tool moved slowly into
> StGit but not everywhere. I personally like StGIT but the last 3
> letters should really be the same as the official git (Git, GIT).

As you may or may not have noticed, I'm responsible for the vast majority of "StGit"s. I prefer it because "git" isn't really an acronym, and I happen to like camel case ... :-)

You're right that we ought to standardize on one of the spellings, though.

-- 
Karl Hasselström, kha@treskal.com
      www.treskal.com/kalle