On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@xxxxxxxx> wrote: > On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote: > >> >> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/ >> > >> > Thank you very much Felipe to take the time to upload the patches there. >> > I already have a copy there and I'll look at it soon. >> >> Has anybody looked at this? It's a bit large-ish and touches all over the >> place, so I am finding it a bit hard to concentrate on it myself really >> nitpicking, but from the cursory look after formatting the result looked >> Ok. > > I started to, but the first commit message is lacking something that I > think would make reviewing much simpler: what are the general classes of > changes that are being made? > > I see some doublequotes becoming backticks, and some becoming single > quotes. And some becoming tex-quotes (``...''), and even some becoming > doublequotes _with_ single quotes. It would be easier to verify that > they are doing the right thing if the commit message briefly described > the rules it followed for changing each one. I think they are something > like: > > - tex-quotes if it was really a prose-style quotation > > - backticks (causing monospace) for branch names, commands, etc in > prose > > but that leaves me confused. Some things which I thought should be in > monospace backticks are in single-quotes (causing emphasis). Like > 'master' or 'linux-2.6'. And some things are emphasized and in double > quotes in the prose, like '"o"' or '"branch A"'. What is the rule to > decide which text should have visible doublequotes but also be > emphasized, as opposed to just having double-quotes or just being > emphasized? > > Maybe this was even discussed earlier in the thread (I didn't go back to > look), but it should definitely be part of the commit message. The rule I followed is: change it to whatever looks best. I followed some guidelines such as: make common text monospace, such as gitk and master. And emphasize whatever needs emphasizing, such as fb47ddb2db. Examples are both monospace *and* emphasized. Sometimes the end result still didn't look good so I just used whatever looked best. Have you actually looked at the end result? -- Felipe Contreras -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html