Re: [PATCH 0/6] Unify argument and option notation in the docs

From: Štěpán Němec <stepnem@gmail.com>
Date: Oct 8, 2010, 20:15 UTC
Message-ID: <8739sgtp8i.fsf@gmail.com>
In-Reply-To: <7v1v80wjuw.fsf@alter.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> writes:

> I had to fix up the whitespace damage in the rerolled 2/6 but otherwise
> looked good.

Yeah, sorry for that. Obviously the tabs got replaced by spaces when I copy-pasted the hunk and I didn't notice.

Show 12 quoted lines

> Thanks, both.  It might make sense to outline the rules applied somewhere in
> CodingGuidelines to help people who add to our documents.  Something along
> the lines of...
>
>  - A placeholder is spelled inside angle brackets, e.g. <file>, <object>.
>
>  - Choosing one from many is written with possible choices separated with
>    a vertical bar and the whole thing enclosed in parentheses, e.g.
>    answer=(yes|no|true|false)
>
>  - Repetition of zero or more times of X is spelled as [(X)...], e.g.
>    [(-p <parent>)...]

:-) I was actually considering just that, so I'm glad you mention it.

I can try to compile an initial version of such a document, based on the commit message of the original single-patch version (<http://article.gmane.org/gmane.comp.version-control.git/158467>) and including some more cases/examples.

Where do you think would be the most appropriate place for it? Just add a section to CodingGuidelines, or a separate Documentation/WritingGuidelines or something?

Štěpán