On Thu, May 21, 2009 at 4:25 PM, Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> wrote: > Felipe Contreras venit, vidit, dixit 21.05.2009 09:17: >> 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. > > I think that's a bit of a "quick and dirty" approach. Man pages and user > manual should use semantic markup. The matter of "looks" is up to the > documentation tool chain, i.e. the style sheets etc. for the various > backends. > > So we would need: > > - a documentation "style guide" which tells you how to do the semantic > markup, such as `cmd` for commands, 'foo' for emphasis etc. > > - maybe some changes to the style sheets etc. which make the semantic > markup "look good" > > The standard transformations which come with asciidoc/docbook can serve > as a guide. There's already a guide: the asciidoc user-guide... you can only go as far as asciidoc lets you. `` for monospace, '' for emphasis, ``'' for double quotes. I have a problem with clear-cut rules such as: `cmd` for commands. Do you think all these are the same? The `git clone` command allows you to... You can do that by doing '"git commit -a -m Example"' Please refer to linkgit:git-add[1] If you are reading the text you'll see that the 3 usages have different intents. >> Have you actually looked at the end result? >> > > No. My attempts at doing systematic changes (rather than modifying > single pages without a clear target) have failed, so I've been keeping > out of this business... It's one click away: http://people.freedesktop.org/~felipec/git/user-manual/user-manual.html -- 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