Re: user-manual: patch proposals and questions

[Eric Sunshine <sunshine@sunshineco.com>]

On Sun, Mar 18, 2018 at 7:49 PM, kalle <kalle@projektwerkstatt.de> wrote:
> 1.I wonder, why the "user-manual" is so hidden on the (official?) site
> git-scm.com [it is accessible at git-scm.com/docs/user-manual ,but is
> not viewable in /docs ]

The git-scm.com website is maintained as a distinct project[1] at
Github; it is not directly related to the Git project itself. A good
way to voice your concern about the website is either to open an issue
ticket[2] or submit a pull request[3] if you have a specific change in
mind.

[1]: https://github.com/git/git-scm.com
[2]: https://github.com/git/git-scm.com/issues
[3]: https://github.com/git/git-scm.com/pulls

> 2.I did not receive an answer to my mail. Maybe it could have to do with
> a possible stopped maintainment of the 'user-manual'

More likely it was because your email was not composed in a way for
people to digest and respond to it easily. There are some things you
can do to help make it easier for people to respond:

* Send patches inline rather than attachments since it is much easier
for people to respond to them directly when inline. When they are
attachments, people are forced to open the attachment, then copy/paste
parts of the patch back into the email for response, and most people
won't bother with such effort. Also, make each patch a separate email
with a meaningful commit message ("git format-patch" and "git
send-email" can help with this).

* For your questions about documentation, quote the section of
documentation you want to talk about directly in your email, then ask
a question about it. This saves people the effort of manually having
to open the file and locate the line or paragraph in question. Also,
line numbers change as changes are made to files, so the line number
you cite might not match the line number in a version of the file
someone else is looking at.

> 3.it would be for non-graphics-users to have the Git-Pro-book in
> text-format.

Like the website, the Pro Git book is a distinct project[4], not
directly related to the Git project. To suggest making the book
available as plain text, you can open an issue ticket[5] or submit a
pull request[6] if you implement it yourself.

[4]: https://github.com/progit/progit2
[5]: https://github.com/progit/progit2/issues
[6]: https://github.com/progit/progit2/pulls


> -------- Weitergeleitete Nachricht --------
> Betreff: user-manual: patch proposals and questions
> Datum: Tue, 6 Mar 2018 00:08:55 +0100
> Von: kalle <kalle@projektwerkstatt.de>
> An: git@vger.kernel.org
>
> The patches are attached.
> Further some questions:
>
> -see the explanations of the branch command, ca. line 280: wouldn't it
> be better to use other words than 'references'?
> -sentence "it shows all commits reachable from the parent commit": it
> seems wrong to me. The last commit is also shown.
> - chapter "Browsing revisions": it seems counterintuitive to me to have
> two different logics for the meaning of "branch1..branch2" and
> "branch1...branch2", according to whether it's the argument of `git log'
> or `git diff'
> -section "Check whether two branches point at the same history": 'git
> diff origin..master' -> shouldn't it be rather 'git diff
> branch1..branch2'? … or rewrite the example with branch1=origin and
> branch2=master.
>
> greetings,
> kalle