{"thread":{"id":"19212","subject":"[PATCH v3 2/2] user-manual: use 'fast-forward' instead of 'fast forward'","startedAt":"2009-05-06T22:53:34Z","lastAt":"2009-05-25T12:41:47Z","messageCount":17,"participants":["Felipe Contreras","Nicolas Sebrecht","Junio C Hamano","Jeff King","Michael J Gruber","Wincent Colaiuta"],"isPatch":true,"patchVersion":3,"patchTotal":2},"messages":[{"id":"113140","messageId":"1241650416-12224-1-git-send-email-felipe.contreras@gmail.com","threadId":"19212","inReplyTo":null,"subject":"[PATCH v3 0/2] user-manual: general improvements","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-05-06T22:53:34Z","receivedAt":"2009-05-06T22:53:34Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"I split the previous patch series, now only trivial changes are included.\n\nFelipe Contreras (2):\n user-manual: general quoting improvements\n user-manual: use 'fast-forward' instead of 'fast forward'\n\n Documentation/user-manual.txt | 890 ++++++++++++++++++++--------------------\n 1 files changed, 445 insertions(+), 445 deletions(-)\n"},{"id":"113139","messageId":"1241650416-12224-3-git-send-email-felipe.contreras@gmail.com","threadId":"19212","inReplyTo":"1241650416-12224-2-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v3 2/2] user-manual: use 'fast-forward' instead of 'fast forward'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-05-06T22:53:36Z","receivedAt":"2009-05-06T22:53:36Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Signed-off-by: Felipe Contreras \n---\n Documentation/user-manual.txt | 14 +++++++-------\n 1 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex a8558a1..9978027 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1384,7 +1384,7 @@ were merged.\n \n However, if the current branch is a descendant of the other--so every\n commit present in the one is already contained in the other--then git\n-just performs a '``fast forward'''; the head of the current branch is moved\n+just performs a 'fast-forward'; the head of the current branch is moved\n forward to point at the head of the merged-in branch, without any new\n commits being created.\n \n@@ -1719,7 +1719,7 @@ producing a default commit message documenting the branch and\n repository that you pulled from.\n \n (But note that no such commit will be created in the case of a\n-<>; instead, your branch will just be\n+<>; instead, your branch will just be\n updated to point to the latest commit from the upstream branch.)\n \n The `git pull` command can also be given '\".\"' as the 'remote' repository,\n@@ -1943,7 +1943,7 @@ $ git push ssh://yourserver.com/~you/proj.git master\n -------------------------------------------------\n \n As with `git fetch`, `git push` will complain if this does not result in a\n-<>; see the following section for details on\n+<>; see the following section for details on\n handling this case.\n \n Note that the target of a 'push' is normally a\n@@ -1976,7 +1976,7 @@ details.\n What to do when a push fails\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-If a push would not result in a <> of the\n+If a push would not result in a <> of the\n remote branch, then it will fail with an error like:\n \n -------------------------------------------------\n@@ -2115,7 +2115,7 @@ $ git checkout release && git pull\n \n *Important note!* If you have any local changes in these branches, then\n this merge will create a commit object in the history (with no local\n-changes git will simply do a 'fast forward' merge). Many people dislike\n+changes git will simply do a 'fast-forward' merge). Many people dislike\n the ``noise'' that this creates in the Linux history, so you should avoid\n doing this capriciously in the 'release' branch, as these noisy commits\n will become part of the permanent history when you ask Linus to pull\n@@ -2729,9 +2729,9 @@ In the previous example, when updating an existing branch, \"git fetch\"\n checks to make sure that the most recent commit on the remote\n branch is a descendant of the most recent commit on your copy of the\n branch before updating your copy of the branch to point at the new\n-commit. Git calls this process a <>.\n+commit. Git calls this process a <>.\n \n-A 'fast forward' looks something like this:\n+A 'fast-forward' looks something like this:\n \n ................................................\n o--o--o--o <-- old head of the branch\n-- \n1.6.3.rc4.14.g96da.dirty\n"},{"id":"113176","messageId":"20090507072326.GA13123@vidovic","threadId":"19212","inReplyTo":"1241650416-12224-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Nicolas Sebrecht","fromEmail":"nicolas.s.dev@gmx.fr","sentAt":"2009-05-07T07:23:26Z","receivedAt":"2009-05-07T07:23:26Z","isPatch":true,"sender":{"key":"nicolas.s.dev@gmx.fr","avatar":null},"body":"The 07/05/09, Felipe Contreras wrote:\n\n> Felipe Contreras (2):\n\nHi,\n\n> user-manual: general quoting improvements\n\nI didn't receive the v3 of this patch and it neither appears in gmane.\nhttp://article.gmane.org/gmane.comp.version-control.git/118399\n\nCould you please resend it ?\n\n-- \nNicolas Sebrecht\n"},{"id":"113287","messageId":"7veiv0cvdt.fsf@alter.siamese.dyndns.org","threadId":"19212","inReplyTo":"20090507072326.GA13123@vidovic","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-05-08T00:04:46Z","receivedAt":"2009-05-08T00:04:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Sebrecht writes:\n\n> The 07/05/09, Felipe Contreras wrote:\n>\n>> Felipe Contreras (2):\n>\n> Hi,\n>\n>> user-manual: general quoting improvements\n>\n> I didn't receive the v3 of this patch and it neither appears in gmane.\n> http://article.gmane.org/gmane.comp.version-control.git/118399\n>\n> Could you please resend it ?\n\nFelipe has been resending it for a few rounds, but it appears it never\ngoes through vger (nor directly to me). It's a bit frustrating (no, not a\nfault of Felipe's).\n"},{"id":"114381","messageId":"7vvdnvtf2n.fsf@alter.siamese.dyndns.org","threadId":"19212","inReplyTo":"20090514160609.GA12910@vidovic","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-05-21T01:33:36Z","receivedAt":"2009-05-21T01:33:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Sebrecht writes:\n\n> The 14/05/09, Felipe Contreras wrote:\n> ...\n>> I've uploaded the patches here:\n>> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n>\n> Thank you very much Felipe to take the time to upload the patches there.\n> I already have a copy there and I'll look at it soon.\n\nHas anybody looked at this? It's a bit large-ish and touches all over the\nplace, so I am finding it a bit hard to concentrate on it myself really\nnitpicking, but from the cursory look after formatting the result looked\nOk.\n"},{"id":"114389","messageId":"20090521041529.GD8091@sigill.intra.peff.net","threadId":"19212","inReplyTo":"7vvdnvtf2n.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-05-21T04:15:29Z","receivedAt":"2009-05-21T04:15:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n\n> >> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n> >\n> > Thank you very much Felipe to take the time to upload the patches there.\n> > I already have a copy there and I'll look at it soon.\n> \n> Has anybody looked at this? It's a bit large-ish and touches all over the\n> place, so I am finding it a bit hard to concentrate on it myself really\n> nitpicking, but from the cursory look after formatting the result looked\n> Ok.\n\nI started to, but the first commit message is lacking something that I\nthink would make reviewing much simpler: what are the general classes of\nchanges that are being made?\n\nI see some doublequotes becoming backticks, and some becoming single\nquotes. And some becoming tex-quotes (``...''), and even some becoming\ndoublequotes _with_ single quotes. It would be easier to verify that\nthey are doing the right thing if the commit message briefly described\nthe rules it followed for changing each one. I think they are something\nlike:\n\n - tex-quotes if it was really a prose-style quotation\n\n - backticks (causing monospace) for branch names, commands, etc in\n prose\n\nbut that leaves me confused. Some things which I thought should be in\nmonospace backticks are in single-quotes (causing emphasis). Like\n'master' or 'linux-2.6'. And some things are emphasized and in double\nquotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\ndecide which text should have visible doublequotes but also be\nemphasized, as opposed to just having double-quotes or just being\nemphasized?\n\nMaybe this was even discussed earlier in the thread (I didn't go back to\nlook), but it should definitely be part of the commit message.\n\n-Peff\n"},{"id":"114392","messageId":"7viqjvdofq.fsf@alter.siamese.dyndns.org","threadId":"19212","inReplyTo":"20090521041529.GD8091@sigill.intra.peff.net","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-05-21T05:18:01Z","receivedAt":"2009-05-21T05:18:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n>\n>> >> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n>> >\n>> > Thank you very much Felipe to take the time to upload the patches there.\n>> > I already have a copy there and I'll look at it soon.\n>> \n>> Has anybody looked at this? It's a bit large-ish and touches all over the\n>> place, so I am finding it a bit hard to concentrate on it myself really\n>> nitpicking, but from the cursory look after formatting the result looked\n>> Ok.\n>\n> I started to, but the first commit message is lacking something that I\n> think would make reviewing much simpler: what are the general classes of\n> changes that are being made?\n>\n> I see some doublequotes becoming backticks, and some becoming single\n> quotes. And some becoming tex-quotes (``...''), and even some becoming\n> doublequotes _with_ single quotes. It would be easier to verify that\n> they are doing the right thing if the commit message briefly described\n> the rules it followed for changing each one. I think they are something\n> like:\n>\n> - tex-quotes if it was really a prose-style quotation\n>\n> - backticks (causing monospace) for branch names, commands, etc in\n> prose\n>\n> but that leaves me confused. Some things which I thought should be in\n> monospace backticks are in single-quotes (causing emphasis). Like\n> 'master' or 'linux-2.6'. And some things are emphasized and in double\n> quotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\n> decide which text should have visible doublequotes but also be\n> emphasized, as opposed to just having double-quotes or just being\n> emphasized?\n>\n> Maybe this was even discussed earlier in the thread (I didn't go back to\n> look), but it should definitely be part of the commit message.\n\nI do not think there was any discussion, as the original patch never made\nto the list. And I realize that the difficulty I had while reading this\nwas exactly what you described here. Thanks for saying it very clearly.\n"},{"id":"114394","messageId":"94a0d4530905210017x1ce3e32bk3b1fbf9044377763@mail.gmail.com","threadId":"19212","inReplyTo":"20090521041529.GD8091@sigill.intra.peff.net","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-05-21T07:17:45Z","receivedAt":"2009-05-21T07:17:45Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Thu, May 21, 2009 at 7:15 AM, Jeff King wrote:\n> On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n>\n>> >> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n>> >\n>> > Thank you very much Felipe to take the time to upload the patches there.\n>> > I already have a copy there and I'll look at it soon.\n>>\n>> Has anybody looked at this?  It's a bit large-ish and touches all over the\n>> place, so I am finding it a bit hard to concentrate on it myself really\n>> nitpicking, but from the cursory look after formatting the result looked\n>> Ok.\n>\n> I started to, but the first commit message is lacking something that I\n> think would make reviewing much simpler: what are the general classes of\n> changes that are being made?\n>\n> I see some doublequotes becoming backticks, and some becoming single\n> quotes. And some becoming tex-quotes (``...''), and even some becoming\n> doublequotes _with_ single quotes. It would be easier to verify that\n> they are doing the right thing if the commit message briefly described\n> the rules it followed for changing each one. I think they are something\n> like:\n>\n>  - tex-quotes if it was really a prose-style quotation\n>\n>  - backticks (causing monospace) for branch names, commands, etc in\n>    prose\n>\n> but that leaves me confused. Some things which I thought should be in\n> monospace backticks are in single-quotes (causing emphasis). Like\n> 'master' or 'linux-2.6'. And some things are emphasized and in double\n> quotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\n> decide which text should have visible doublequotes but also be\n> emphasized, as opposed to just having double-quotes or just being\n> emphasized?\n>\n> Maybe this was even discussed earlier in the thread (I didn't go back to\n> look), but it should definitely be part of the commit message.\n\nThe rule I followed is: change it to whatever looks best.\n\nI followed some guidelines such as: make common text monospace, such\nas gitk and master. And emphasize whatever needs emphasizing, such as\nfb47ddb2db. Examples are both monospace *and* emphasized.\n\nSometimes the end result still didn't look good so I just used\nwhatever looked best.\n\nHave you actually looked at the end result?\n\n-- \nFelipe Contreras\n"},{"id":"114411","messageId":"20090521131802.GA13840@vidovic","threadId":"19212","inReplyTo":"94a0d4530905210017x1ce3e32bk3b1fbf9044377763@mail.gmail.com","subject":"[PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Nicolas Sebrecht","fromEmail":"nicolas.s.dev@gmx.fr","sentAt":"2009-05-21T13:18:02Z","receivedAt":"2009-05-21T13:18:02Z","isPatch":true,"sender":{"key":"nicolas.s.dev@gmx.fr","avatar":null},"body":"The 21/05/09, Felipe Contreras wrote:\n> On Thu, May 21, 2009 at 7:15 AM, Jeff King wrote:\n> > On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n> >\n> >> >> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n> >> >\n> >> > Thank you very much Felipe to take the time to upload the patches there.\n> >> > I already have a copy there and I'll look at it soon.\n> >>\n> >> Has anybody looked at this?  It's a bit large-ish and touches all over the\n> >> place, so I am finding it a bit hard to concentrate on it myself really\n> >> nitpicking, but from the cursory look after formatting the result looked\n> >> Ok.\n> >\n> > I started to, but the first commit message is lacking something that I\n> > think would make reviewing much simpler: what are the general classes of\n> > changes that are being made?\n> >\n> > I see some doublequotes becoming backticks, and some becoming single\n> > quotes. And some becoming tex-quotes (``...''), and even some becoming\n> > doublequotes _with_ single quotes. It would be easier to verify that\n> > they are doing the right thing if the commit message briefly described\n> > the rules it followed for changing each one. I think they are something\n> > like:\n> >\n> >  - tex-quotes if it was really a prose-style quotation\n> >\n> >  - backticks (causing monospace) for branch names, commands, etc in\n> >    prose\n> >\n> > but that leaves me confused. Some things which I thought should be in\n> > monospace backticks are in single-quotes (causing emphasis). Like\n> > 'master' or 'linux-2.6'. And some things are emphasized and in double\n> > quotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\n> > decide which text should have visible doublequotes but also be\n> > emphasized, as opposed to just having double-quotes or just being\n> > emphasized?\n> >\n> > Maybe this was even discussed earlier in the thread (I didn't go back to\n> > look), but it should definitely be part of the commit message.\n\nAgreed.\n\n> The rule I followed is: change it to whatever looks best.\n> \n> I followed some guidelines such as: make common text monospace, such\n> as gitk and master. And emphasize whatever needs emphasizing, such as\n> fb47ddb2db. Examples are both monospace *and* emphasized.\n> \n> Sometimes the end result still didn't look good so I just used\n> whatever looked best.\n\nIHMO, \"what looks best\" is not the best way to enhance the user manual\nbecause it may be somewhat confusing.\n\nWithout being as strict as in the manpages we should have good rules to\ndisplay the commands, branch names, etc to the end-users all over the\nmanual (think SYNOPSIS). For example, all branch names in the text could\nbe \"italic, green, without quotes\". Now, in the paragraph \"Fetching\nindividual branches\" we have\n\n will create a new branch named '\"example-master\"' and store in it the\n branch named '\"master\"' from the repository at the given URL. If you\n already have a branch named 'example-master', it will attempt to\n\nwhere the branch name /example-master/ has two different occurences _with_\nand _without_ quotes.\n\n\nThis is for the end user part. For the contributers, the commit could say:\n\n\" - branch names: uses the form 'branch-name' to appear in green,\n italic.\n - file names: uses [...] to appear in [...]\n - refspec: uses [...] to appear in [...]\n - etc.\n\"\n\n> Have you actually looked at the end result?\n\nYes, I think it's much better with your patch but \"display-types\" should\nfollow the same rules all over the text.\n\n\nI'm missing of time theses days. I think I'll could help you in one or\ntwo weeks I you want. It's an ant work. :-)\nAFAICT, some people here want to rewrite the manual, right? Maybe it\ncould be done with this rewriting?\n\n-- \nNicolas Sebrecht\n"},{"id":"114415","messageId":"4A155643.5030804@drmicha.warpmail.net","threadId":"19212","inReplyTo":"94a0d4530905210017x1ce3e32bk3b1fbf9044377763@mail.gmail.com","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-05-21T13:25:23Z","receivedAt":"2009-05-21T13:25:23Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Felipe Contreras venit, vidit, dixit 21.05.2009 09:17:\n> On Thu, May 21, 2009 at 7:15 AM, Jeff King wrote:\n>> On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n>>\n>>>>> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n>>>>\n>>>> Thank you very much Felipe to take the time to upload the patches there.\n>>>> I already have a copy there and I'll look at it soon.\n>>>\n>>> Has anybody looked at this? It's a bit large-ish and touches all over the\n>>> place, so I am finding it a bit hard to concentrate on it myself really\n>>> nitpicking, but from the cursory look after formatting the result looked\n>>> Ok.\n>>\n>> I started to, but the first commit message is lacking something that I\n>> think would make reviewing much simpler: what are the general classes of\n>> changes that are being made?\n>>\n>> I see some doublequotes becoming backticks, and some becoming single\n>> quotes. And some becoming tex-quotes (``...''), and even some becoming\n>> doublequotes _with_ single quotes. It would be easier to verify that\n>> they are doing the right thing if the commit message briefly described\n>> the rules it followed for changing each one. I think they are something\n>> like:\n>>\n>> - tex-quotes if it was really a prose-style quotation\n>>\n>> - backticks (causing monospace) for branch names, commands, etc in\n>> prose\n>>\n>> but that leaves me confused. Some things which I thought should be in\n>> monospace backticks are in single-quotes (causing emphasis). Like\n>> 'master' or 'linux-2.6'. And some things are emphasized and in double\n>> quotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\n>> decide which text should have visible doublequotes but also be\n>> emphasized, as opposed to just having double-quotes or just being\n>> emphasized?\n>>\n>> Maybe this was even discussed earlier in the thread (I didn't go back to\n>> look), but it should definitely be part of the commit message.\n> \n> The rule I followed is: change it to whatever looks best.\n> \n> I followed some guidelines such as: make common text monospace, such\n> as gitk and master. And emphasize whatever needs emphasizing, such as\n> fb47ddb2db. Examples are both monospace *and* emphasized.\n> \n> Sometimes the end result still didn't look good so I just used\n> whatever looked best.\n\nI think that's a bit of a \"quick and dirty\" approach. Man pages and user\nmanual should use semantic markup. The matter of \"looks\" is up to the\ndocumentation tool chain, i.e. the style sheets etc. for the various\nbackends.\n\nSo we would need:\n\n- a documentation \"style guide\" which tells you how to do the semantic\nmarkup, such as `cmd` for commands, 'foo' for emphasis etc.\n\n- maybe some changes to the style sheets etc. which make the semantic\nmarkup \"look good\"\n\nThe standard transformations which come with asciidoc/docbook can serve\nas a guide.\n\n> \n> Have you actually looked at the end result?\n> \n\nNo. My attempts at doing systematic changes (rather than modifying\nsingle pages without a clear target) have failed, so I've been keeping\nout of this business...\n\nCheers,\nMichael\n"},{"id":"114417","messageId":"7vvdnubl1x.fsf@alter.siamese.dyndns.org","threadId":"19212","inReplyTo":"94a0d4530905210017x1ce3e32bk3b1fbf9044377763@mail.gmail.com","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-05-21T14:14:02Z","receivedAt":"2009-05-21T14:14:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n>> Maybe this was even discussed earlier in the thread (I didn't go back to\n>> look), but it should definitely be part of the commit message.\n>\n> The rule I followed is: change it to whatever looks best.\n\n\"Looks best to me\" is not something other people can follow to replicate\nthe examples you set here to further \"clean up\" other parts of the\ndocumentation set or writing new sections to the document you touched up\nwith this patch.\n\nI suspect that you would not deny the possibility of saying \"The result\nlooked better when I last looked at it, but now I think about it I do not\nknow why I thought it looked better\" three months down the line.\n\nIt is not a rule.\n"},{"id":"114428","messageId":"94a0d4530905210847o697dd1f9w2f6ffcb8a109f0ca@mail.gmail.com","threadId":"19212","inReplyTo":"20090521131802.GA13840@vidovic","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-05-21T15:47:05Z","receivedAt":"2009-05-21T15:47:05Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht wrote:\n> The 21/05/09, Felipe Contreras wrote:\n>> On Thu, May 21, 2009 at 7:15 AM, Jeff King wrote:\n>> > On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n>> >\n>> >> >> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n>> >> >\n>> >> > Thank you very much Felipe to take the time to upload the patches there.\n>> >> > I already have a copy there and I'll look at it soon.\n>> >>\n>> >> Has anybody looked at this?  It's a bit large-ish and touches all over the\n>> >> place, so I am finding it a bit hard to concentrate on it myself really\n>> >> nitpicking, but from the cursory look after formatting the result looked\n>> >> Ok.\n>> >\n>> > I started to, but the first commit message is lacking something that I\n>> > think would make reviewing much simpler: what are the general classes of\n>> > changes that are being made?\n>> >\n>> > I see some doublequotes becoming backticks, and some becoming single\n>> > quotes. And some becoming tex-quotes (``...''), and even some becoming\n>> > doublequotes _with_ single quotes. It would be easier to verify that\n>> > they are doing the right thing if the commit message briefly described\n>> > the rules it followed for changing each one. I think they are something\n>> > like:\n>> >\n>> >  - tex-quotes if it was really a prose-style quotation\n>> >\n>> >  - backticks (causing monospace) for branch names, commands, etc in\n>> >    prose\n>> >\n>> > but that leaves me confused. Some things which I thought should be in\n>> > monospace backticks are in single-quotes (causing emphasis). Like\n>> > 'master' or 'linux-2.6'. And some things are emphasized and in double\n>> > quotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\n>> > decide which text should have visible doublequotes but also be\n>> > emphasized, as opposed to just having double-quotes or just being\n>> > emphasized?\n>> >\n>> > Maybe this was even discussed earlier in the thread (I didn't go back to\n>> > look), but it should definitely be part of the commit message.\n>\n> Agreed.\n>\n>> The rule I followed is: change it to whatever looks best.\n>>\n>> I followed some guidelines such as: make common text monospace, such\n>> as gitk and master. And emphasize whatever needs emphasizing, such as\n>> fb47ddb2db. Examples are both monospace *and* emphasized.\n>>\n>> Sometimes the end result still didn't look good so I just used\n>> whatever looked best.\n>\n> IHMO, \"what looks best\" is not the best way to enhance the user manual\n> because it may be somewhat confusing.\n>\n> Without being as strict as in the manpages we should have good rules to\n> display the commands, branch names, etc to the end-users all over the\n> manual (think SYNOPSIS). For example, all branch names in the text could\n> be \"italic, green, without quotes\". Now, in the paragraph \"Fetching\n> individual branches\" we have\n>\n>  will create a new branch named '\"example-master\"' and store in it the\n>  branch named '\"master\"' from the repository at the given URL.  If you\n>  already have a branch named 'example-master', it will attempt to\n>\n> where the branch name /example-master/ has two different occurences _with_\n> and _without_ quotes.\n\nYes, I wanted delimit \"example-master\", just like quotation marks are\nnormally used, but after it has been denoted there's no more point in\ndoing that over an over.\n\nFor example:\nHe referred to his friend as \"John\". But unlike him, \"John\" was very quiet.\n\nThe quotes make sense on the first sentence, but not on the second.\n\n> This is for the end user part. For the contributers, the commit could say:\n>\n> \" - branch names: uses the form 'branch-name' to appear in green,\n>    italic.\n>  - file names: uses [...] to appear in [...]\n>  - refspec: uses [...] to appear in [...]\n>  - etc.\n> \"\n\nNo, asciidoc only has support for: emphazised, strong, monospace,\nsingle-quoted and double-quoted. No colors or anything fancy.\n\nNot all branch names are equal; \"master\" is not the same as\n\"mybranch\". \"master\" has a special meaning, therefore it should be in\nmonospace, but \"mybranch\" is simply a branch name, therefore it should\nbe emphazied. If the branch name is complicated you might want to\ndelimit it with double quotes: \"my-fooish-bar-branch\", at least the\nfirst time you mention it.\n\nFile names is a similar story; \".gitignore\" is not the same as \"test.c\".\n\n>> Have you actually looked at the end result?\n>\n> Yes, I think it's much better with your patch but \"display-types\" should\n> follow the same rules all over the text.\n\nI disagree. There are no absolutes when writing human-readable documents.\n\n> I'm missing of time theses days. I think I'll could help you in one or\n> two weeks I you want. It's an ant work. :-)\n> AFAICT, some people here want to rewrite the manual, right? Maybe it\n> could be done with this rewriting?\n\nI have a bunch of patches and this was supposed to be the uncontroversial one =/\n\n-- \nFelipe Contreras\n"},{"id":"114430","messageId":"94a0d4530905210857y51c22909ke65d643abd3e8cee@mail.gmail.com","threadId":"19212","inReplyTo":"4A155643.5030804@drmicha.warpmail.net","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-05-21T15:57:49Z","receivedAt":"2009-05-21T15:57:49Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Thu, May 21, 2009 at 4:25 PM, Michael J Gruber\n wrote:\n> Felipe Contreras venit, vidit, dixit 21.05.2009 09:17:\n>> On Thu, May 21, 2009 at 7:15 AM, Jeff King wrote:\n>>> On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n>>>\n>>>>>> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n>>>>>\n>>>>> Thank you very much Felipe to take the time to upload the patches there.\n>>>>> I already have a copy there and I'll look at it soon.\n>>>>\n>>>> Has anybody looked at this?  It's a bit large-ish and touches all over the\n>>>> place, so I am finding it a bit hard to concentrate on it myself really\n>>>> nitpicking, but from the cursory look after formatting the result looked\n>>>> Ok.\n>>>\n>>> I started to, but the first commit message is lacking something that I\n>>> think would make reviewing much simpler: what are the general classes of\n>>> changes that are being made?\n>>>\n>>> I see some doublequotes becoming backticks, and some becoming single\n>>> quotes. And some becoming tex-quotes (``...''), and even some becoming\n>>> doublequotes _with_ single quotes. It would be easier to verify that\n>>> they are doing the right thing if the commit message briefly described\n>>> the rules it followed for changing each one. I think they are something\n>>> like:\n>>>\n>>>  - tex-quotes if it was really a prose-style quotation\n>>>\n>>>  - backticks (causing monospace) for branch names, commands, etc in\n>>>    prose\n>>>\n>>> but that leaves me confused. Some things which I thought should be in\n>>> monospace backticks are in single-quotes (causing emphasis). Like\n>>> 'master' or 'linux-2.6'. And some things are emphasized and in double\n>>> quotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\n>>> decide which text should have visible doublequotes but also be\n>>> emphasized, as opposed to just having double-quotes or just being\n>>> emphasized?\n>>>\n>>> Maybe this was even discussed earlier in the thread (I didn't go back to\n>>> look), but it should definitely be part of the commit message.\n>>\n>> The rule I followed is: change it to whatever looks best.\n>>\n>> I followed some guidelines such as: make common text monospace, such\n>> as gitk and master. And emphasize whatever needs emphasizing, such as\n>> fb47ddb2db. Examples are both monospace *and* emphasized.\n>>\n>> Sometimes the end result still didn't look good so I just used\n>> whatever looked best.\n>\n> I think that's a bit of a \"quick and dirty\" approach. Man pages and user\n> manual should use semantic markup. The matter of \"looks\" is up to the\n> documentation tool chain, i.e. the style sheets etc. for the various\n> backends.\n>\n> So we would need:\n>\n> - a documentation \"style guide\" which tells you how to do the semantic\n> markup, such as `cmd` for commands, 'foo' for emphasis etc.\n>\n> - maybe some changes to the style sheets etc. which make the semantic\n> markup \"look good\"\n>\n> The standard transformations which come with asciidoc/docbook can serve\n> as a guide.\n\nThere's already a guide: the asciidoc user-guide... you can only go as\nfar as asciidoc lets you. `` for monospace, '' for emphasis, ``'' for\ndouble quotes.\n\nI have a problem with clear-cut rules such as: `cmd` for commands.\n\nDo you think all these are the same?\nThe `git clone` command allows you to...\nYou can do that by doing '\"git commit -a -m Example\"'\nPlease refer to linkgit:git-add[1]\n\nIf you are reading the text you'll see that the 3 usages have different intents.\n\n>> Have you actually looked at the end result?\n>>\n>\n> No. My attempts at doing systematic changes (rather than modifying\n> single pages without a clear target) have failed, so I've been keeping\n> out of this business...\n\nIt's one click away:\nhttp://people.freedesktop.org/~felipec/git/user-manual/user-manual.html\n\n-- \nFelipe Contreras\n"},{"id":"114431","messageId":"94a0d4530905210900xa464f75se2bd2bf3d8103b10@mail.gmail.com","threadId":"19212","inReplyTo":"7vvdnubl1x.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-05-21T16:00:17Z","receivedAt":"2009-05-21T16:00:17Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Thu, May 21, 2009 at 5:14 PM, Junio C Hamano wrote:\n> Felipe Contreras writes:\n>\n>>> Maybe this was even discussed earlier in the thread (I didn't go back to\n>>> look), but it should definitely be part of the commit message.\n>>\n>> The rule I followed is: change it to whatever looks best.\n>\n> \"Looks best to me\" is not something other people can follow to replicate\n> the examples you set here to further \"clean up\" other parts of the\n> documentation set or writing new sections to the document you touched up\n> with this patch.\n>\n> I suspect that you would not deny the possibility of saying \"The result\n> looked better when I last looked at it, but now I think about it I do not\n> know why I thought it looked better\" three months down the line.\n>\n> It is not a rule.\n\nThe \"guidelines\" (not rules) I followed are a bit hard to explain,\nI'll try to do that, but in the meantime would you deny that the patch\nactually makes things a bit more consistent?\n\n-- \nFelipe Contreras\n"},{"id":"114432","messageId":"7v8wkqbfnr.fsf@alter.siamese.dyndns.org","threadId":"19212","inReplyTo":"94a0d4530905210900xa464f75se2bd2bf3d8103b10@mail.gmail.com","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-05-21T16:10:32Z","receivedAt":"2009-05-21T16:10:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> The \"guidelines\" (not rules) I followed are a bit hard to explain,\n> I'll try to do that, but in the meantime would you deny that the patch\n> actually makes things a bit more consistent?\n\nWell, until you spell out what your rules are to decide how things should\nbe marked up (e.g \"command name in prose should be spelled inside sq pair,\nlike 'git frotz'\"), I assert that I cannot even judge if the result of the\npatch is consistent with them. I can only say \"wooo, most of the branch\nnames look green\" or something like that, but that kind of comment on the\nconsistency is as useful to you as \"ahh, everything is spelled in American\nspellings\", iow, not much, isn't it?\n\nGetting everybody agree to the rules is a different matter, but that\nhappens only after everybody knows what the rules are.\n"},{"id":"114434","messageId":"F1CD811C-E625-4792-8341-7FA2A13E61AE@wincent.com","threadId":"19212","inReplyTo":"94a0d4530905210847o697dd1f9w2f6ffcb8a109f0ca@mail.gmail.com","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2009-05-21T16:41:28Z","receivedAt":"2009-05-21T16:41:28Z","isPatch":true,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 21/5/2009, a las 17:47, Felipe Contreras escribió:\n\n> On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht > wrote:\n>> The 21/05/09, Felipe Contreras wrote:\n>>> On Thu, May 21, 2009 at 7:15 AM, Jeff King wrote:\n>>\n> Not all branch names are equal; \"master\" is not the same as\n> \"mybranch\". \"master\" has a special meaning, therefore it should be in\n> monospace, but \"mybranch\" is simply a branch name, therefore it should\n> be emphazied. If the branch name is complicated you might want to\n> delimit it with double quotes: \"my-fooish-bar-branch\", at least the\n> first time you mention it.\n>\n> File names is a similar story; \".gitignore\" is not the same as \n> \"test.c\".\n>\n>>> Have you actually looked at the end result?\n>>\n>> Yes, I think it's much better with your patch but \"display-types\" \n>> should\n>> follow the same rules all over the text.\n>\n> I disagree. There are no absolutes when writing human-readable \n> documents.\n\nIt is human-readable, but for the purposes of this discussion it is \nmuch more relevant that it is a _technical_ document.\n\nAll good technical documentation that I've seen adheres to consistent \nstandards for display types. A \"how to read this book\" section in \nwhich the formatting of the different types appears is extremely \nwidespread, standard practice.\n\nHere's a very brief sampling for you:\n\nhttp://svnbook.red-bean.com/nightly/en/svn.preface.conventions.html\n\"Conventions used in this book\", from the SVN Book\n\nhttp://www.freebsd.org/doc/en/books/handbook/book-preface.html\n\"Conventions used in this book\", from the FreeBSD Handbook\n\nhttp://oreilly.com/catalog/debian/chapter/book/prf1_02.html\n\"Conventions used in this book\", from O'Reilly's \"Learning Debian\" book\n\nIf you're interested, a Google search for \"Conventions used in this \nbook\" will net you about 58,000 results to persuse.\n\nNot only are people used to understanding texts written using this \nkind of guideline, but it makes it easier for contributors as well if \ntheir a clear-cut conventions for different display types. They \nobviate the need for you to explain your reasoning about why \"master\" \nis somehow different from \"mybranch\", and why it should be formatted \ndifferently etc.\n\nCheers,\nWincent\n"},{"id":"114668","messageId":"4A1A920B.5000206@drmicha.warpmail.net","threadId":"19212","inReplyTo":"94a0d4530905210857y51c22909ke65d643abd3e8cee@mail.gmail.com","subject":"Re: [PATCH v3 0/2] Re: user-manual: general improvements","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-05-25T12:41:47Z","receivedAt":"2009-05-25T12:41:47Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Felipe Contreras venit, vidit, dixit 21.05.2009 17:57:\n> On Thu, May 21, 2009 at 4:25 PM, Michael J Gruber\n> wrote:\n>> Felipe Contreras venit, vidit, dixit 21.05.2009 09:17:\n>>> On Thu, May 21, 2009 at 7:15 AM, Jeff King wrote:\n>>>> On Wed, May 20, 2009 at 06:33:36PM -0700, Junio C Hamano wrote:\n>>>>\n>>>>>>> http://people.freedesktop.org/~felipec/git/user-manual-general-improvements/\n>>>>>>\n>>>>>> Thank you very much Felipe to take the time to upload the patches there.\n>>>>>> I already have a copy there and I'll look at it soon.\n>>>>>\n>>>>> Has anybody looked at this? It's a bit large-ish and touches all over the\n>>>>> place, so I am finding it a bit hard to concentrate on it myself really\n>>>>> nitpicking, but from the cursory look after formatting the result looked\n>>>>> Ok.\n>>>>\n>>>> I started to, but the first commit message is lacking something that I\n>>>> think would make reviewing much simpler: what are the general classes of\n>>>> changes that are being made?\n>>>>\n>>>> I see some doublequotes becoming backticks, and some becoming single\n>>>> quotes. And some becoming tex-quotes (``...''), and even some becoming\n>>>> doublequotes _with_ single quotes. It would be easier to verify that\n>>>> they are doing the right thing if the commit message briefly described\n>>>> the rules it followed for changing each one. I think they are something\n>>>> like:\n>>>>\n>>>> - tex-quotes if it was really a prose-style quotation\n>>>>\n>>>> - backticks (causing monospace) for branch names, commands, etc in\n>>>> prose\n>>>>\n>>>> but that leaves me confused. Some things which I thought should be in\n>>>> monospace backticks are in single-quotes (causing emphasis). Like\n>>>> 'master' or 'linux-2.6'. And some things are emphasized and in double\n>>>> quotes in the prose, like '\"o\"' or '\"branch A\"'. What is the rule to\n>>>> decide which text should have visible doublequotes but also be\n>>>> emphasized, as opposed to just having double-quotes or just being\n>>>> emphasized?\n>>>>\n>>>> Maybe this was even discussed earlier in the thread (I didn't go back to\n>>>> look), but it should definitely be part of the commit message.\n>>>\n>>> The rule I followed is: change it to whatever looks best.\n>>>\n>>> I followed some guidelines such as: make common text monospace, such\n>>> as gitk and master. And emphasize whatever needs emphasizing, such as\n>>> fb47ddb2db. Examples are both monospace *and* emphasized.\n>>>\n>>> Sometimes the end result still didn't look good so I just used\n>>> whatever looked best.\n>>\n>> I think that's a bit of a \"quick and dirty\" approach. Man pages and user\n>> manual should use semantic markup. The matter of \"looks\" is up to the\n>> documentation tool chain, i.e. the style sheets etc. for the various\n>> backends.\n>>\n>> So we would need:\n>>\n>> - a documentation \"style guide\" which tells you how to do the semantic\n>> markup, such as `cmd` for commands, 'foo' for emphasis etc.\n>>\n>> - maybe some changes to the style sheets etc. which make the semantic\n>> markup \"look good\"\n>>\n>> The standard transformations which come with asciidoc/docbook can serve\n>> as a guide.\n> \n> There's already a guide: the asciidoc user-guide... you can only go as\n> far as asciidoc lets you. `` for monospace, '' for emphasis, ``'' for\n> double quotes.\n\nI am sorry but I don't think you fully comprehend the documentation tool\nchain. Asciidoc translates the *.txt according to config files which\ncome with asciidoc and can be (and are, in our case) modified. It\ntranslates into xml (for man pages) which is semantic markup. Even at\nthat step, there are more options - the standard asciidoc.conf (asciidoc\n8) has:\n\n[quotes]\n# Constrained quotes.\n*=strong\n'=emphasis\n`=monospaced\n``|''=quoted\nifdef::asciidoc7compatible[]\n\\##=unquoted\nendif::asciidoc7compatible[]\nifndef::asciidoc7compatible[]\n\\#=unquoted\n_=emphasis\n+=monospaced\n# Unconstrained quotes.\n**=#strong\n__=#emphasis\n++=#monospaced\n\\##=#unquoted\n^=#superscript\n~=#subscript\nendif::asciidoc7compatible[]\n\nSo, you see we could use quite a few more quote designators if we wished\nto. We only needed ' and _ to be different, for example.\n\nBackend specific config files determine what \"emphasis\" is translated\ninto: an tag for docbook-xml, an tag (with attributes)\nfor xhtml.\n\nThen, for man page format, docbook style sheets are applied (using\nxsltproc or such) to the xml files. The final appearance is determined\nby those sheets. (For html, it's merely css applied by the browser.)\n\nThe asciidoc manual really only explains example usage with the default,\nunmodified config files.\n\n> \n> I have a problem with clear-cut rules such as: `cmd` for commands.\n> \n> Do you think all these are the same?\n> The `git clone` command allows you to...\n> You can do that by doing '\"git commit -a -m Example\"'\n> Please refer to linkgit:git-add[1]\n> \n> If you are reading the text you'll see that the 3 usages have different intents.\n\nYes, which is why I said \"for example\", and why a guide needs some\nthinking. Or I would have come up with one...\n\n> \n>>> Have you actually looked at the end result?\n>>>\n>>\n>> No. My attempts at doing systematic changes (rather than modifying\n>> single pages without a clear target) have failed, so I've been keeping\n>> out of this business...\n> \n> It's one click away:\n> http://people.freedesktop.org/~felipec/git/user-manual/user-manual.html\n> \n\nI guess you completely misunderstood my remark (and I may very well be\nthe one to blame for that), and it doesn't matter in the context of this\nthread. I have no problems formatting the user-manual, thanks to the\nrecent addition of ASCIIDOC_NO_ROFF ;)\n\nMichael\n"}]}