[PATCH v3 0/2] user-manual: general improvements

[PATCH v3 0/2] user-manual: general improvements

[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(-)

[PATCH v3 2/2] user-manual: use 'fast-forward' instead of 'fast forward'

[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

[PATCH v3 0/2] Re: user-manual: general improvements

[Nicolas Sebrecht]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[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).

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Junio C Hamano]

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.

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Jeff King]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Junio C Hamano]

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.

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Felipe Contreras]

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

[PATCH v3 0/2] Re: user-manual: general improvements

[Nicolas Sebrecht]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Michael J Gruber]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Junio C Hamano]

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.

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Felipe Contreras]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Felipe Contreras]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Felipe Contreras]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Junio C Hamano]

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.

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Wincent Colaiuta]

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

Re: [PATCH v3 0/2] Re: user-manual: general improvements

[Michael J Gruber]

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