From: David Greaves <david@dgreaves.com>
Date: Wed, 11 May 2005 22:20:10 GMT
Subject: Re: [RFC] Embedding asciidoc manpages in the cg scripts
Message-ID: <4282851A.2010305@dgreaves.com>
In-Reply-To: <20050511213217.GG22686@pasky.ji.cz>

Petr Baudis wrote:

>> #
>>+# 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.

>>+#
>>+# SYNOPSIS
>>+# --------
>>    
>>
>No need for this heading either.
>  
>
Actually there is :)
asciidoc won't produce a manpage without it.

>>+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...

>>+#
>>+# 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

--