Re: [RFC] Embedding asciidoc manpages in the cg scripts

From: David Greaves <david@dgreaves.com>
Date: May 11, 2005, 22:20 UTC
Message-ID: <4282851A.2010305@dgreaves.com>
In-Reply-To: <20050511213217.GG22686@pasky.ji.cz>

Petr Baudis wrote:

Show 13 quoted lines

>> #
>>+# NAME
>>+# ----
>>+# cg-add - add files to a GIT repository
>>    
>>
>
>Half of this is useless, too.
>
>I think you should just keep the first paragraph of the files as it is
>now. Don't touch it, just parse it.
>  
>

A bit harsh Petr.

Isn't the idea of using an already written tool that you don't _have_ to parse it? Where, consistently, do the cg-files have a 1 line summary.

Show 8 quoted lines

>>+#
>>+# SYNOPSIS
>>+# --------
>>    
>>
>No need for this heading either.
>  
>

Actually there is :) asciidoc won't produce a manpage without it.

Show 16 quoted lines

>>+USAGE="cg-add FILE..."
>>+#
>>+# DESCRIPTION
>>+# -----------
>> # Takes a list of file names at the command line, and schedules them
>> # for addition to the GIT repository at the next commit.
>>+#
>>+# The command will fail if one of the given files does not exist.
>>+#
>>+# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.
>>    
>>
>
>Useless.
>  
>

Yes - if you happen to have written and breathed the code - not so useless if you're a normal user.

It cogito is ever installed as part of a distro (maybe even by default) then it would be nice if "man cg-add" actually mentioned it was part of cogito and git...

Show 15 quoted lines

>>+#
>>+# OPTIONS
>>+# -------
>>+# No options.
>>    
>>
>
>The rest of DESCRIPTION and OPTIONS looks fine.
>
>I'd just expect you to be much less intrusive in the in-file comments
>and do more work when processing the stuff. I'm commenting on how it
>looks inside of the sources - do whatever is necessary when processing
>it to generate a proper-looking manpage from it.
>  
>

Having worked hard on being consistent throughout the git docs I'd say that a little excess verbiage in the comments is a worthwhile price. I don't think you can worry about performance or anything - these _are_ shell scripts!

Maybe you'd be happier if they were moved to the bottom of the file and preceded with:

#asciidoc follows

Or if you don't like that then maybe keep them external.

David