* [PATCH v3 0/2] user-manual: general improvements @ 2009-05-06 22:53 Felipe Contreras [not found] ` <1241650416-12224-2-git-send-email-felipe.contreras@gmail.com> 2009-05-07 7:23 ` [PATCH v3 0/2] Re: user-manual: general improvements Nicolas Sebrecht 0 siblings, 2 replies; 17+ messages in thread From: Felipe Contreras @ 2009-05-06 22:53 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Felipe Contreras I split the previous patch series, now only trivial changes are included. Felipe Contreras (2): user-manual: general quoting improvements user-manual: use 'fast-forward' instead of 'fast forward' Documentation/user-manual.txt | 890 ++++++++++++++++++++-------------------- 1 files changed, 445 insertions(+), 445 deletions(-) ^ permalink raw reply [flat|nested] 17+ messages in thread
[parent not found: <1241650416-12224-2-git-send-email-felipe.contreras@gmail.com>]
* [PATCH v3 2/2] user-manual: use 'fast-forward' instead of 'fast forward' [not found] ` <1241650416-12224-2-git-send-email-felipe.contreras@gmail.com> @ 2009-05-06 22:53 ` Felipe Contreras 0 siblings, 0 replies; 17+ messages in thread From: Felipe Contreras @ 2009-05-06 22:53 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Felipe Contreras Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/user-manual.txt | 14 +++++++------- 1 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index a8558a1..9978027 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1384,7 +1384,7 @@ were merged. However, if the current branch is a descendant of the other--so every commit present in the one is already contained in the other--then git -just performs a '``fast forward'''; the head of the current branch is moved +just performs a 'fast-forward'; the head of the current branch is moved forward to point at the head of the merged-in branch, without any new commits being created. @@ -1719,7 +1719,7 @@ producing a default commit message documenting the branch and repository that you pulled from. (But note that no such commit will be created in the case of a -<<fast-forwards,fast forward>>; instead, your branch will just be +<<fast-forwards,fast-forward>>; instead, your branch will just be updated to point to the latest commit from the upstream branch.) The `git pull` command can also be given '"."' as the 'remote' repository, @@ -1943,7 +1943,7 @@ $ git push ssh://yourserver.com/~you/proj.git master ------------------------------------------------- As with `git fetch`, `git push` will complain if this does not result in a -<<fast-forwards,fast forward>>; see the following section for details on +<<fast-forwards,fast-forward>>; see the following section for details on handling this case. Note that the target of a 'push' is normally a @@ -1976,7 +1976,7 @@ details. What to do when a push fails ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If a push would not result in a <<fast-forwards,fast forward>> of the +If a push would not result in a <<fast-forwards,fast-forward>> of the remote branch, then it will fail with an error like: ------------------------------------------------- @@ -2115,7 +2115,7 @@ $ git checkout release && git pull *Important note!* If you have any local changes in these branches, then this merge will create a commit object in the history (with no local -changes git will simply do a 'fast forward' merge). Many people dislike +changes git will simply do a 'fast-forward' merge). Many people dislike the ``noise'' that this creates in the Linux history, so you should avoid doing this capriciously in the 'release' branch, as these noisy commits will become part of the permanent history when you ask Linus to pull @@ -2729,9 +2729,9 @@ In the previous example, when updating an existing branch, "git fetch" checks to make sure that the most recent commit on the remote branch is a descendant of the most recent commit on your copy of the branch before updating your copy of the branch to point at the new -commit. Git calls this process a <<fast-forwards,fast forward>>. +commit. Git calls this process a <<fast-forwards,fast-forward>>. -A 'fast forward' looks something like this: +A 'fast-forward' looks something like this: ................................................ o--o--o--o <-- old head of the branch -- 1.6.3.rc4.14.g96da.dirty ^ permalink raw reply related [flat|nested] 17+ messages in thread
* [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-06 22:53 [PATCH v3 0/2] user-manual: general improvements Felipe Contreras [not found] ` <1241650416-12224-2-git-send-email-felipe.contreras@gmail.com> @ 2009-05-07 7:23 ` Nicolas Sebrecht 2009-05-08 0:04 ` Junio C Hamano 1 sibling, 1 reply; 17+ messages in thread From: Nicolas Sebrecht @ 2009-05-07 7:23 UTC (permalink / raw) To: Felipe Contreras; +Cc: git, Junio C Hamano The 07/05/09, Felipe Contreras wrote: > Felipe Contreras (2): Hi, > user-manual: general quoting improvements I didn't receive the v3 of this patch and it neither appears in gmane. http://article.gmane.org/gmane.comp.version-control.git/118399 Could you please resend it ? -- Nicolas Sebrecht ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-07 7:23 ` [PATCH v3 0/2] Re: user-manual: general improvements Nicolas Sebrecht @ 2009-05-08 0:04 ` Junio C Hamano [not found] ` <20090508042814.GA30031@vidovic> 0 siblings, 1 reply; 17+ messages in thread From: Junio C Hamano @ 2009-05-08 0:04 UTC (permalink / raw) To: Nicolas Sebrecht; +Cc: Felipe Contreras, git, Junio C Hamano Nicolas Sebrecht <nicolas.s.dev@gmx.fr> writes: > The 07/05/09, Felipe Contreras wrote: > >> Felipe Contreras (2): > > Hi, > >> user-manual: general quoting improvements > > I didn't receive the v3 of this patch and it neither appears in gmane. > http://article.gmane.org/gmane.comp.version-control.git/118399 > > Could you please resend it ? Felipe has been resending it for a few rounds, but it appears it never goes through vger (nor directly to me). It's a bit frustrating (no, not a fault of Felipe's). ^ permalink raw reply [flat|nested] 17+ messages in thread
[parent not found: <20090508042814.GA30031@vidovic>]
[parent not found: <94a0d4530905131430q2250a43ei692265c3f32b5715@mail.gmail.com>]
[parent not found: <20090514160609.GA12910@vidovic>]
* Re: [PATCH v3 0/2] Re: user-manual: general improvements [not found] ` <20090514160609.GA12910@vidovic> @ 2009-05-21 1:33 ` Junio C Hamano 2009-05-21 4:15 ` Jeff King 0 siblings, 1 reply; 17+ messages in thread From: Junio C Hamano @ 2009-05-21 1:33 UTC (permalink / raw) To: Nicolas Sebrecht; +Cc: Felipe Contreras, git Nicolas Sebrecht <nicolas.s.dev@gmx.fr> writes: > The 14/05/09, Felipe Contreras wrote: > ... >> I've uploaded the patches here: >> 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. ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 1:33 ` Junio C Hamano @ 2009-05-21 4:15 ` Jeff King 2009-05-21 5:18 ` Junio C Hamano 2009-05-21 7:17 ` Felipe Contreras 0 siblings, 2 replies; 17+ messages in thread From: Jeff King @ 2009-05-21 4:15 UTC (permalink / raw) To: Junio C Hamano; +Cc: Nicolas Sebrecht, Felipe Contreras, git 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. -Peff ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 4:15 ` Jeff King @ 2009-05-21 5:18 ` Junio C Hamano 2009-05-21 7:17 ` Felipe Contreras 1 sibling, 0 replies; 17+ messages in thread From: Junio C Hamano @ 2009-05-21 5:18 UTC (permalink / raw) To: Jeff King; +Cc: Nicolas Sebrecht, Felipe Contreras, git Jeff King <peff@peff.net> writes: > 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. I do not think there was any discussion, as the original patch never made to the list. And I realize that the difficulty I had while reading this was exactly what you described here. Thanks for saying it very clearly. ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 4:15 ` Jeff King 2009-05-21 5:18 ` Junio C Hamano @ 2009-05-21 7:17 ` Felipe Contreras 2009-05-21 13:18 ` Nicolas Sebrecht ` (2 more replies) 1 sibling, 3 replies; 17+ messages in thread From: Felipe Contreras @ 2009-05-21 7:17 UTC (permalink / raw) To: Jeff King; +Cc: Junio C Hamano, Nicolas Sebrecht, git On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 7:17 ` Felipe Contreras @ 2009-05-21 13:18 ` Nicolas Sebrecht 2009-05-21 15:47 ` Felipe Contreras 2009-05-21 13:25 ` Michael J Gruber 2009-05-21 14:14 ` Junio C Hamano 2 siblings, 1 reply; 17+ messages in thread From: Nicolas Sebrecht @ 2009-05-21 13:18 UTC (permalink / raw) To: Felipe Contreras; +Cc: Jeff King, Junio C Hamano, Nicolas Sebrecht, git The 21/05/09, Felipe Contreras wrote: > On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> 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. 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. " > 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'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? -- Nicolas Sebrecht ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 13:18 ` Nicolas Sebrecht @ 2009-05-21 15:47 ` Felipe Contreras 2009-05-21 16:41 ` Wincent Colaiuta 0 siblings, 1 reply; 17+ messages in thread From: Felipe Contreras @ 2009-05-21 15:47 UTC (permalink / raw) To: Nicolas Sebrecht; +Cc: Jeff King, Junio C Hamano, git On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht <nicolas.s.dev@gmx.fr> wrote: > The 21/05/09, Felipe Contreras wrote: >> On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 15:47 ` Felipe Contreras @ 2009-05-21 16:41 ` Wincent Colaiuta 0 siblings, 0 replies; 17+ messages in thread From: Wincent Colaiuta @ 2009-05-21 16:41 UTC (permalink / raw) To: Felipe Contreras; +Cc: Nicolas Sebrecht, Jeff King, Junio C Hamano, git El 21/5/2009, a las 17:47, Felipe Contreras escribió: > On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht <nicolas.s.dev@gmx.fr > > wrote: >> The 21/05/09, Felipe Contreras wrote: >>> On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> wrote: >> > 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. It is human-readable, but for the purposes of this discussion it is much more relevant that it is a _technical_ document. All good technical documentation that I've seen adheres to consistent standards for display types. A "how to read this book" section in which the formatting of the different types appears is extremely widespread, standard practice. Here's a very brief sampling for you: http://svnbook.red-bean.com/nightly/en/svn.preface.conventions.html "Conventions used in this book", from the SVN Book http://www.freebsd.org/doc/en/books/handbook/book-preface.html "Conventions used in this book", from the FreeBSD Handbook http://oreilly.com/catalog/debian/chapter/book/prf1_02.html "Conventions used in this book", from O'Reilly's "Learning Debian" book If you're interested, a Google search for "Conventions used in this book" will net you about 58,000 results to persuse. Not only are people used to understanding texts written using this kind of guideline, but it makes it easier for contributors as well if their a clear-cut conventions for different display types. They obviate the need for you to explain your reasoning about why "master" is somehow different from "mybranch", and why it should be formatted differently etc. Cheers, Wincent ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 7:17 ` Felipe Contreras 2009-05-21 13:18 ` Nicolas Sebrecht @ 2009-05-21 13:25 ` Michael J Gruber 2009-05-21 15:57 ` Felipe Contreras 2009-05-21 14:14 ` Junio C Hamano 2 siblings, 1 reply; 17+ messages in thread From: Michael J Gruber @ 2009-05-21 13:25 UTC (permalink / raw) To: Felipe Contreras; +Cc: Jeff King, Junio C Hamano, Nicolas Sebrecht, git Felipe Contreras venit, vidit, dixit 21.05.2009 09:17: > On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> 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. > > 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... Cheers, Michael ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 13:25 ` Michael J Gruber @ 2009-05-21 15:57 ` Felipe Contreras 2009-05-25 12:41 ` Michael J Gruber 0 siblings, 1 reply; 17+ messages in thread From: Felipe Contreras @ 2009-05-21 15:57 UTC (permalink / raw) To: Michael J Gruber; +Cc: Jeff King, Junio C Hamano, Nicolas Sebrecht, git On Thu, May 21, 2009 at 4:25 PM, Michael J Gruber <git@drmicha.warpmail.net> wrote: > Felipe Contreras venit, vidit, dixit 21.05.2009 09:17: >> On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 15:57 ` Felipe Contreras @ 2009-05-25 12:41 ` Michael J Gruber 0 siblings, 0 replies; 17+ messages in thread From: Michael J Gruber @ 2009-05-25 12:41 UTC (permalink / raw) To: Felipe Contreras; +Cc: Jeff King, Junio C Hamano, Nicolas Sebrecht, git Felipe Contreras venit, vidit, dixit 21.05.2009 17:57: > On Thu, May 21, 2009 at 4:25 PM, Michael J Gruber > <git@drmicha.warpmail.net> wrote: >> Felipe Contreras venit, vidit, dixit 21.05.2009 09:17: >>> On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> 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 am sorry but I don't think you fully comprehend the documentation tool chain. Asciidoc translates the *.txt according to config files which come with asciidoc and can be (and are, in our case) modified. It translates into xml (for man pages) which is semantic markup. Even at that step, there are more options - the standard asciidoc.conf (asciidoc 8) has: [quotes] # Constrained quotes. *=strong '=emphasis `=monospaced ``|''=quoted ifdef::asciidoc7compatible[] \##=unquoted endif::asciidoc7compatible[] ifndef::asciidoc7compatible[] \#=unquoted _=emphasis +=monospaced # Unconstrained quotes. **=#strong __=#emphasis ++=#monospaced \##=#unquoted ^=#superscript ~=#subscript endif::asciidoc7compatible[] So, you see we could use quite a few more quote designators if we wished to. We only needed ' and _ to be different, for example. Backend specific config files determine what "emphasis" is translated into: an <emphasis> tag for docbook-xml, an <em> tag (with attributes) for xhtml. Then, for man page format, docbook style sheets are applied (using xsltproc or such) to the xml files. The final appearance is determined by those sheets. (For html, it's merely css applied by the browser.) The asciidoc manual really only explains example usage with the default, unmodified config files. > > 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. Yes, which is why I said "for example", and why a guide needs some thinking. Or I would have come up with one... > >>> 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 > I guess you completely misunderstood my remark (and I may very well be the one to blame for that), and it doesn't matter in the context of this thread. I have no problems formatting the user-manual, thanks to the recent addition of ASCIIDOC_NO_ROFF ;) Michael ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 7:17 ` Felipe Contreras 2009-05-21 13:18 ` Nicolas Sebrecht 2009-05-21 13:25 ` Michael J Gruber @ 2009-05-21 14:14 ` Junio C Hamano 2009-05-21 16:00 ` Felipe Contreras 2 siblings, 1 reply; 17+ messages in thread From: Junio C Hamano @ 2009-05-21 14:14 UTC (permalink / raw) To: Felipe Contreras; +Cc: Jeff King, Nicolas Sebrecht, git Felipe Contreras <felipe.contreras@gmail.com> writes: >> 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. "Looks best to me" is not something other people can follow to replicate the examples you set here to further "clean up" other parts of the documentation set or writing new sections to the document you touched up with this patch. I suspect that you would not deny the possibility of saying "The result looked better when I last looked at it, but now I think about it I do not know why I thought it looked better" three months down the line. It is not a rule. ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 14:14 ` Junio C Hamano @ 2009-05-21 16:00 ` Felipe Contreras 2009-05-21 16:10 ` Junio C Hamano 0 siblings, 1 reply; 17+ messages in thread From: Felipe Contreras @ 2009-05-21 16:00 UTC (permalink / raw) To: Junio C Hamano; +Cc: Jeff King, Nicolas Sebrecht, git On Thu, May 21, 2009 at 5:14 PM, Junio C Hamano <gitster@pobox.com> wrote: > Felipe Contreras <felipe.contreras@gmail.com> writes: > >>> 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. > > "Looks best to me" is not something other people can follow to replicate > the examples you set here to further "clean up" other parts of the > documentation set or writing new sections to the document you touched up > with this patch. > > I suspect that you would not deny the possibility of saying "The result > looked better when I last looked at it, but now I think about it I do not > know why I thought it looked better" three months down the line. > > It is not a rule. The "guidelines" (not rules) I followed are a bit hard to explain, I'll try to do that, but in the meantime would you deny that the patch actually makes things a bit more consistent? -- Felipe Contreras ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH v3 0/2] Re: user-manual: general improvements 2009-05-21 16:00 ` Felipe Contreras @ 2009-05-21 16:10 ` Junio C Hamano 0 siblings, 0 replies; 17+ messages in thread From: Junio C Hamano @ 2009-05-21 16:10 UTC (permalink / raw) To: Felipe Contreras; +Cc: Jeff King, Nicolas Sebrecht, git Felipe Contreras <felipe.contreras@gmail.com> writes: > The "guidelines" (not rules) I followed are a bit hard to explain, > I'll try to do that, but in the meantime would you deny that the patch > actually makes things a bit more consistent? Well, until you spell out what your rules are to decide how things should be marked up (e.g "command name in prose should be spelled inside sq pair, like 'git frotz'"), I assert that I cannot even judge if the result of the patch is consistent with them. I can only say "wooo, most of the branch names look green" or something like that, but that kind of comment on the consistency is as useful to you as "ahh, everything is spelled in American spellings", iow, not much, isn't it? Getting everybody agree to the rules is a different matter, but that happens only after everybody knows what the rules are. ^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2009-05-25 12:42 UTC | newest] Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2009-05-06 22:53 [PATCH v3 0/2] user-manual: general improvements Felipe Contreras [not found] ` <1241650416-12224-2-git-send-email-felipe.contreras@gmail.com> 2009-05-06 22:53 ` [PATCH v3 2/2] user-manual: use 'fast-forward' instead of 'fast forward' Felipe Contreras 2009-05-07 7:23 ` [PATCH v3 0/2] Re: user-manual: general improvements Nicolas Sebrecht 2009-05-08 0:04 ` Junio C Hamano [not found] ` <20090508042814.GA30031@vidovic> [not found] ` <94a0d4530905131430q2250a43ei692265c3f32b5715@mail.gmail.com> [not found] ` <20090514160609.GA12910@vidovic> 2009-05-21 1:33 ` Junio C Hamano 2009-05-21 4:15 ` Jeff King 2009-05-21 5:18 ` Junio C Hamano 2009-05-21 7:17 ` Felipe Contreras 2009-05-21 13:18 ` Nicolas Sebrecht 2009-05-21 15:47 ` Felipe Contreras 2009-05-21 16:41 ` Wincent Colaiuta 2009-05-21 13:25 ` Michael J Gruber 2009-05-21 15:57 ` Felipe Contreras 2009-05-25 12:41 ` Michael J Gruber 2009-05-21 14:14 ` Junio C Hamano 2009-05-21 16:00 ` Felipe Contreras 2009-05-21 16:10 ` Junio C Hamano
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).