On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht <nicolas.s.dev@xxxxxx> wrote: > The 21/05/09, Felipe Contreras wrote: >> 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. > > Agreed. > >> 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. > > IHMO, "what looks best" is not the best way to enhance the user manual > because it may be somewhat confusing. > > Without being as strict as in the manpages we should have good rules to > display the commands, branch names, etc to the end-users all over the > manual (think SYNOPSIS). For example, all branch names in the text could > be "italic, green, without quotes". Now, in the paragraph "Fetching > individual branches" we have > > will create a new branch named '"example-master"' and store in it the > branch named '"master"' from the repository at the given URL. If you > already have a branch named 'example-master', it will attempt to > > where the branch name /example-master/ has two different occurences _with_ > and _without_ quotes. Yes, I wanted delimit "example-master", just like quotation marks are normally used, but after it has been denoted there's no more point in doing that over an over. For example: He referred to his friend as "John". But unlike him, "John" was very quiet. The quotes make sense on the first sentence, but not on the second. > This is for the end user part. For the contributers, the commit could say: > > " - branch names: uses the form 'branch-name' to appear in green, > italic. > - file names: uses [...] to appear in [...] > - refspec: uses [...] to appear in [...] > - etc. > " No, asciidoc only has support for: emphazised, strong, monospace, single-quoted and double-quoted. No colors or anything fancy. Not all branch names are equal; "master" is not the same as "mybranch". "master" has a special meaning, therefore it should be in monospace, but "mybranch" is simply a branch name, therefore it should be emphazied. If the branch name is complicated you might want to delimit it with double quotes: "my-fooish-bar-branch", at least the first time you mention it. File names is a similar story; ".gitignore" is not the same as "test.c". >> Have you actually looked at the end result? > > Yes, I think it's much better with your patch but "display-types" should > follow the same rules all over the text. I disagree. There are no absolutes when writing human-readable documents. > I'm missing of time theses days. I think I'll could help you in one or > two weeks I you want. It's an ant work. :-) > AFAICT, some people here want to rewrite the manual, right? Maybe it > could be done with this rewriting? I have a bunch of patches and this was supposed to be the uncontroversial one =/ -- 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