git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH] CodingGuidelines: Add a section on writing documentation

From
Štěpán Němec <stepnem@gmail.com>
Date
Nov 1, 2010, 17:00 UTC
Message-ID
<87fwvl2d4d.fsf@gmail.com>
In-Reply-To
<AANLkTinyPkGmsgbGM9qpXMNcZRzOXvtjDDEkJ-i3nWXz@mail.gmail.com>
Sverre Rabbelier <srabbelier@gmail.com> writes:
Show 10 quoted lines
> Heya,
>
> On Fri, Oct 29, 2010 at 04:54, Štěpán Němec <stepnem@gmail.com> wrote:
>> But given that it's only used as {0,2} at the two places right now
>> (disregarding occurences of "0{40}" in the documentation), I agree it
>> might be better to get rid of it, although I don't feel strongly about
>> it. Any other opinions?
>
> Let's get rid of it for now, we can always resurrect it later if we
> have a need for it.
OK.
Show 13 quoted lines
>> I thought about this already when preparing the recent unification
>> series, and came to the conclusion "no, there shouldn't". :-) As the
>> examples you give show, the current usage is inconsistent, but given
>> that it brings no semantic ambiguity, I don't think it is a problem. You
>> could find more similar cosmetic inconsistencies and I don't think it
>> makes much sense to mandate any rules for such things. (But again, I
>> don't feel _too_ strongly about this either, so if more people think
>> it's worth it, I can prepare a patch that unifies them and mention the
>> preference in CodingGuidelines.)
>
> Perhaps we can set a standard to do it, but just leave the existing
> cases as is (to prevent unneeded churn)? That way we'll eventually
> converge on something.

Hm... that seems like the worst solution to me -- if we do end up standardizing this after all, any occurence of non-standard usage would be a bug that needs fixing (think about it from the POV of a new contributor who reads CodingGuidelines but sees the actual usage being different).

I guess it wouldn't be so much of a code churn to unify the spacing, but I'm still not convinced we should be enforcing this kind of thing.

Štěpán
Previous: Sverre RabbelierNext: Štěpán Němec
Message 13 of 43 in “Unify argument and option notation in the docs”
  1. Unify argument and option notation in the docsŠtěpán Němec, Oct 8, 2010
  2. Jonathan NiederOct 8, 2010
  3. Štěpán NěmecOct 8, 2010
  4. 0/6 Unify argument and option notation in the docsŠtěpán Němec, Oct 8, 2010
  5. Jonathan NiederOct 8, 2010
  6. Junio C HamanoOct 8, 2010
  7. Štěpán NěmecOct 8, 2010
  8. Jonathan NiederOct 21, 2010
  9. CodingGuidelines: Add a section on writing documentationŠtěpán Němec, Oct 24, 2010
  10. Mark LodatoOct 29, 2010
  11. Štěpán NěmecOct 29, 2010
  12. Sverre RabbelierOct 29, 2010
  13. Štěpán NěmecNov 1, 2010
  14. CodingGuidelines: Add a section on writing documentationŠtěpán Němec, Nov 4, 2010
  15. diff,difftool: Don't use the {0,2} notation in usage stringsŠtěpán Němec, Nov 4, 2010
  16. Sverre RabbelierNov 4, 2010
  17. Jeff KingNov 4, 2010
  18. Jonathan NiederNov 4, 2010
  19. Jeff KingNov 4, 2010
  20. Jonathan NiederNov 4, 2010
  21. Jeff KingNov 4, 2010
  22. Štěpán NěmecNov 4, 2010
  23. Jeff KingNov 4, 2010
  24. docs: clarify git diff modes of operationJeff King, Nov 4, 2010
  25. Jonathan NiederNov 4, 2010
  26. Mark LodatoNov 5, 2010
  27. Štěpán NěmecNov 4, 2010
  28. Štěpán NěmecNov 4, 2010
  29. 1/6 Use angles for placeholders consistentlyŠtěpán Němec, Oct 8, 2010
  30. 2/6 Fix odd markup in --diff-filter documentationŠtěpán Němec, Oct 8, 2010
  31. Jonathan NiederOct 8, 2010
  32. Štěpán NěmecOct 8, 2010
  33. Jonathan NiederOct 8, 2010
  34. Štěpán NěmecOct 8, 2010
  35. Jonathan NiederOct 8, 2010
  36. 3/6 Use parentheses and `...' where appropriateŠtěpán Němec, Oct 8, 2010
  37. 4/6 Remove stray quotes in --pretty and --format documentationŠtěpán Němec, Oct 8, 2010
  38. 5/6 Put a space between `<' and argument in pack-objects usage stringŠtěpán Němec, Oct 8, 2010
  39. 6/6 Fix {update,checkout}-index usage stringsŠtěpán Němec, Oct 8, 2010
  40. 0/2 pack-objects: use ALLOC_GROW in place of manual growthJonathan Nieder, Oct 8, 2010
  41. 1/2 Documentation: No argument of ALLOC_GROW should have side-effectsJonathan Nieder, Oct 8, 2010
  42. 2/2 pack-objects: use ALLOC_GROWJonathan Nieder, Oct 8, 2010
  43. 3/2 Allow side-effects in second argument to ALLOC_GROWJonathan Nieder, Oct 8, 2010

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.