[RFC/PATCH 0/5] Make README more pleasant to read

[RFC/PATCH 0/5] Make README more pleasant to read

[Matthieu Moy]

This patch series was inspired by a discussion I had with Emma Jane
after Git Merge last year. It tries both to make the README file less
agressive and generally more pleasant to read.

To get a quick overview, compare the old one:

  https://github.com/git/git#readme

and my proposal:

  https://github.com/moy/git/tree/git-readme#readme

Matthieu Moy (5):
  README: use markdown syntax
  README.md: add hyperlinks on filenames
  README.md: move the link to git-scm.com up
  README.md: don't call git stupid in the title
  README.md: move down historical explanation about the name

 README => README.md | 54 ++++++++++++++++++++++++++++-------------------------
 t/t7001-mv.sh       |  2 +-
 2 files changed, 30 insertions(+), 26 deletions(-)
 rename README => README.md (67%)

-- 
2.7.2.334.g35ed2ae.dirty

[PATCH 1/5] README: use markdown syntax

[Matthieu Moy]

This allows repository browsers like GitHub to display the content of
the file nicely formatted.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README => README.md | 6 +-----
 t/t7001-mv.sh       | 2 +-
 2 files changed, 2 insertions(+), 6 deletions(-)
 rename README => README.md (93%)

diff --git a/README b/README.md
similarity index 93%
rename from README
rename to README.md
index 1083735..907eb3b 100644
--- a/README
+++ b/README.md
@@ -1,8 +1,4 @@
-////////////////////////////////////////////////////////////////
-
-	Git - the stupid content tracker
-
-////////////////////////////////////////////////////////////////
+# Git - the stupid content tracker
 
 "git" can mean anything, depending on your mood.
 
diff --git a/t/t7001-mv.sh b/t/t7001-mv.sh
index 51dd2b4..4008fae 100755
--- a/t/t7001-mv.sh
+++ b/t/t7001-mv.sh
@@ -102,7 +102,7 @@ test_expect_success \
 
 test_expect_success \
     'adding another file' \
-    'cp "$TEST_DIRECTORY"/../README path0/README &&
+    'cp "$TEST_DIRECTORY"/../README.md path0/README &&
      git add path0/README &&
      git commit -m add2 -a'
 
-- 
2.7.2.334.g35ed2ae.dirty

Re: [PATCH 1/5] README: use markdown syntax

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> This allows repository browsers like GitHub to display the content of
> the file nicely formatted.
>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---

To be honest, I have the most problem with this step in the whole
series.

Markdown when rendered may be easier to read, but plain text is even
easier, and it somehow feels backward to cater to those who browse
at GitHub sacrificing those who use "less" in the source tree.

>  README => README.md | 6 +-----
>  t/t7001-mv.sh       | 2 +-
>  2 files changed, 2 insertions(+), 6 deletions(-)
>  rename README => README.md (93%)
>
> diff --git a/README b/README.md
> similarity index 93%
> rename from README
> rename to README.md
> index 1083735..907eb3b 100644
> --- a/README
> +++ b/README.md
> @@ -1,8 +1,4 @@
> -////////////////////////////////////////////////////////////////
> -
> -	Git - the stupid content tracker
> -
> -////////////////////////////////////////////////////////////////
> +# Git - the stupid content tracker
>  
>  "git" can mean anything, depending on your mood.
>  
> diff --git a/t/t7001-mv.sh b/t/t7001-mv.sh
> index 51dd2b4..4008fae 100755
> --- a/t/t7001-mv.sh
> +++ b/t/t7001-mv.sh
> @@ -102,7 +102,7 @@ test_expect_success \
>  
>  test_expect_success \
>      'adding another file' \
> -    'cp "$TEST_DIRECTORY"/../README path0/README &&
> +    'cp "$TEST_DIRECTORY"/../README.md path0/README &&
>       git add path0/README &&
>       git commit -m add2 -a'

Re: [PATCH 1/5] README: use markdown syntax

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> Matthieu Moy <Matthieu.Moy@imag.fr> writes:
>
>> This allows repository browsers like GitHub to display the content of
>> the file nicely formatted.
>>
>> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
>> ---
>
> To be honest, I have the most problem with this step in the whole
> series.
>
> Markdown when rendered may be easier to read, but plain text is even
> easier, and it somehow feels backward to cater to those who browse
> at GitHub sacrificing those who use "less" in the source tree.

Well, actually almost all the page was already in markdown. The real
change done by this patch is a rename, and change the asciiart in the
title:

>> --- a/README
>> +++ b/README.md
>> @@ -1,8 +1,4 @@
>> -////////////////////////////////////////////////////////////////
>> -
>> -	Git - the stupid content tracker
>> -
>> -////////////////////////////////////////////////////////////////
>> +# Git - the stupid content tracker

Markdown would also accept ascii-art underlining.

Git - the stupid content tracker
================================

we can use this if people think it's easier to read in the source.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH 1/5] README: use markdown syntax

[Johannes Schindelin]

Hi Junio,

On Tue, 23 Feb 2016, Junio C Hamano wrote:

> Matthieu Moy <Matthieu.Moy@imag.fr> writes:
> 
> > This allows repository browsers like GitHub to display the content of
> > the file nicely formatted.
> >
> > Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> > ---
> 
> To be honest, I have the most problem with this step in the whole
> series.
> 
> Markdown when rendered may be easier to read, but plain text is even
> easier, and it somehow feels backward to cater to those who browse
> at GitHub sacrificing those who use "less" in the source tree.

That assumes that the primary audience of the README file is the
developers who already decided to clone the repository, as opposed to
people browsing the README file in the browser to determine whether they
found the correct project, or to read up on the background of the project
without downloading the entire source code.

I'd wager real money (without scientific evidence. just going on common
sense) that your 'less' people are in the vast minority.

Since I am convinced that markdown'ed READMEs enhance the user experience
dramatically, Git for Windows has one already for a long time.

Hence *my* main objection: this patch series would conflict with patches
we carry in Git for Windows.

;-)

Ciao,
Dscho

P.S.: If it was not clear, my objection was meant as a joke. I am very
much in favor of enhancing the user experience via Matthieu's patches.

Re: [PATCH 1/5] README: use markdown syntax

[Jeff King]

On Wed, Feb 24, 2016 at 08:08:52AM +0100, Johannes Schindelin wrote:

> > Markdown when rendered may be easier to read, but plain text is even
> > easier, and it somehow feels backward to cater to those who browse
> > at GitHub sacrificing those who use "less" in the source tree.
> 
> That assumes that the primary audience of the README file is the
> developers who already decided to clone the repository, as opposed to
> people browsing the README file in the browser to determine whether they
> found the correct project, or to read up on the background of the project
> without downloading the entire source code.
> 
> I'd wager real money (without scientific evidence. just going on common
> sense) that your 'less' people are in the vast minority.
> 
> Since I am convinced that markdown'ed READMEs enhance the user experience
> dramatically, Git for Windows has one already for a long time.

Yeah, I agree. I cannot imagine why I would read Git's README at this
point in time.  And I find I primarily consume READMEs on the web these
days, as they are the first step in me figuring out whether a project is
worth looking into.

Whereas I _do_ care what things like Documentation/technical look like,
or CodingGuidelines, because I actually refer to them locally.

IMHO the title formatting is somewhat moot, though, as we can have our
cake and eat it, too, with the "====" underlines. I don't think they are
any worse than the lines of slashes in the original. :)

I'd worry more about the [] links from patch 2, but even those are fine
by me.

-Peff

[PATCH 2/5] README.md: add hyperlinks on filenames

[Matthieu Moy]

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 907eb3b..750fdda 100644
--- a/README.md
+++ b/README.md
@@ -20,17 +20,17 @@ License version 2 (some parts of it are under different licenses,
 compatible with the GPLv2). It was originally written by Linus
 Torvalds with help of a group of hackers around the net.
 
-Please read the file INSTALL for installation instructions.
+Please read the file [INSTALL][] for installation instructions.
 
-See Documentation/gittutorial.txt to get started, then see
-Documentation/giteveryday.txt for a useful minimum set of commands, and
-Documentation/git-commandname.txt for documentation of each command.
+See [Documentation/gittutorial.txt][] to get started, then see
+[Documentation/giteveryday.txt][] for a useful minimum set of commands, and
+[Documentation/git-commandname.txt][] for documentation of each command.
 If git has been correctly installed, then the tutorial can also be
 read with "man gittutorial" or "git help tutorial", and the
 documentation of each command with "man git-commandname" or "git help
 commandname".
 
-CVS users may also want to read Documentation/gitcvs-migration.txt
+CVS users may also want to read [Documentation/gitcvs-migration.txt][]
 ("man gitcvs-migration" or "git help cvs-migration" if git is
 installed).
 
@@ -40,7 +40,7 @@ including full documentation and Git related tools.
 The user discussion and development of Git take place on the Git
 mailing list -- everyone is welcome to post bug reports, feature
 requests, comments and patches to git@vger.kernel.org (read
-Documentation/SubmittingPatches for instructions on patch submission).
+[Documentation/SubmittingPatches][] for instructions on patch submission).
 To subscribe to the list, send an email with just "subscribe git" in
 the body to majordomo@vger.kernel.org. The mailing list archives are
 available at http://news.gmane.org/gmane.comp.version-control.git/,
@@ -50,3 +50,10 @@ The maintainer frequently sends the "What's cooking" reports that
 list the current status of various development topics to the mailing
 list.  The discussion following them give a good reference for
 project status, development direction and remaining tasks.
+
+[INSTALL]: INSTALL
+[Documentation/gittutorial.txt]: Documentation/gittutorial.txt
+[Documentation/giteveryday.txt]: Documentation/giteveryday.txt
+[Documentation/git-commandname.txt]: Documentation/git-commandname.txt
+[Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
+[Documentation/SubmittingPatches]: Documentation/SubmittingPatches
-- 
2.7.2.334.g35ed2ae.dirty

Re: [PATCH 2/5] README.md: add hyperlinks on filenames

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
>  README.md | 19 +++++++++++++------
>  1 file changed, 13 insertions(+), 6 deletions(-)

Makes sense, provided if we want to do Markdown.

If I were pushing this topic (i.e. cater to those who browse at
GitHub, not with "less" in the source tree), I'd have further made
these links to the preformatted documentation at git-scm.com; I
expected the later steps in this series to do that, but it seems you
stopped short of it for some reason.

> diff --git a/README.md b/README.md
> index 907eb3b..750fdda 100644
> --- a/README.md
> +++ b/README.md
> @@ -20,17 +20,17 @@ License version 2 (some parts of it are under different licenses,
>  compatible with the GPLv2). It was originally written by Linus
>  Torvalds with help of a group of hackers around the net.
>  
> -Please read the file INSTALL for installation instructions.
> +Please read the file [INSTALL][] for installation instructions.
>  
> -See Documentation/gittutorial.txt to get started, then see
> -Documentation/giteveryday.txt for a useful minimum set of commands, and
> -Documentation/git-commandname.txt for documentation of each command.
> +See [Documentation/gittutorial.txt][] to get started, then see
> +[Documentation/giteveryday.txt][] for a useful minimum set of commands, and
> +[Documentation/git-commandname.txt][] for documentation of each command.
>  If git has been correctly installed, then the tutorial can also be
>  read with "man gittutorial" or "git help tutorial", and the
>  documentation of each command with "man git-commandname" or "git help
>  commandname".
>  
> -CVS users may also want to read Documentation/gitcvs-migration.txt
> +CVS users may also want to read [Documentation/gitcvs-migration.txt][]
>  ("man gitcvs-migration" or "git help cvs-migration" if git is
>  installed).
>  
> @@ -40,7 +40,7 @@ including full documentation and Git related tools.
>  The user discussion and development of Git take place on the Git
>  mailing list -- everyone is welcome to post bug reports, feature
>  requests, comments and patches to git@vger.kernel.org (read
> -Documentation/SubmittingPatches for instructions on patch submission).
> +[Documentation/SubmittingPatches][] for instructions on patch submission).
>  To subscribe to the list, send an email with just "subscribe git" in
>  the body to majordomo@vger.kernel.org. The mailing list archives are
>  available at http://news.gmane.org/gmane.comp.version-control.git/,
> @@ -50,3 +50,10 @@ The maintainer frequently sends the "What's cooking" reports that
>  list the current status of various development topics to the mailing
>  list.  The discussion following them give a good reference for
>  project status, development direction and remaining tasks.
> +
> +[INSTALL]: INSTALL
> +[Documentation/gittutorial.txt]: Documentation/gittutorial.txt
> +[Documentation/giteveryday.txt]: Documentation/giteveryday.txt
> +[Documentation/git-commandname.txt]: Documentation/git-commandname.txt
> +[Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
> +[Documentation/SubmittingPatches]: Documentation/SubmittingPatches

Re: [PATCH 2/5] README.md: add hyperlinks on filenames

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> Matthieu Moy <Matthieu.Moy@imag.fr> writes:
>
>> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
>> ---
>>  README.md | 19 +++++++++++++------
>>  1 file changed, 13 insertions(+), 6 deletions(-)
>
> Makes sense, provided if we want to do Markdown.

I'd say it the other way around: declaring README as markdown costs
almost nothing and doesn't harm source code readability. This patch
slightly decreases the source's readability so we may want to drop it.

> If I were pushing this topic (i.e. cater to those who browse at
> GitHub, not with "less" in the source tree), I'd have further made
> these links to the preformatted documentation at git-scm.com; I
> expected the later steps in this series to do that, but it seems you
> stopped short of it for some reason.

I tried to keep the spirit of the README as "this is the entry point to
the source code" rather than "this is the new homepage of Git" (as some
project do on GitHub, but we have such a nice git-scm.com ...).

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

[PATCH 3/5] README.md: move the link to git-scm.com up

[Matthieu Moy]

The documentation available on git-scm.com is nicely formatted. It's
better to point users to it than to the source code of the
documentation.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 750fdda..1625352 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,9 @@ Torvalds with help of a group of hackers around the net.
 
 Please read the file [INSTALL][] for installation instructions.
 
+Many Git online resources are accessible from http://git-scm.com/
+including full documentation and Git related tools.
+
 See [Documentation/gittutorial.txt][] to get started, then see
 [Documentation/giteveryday.txt][] for a useful minimum set of commands, and
 [Documentation/git-commandname.txt][] for documentation of each command.
@@ -34,9 +37,6 @@ CVS users may also want to read [Documentation/gitcvs-migration.txt][]
 ("man gitcvs-migration" or "git help cvs-migration" if git is
 installed).
 
-Many Git online resources are accessible from http://git-scm.com/
-including full documentation and Git related tools.
-
 The user discussion and development of Git take place on the Git
 mailing list -- everyone is welcome to post bug reports, feature
 requests, comments and patches to git@vger.kernel.org (read
-- 
2.7.2.334.g35ed2ae.dirty

[PATCH 4/5] README.md: don't call git stupid in the title

[Matthieu Moy]

"the stupid content tracker" was true in the early days of Git, but
hardly applicable these days. "fast, scalable, distributed" describes
Git more accuralety.

Also, "stupid" can be seen as offensive by some people. Let's not use it
in the very first words of the README.

The new formulation is taken from the description of the Debian package.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1625352..c11c3e2 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Git - the stupid content tracker
+# Git - fast, scalable, distributed revision control system
 
 "git" can mean anything, depending on your mood.
 
-- 
2.7.2.334.g35ed2ae.dirty

Re: [PATCH 4/5] README.md: don't call git stupid in the title

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> "the stupid content tracker" was true in the early days of Git, but
> hardly applicable these days. "fast, scalable, distributed" describes
> Git more accuralety.
>
> Also, "stupid" can be seen as offensive by some people. Let's not use it
> in the very first words of the README.
>
> The new formulation is taken from the description of the Debian package.
>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---

This self-derogatory reference shouldn't offend those who didn't
help write it.

Having said that, I agree with the spirit of 4/5 and 5/5; but it is
sad that this line is not resurrected by 5/5 in some way.

>  README.md | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/README.md b/README.md
> index 1625352..c11c3e2 100644
> --- a/README.md
> +++ b/README.md
> @@ -1,4 +1,4 @@
> -# Git - the stupid content tracker
> +# Git - fast, scalable, distributed revision control system
>  
>  "git" can mean anything, depending on your mood.

Re: [PATCH 4/5] README.md: don't call git stupid in the title

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> Matthieu Moy <Matthieu.Moy@imag.fr> writes:
>
>> "the stupid content tracker" was true in the early days of Git, but
>> hardly applicable these days. "fast, scalable, distributed" describes
>> Git more accuralety.
>>
>> Also, "stupid" can be seen as offensive by some people. Let's not use it
>> in the very first words of the README.
>>
>> The new formulation is taken from the description of the Debian package.
>>
>> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
>> ---
>
> This self-derogatory reference shouldn't offend those who didn't
> help write it.
>
> Having said that, I agree with the spirit of 4/5 and 5/5; but it is
> sad that this line is not resurrected by 5/5 in some way.

Do you mean something like this:

diff --git a/README.md b/README.md
index 40de78e..b1c89bd 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,8 @@ list.  The discussion following them give a good reference for
 project status, development direction and remaining tasks.
 
 The name "git" was given by Linus Torvalds when he wrote the very
-first version. He described it as (depending on your mood):
+first version. He described the tool as "the stupid content tracker"
+and the name as (depending on your mood):
 
  - random three-letter combination that is pronounceable, and not
    actually used by any common UNIX command.  The fact that it is a

?

Why not, but I don't think it adds really much, and I'd rather keep the
README as short as possible.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH 4/5] README.md: don't call git stupid in the title

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Having said that, I agree with the spirit of 4/5 and 5/5; but it is
>> sad that this line is not resurrected by 5/5 in some way.
>
> Do you mean something like this:
>
> diff --git a/README.md b/README.md
> index 40de78e..b1c89bd 100644
> --- a/README.md
> +++ b/README.md
> @@ -41,7 +41,8 @@ list.  The discussion following them give a good reference for
>  project status, development direction and remaining tasks.
>  
>  The name "git" was given by Linus Torvalds when he wrote the very
> -first version. He described it as (depending on your mood):
> +first version. He described the tool as "the stupid content tracker"
> +and the name as (depending on your mood):

Exactly.

[PATCH 5/5] README.md: move down historical explanation about the name

[Matthieu Moy]

The explanations about why the name was chosen are secondary compared to
the description and link to the documentation.

Some consider these explanations as good computer scientists joke, but
other see it as needlessly offensive vocabulary.

This patch preserves the historical joke, but gives it less importance
by moving it to the end of the README, and makes it clear that it is a
historical explanation, that does not necessarily reflect the state of
mind of current developers.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index c11c3e2..40de78e 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,5 @@
 # Git - fast, scalable, distributed revision control system
 
-"git" can mean anything, depending on your mood.
-
- - random three-letter combination that is pronounceable, and not
-   actually used by any common UNIX command.  The fact that it is a
-   mispronunciation of "get" may or may not be relevant.
- - stupid. contemptible and despicable. simple. Take your pick from the
-   dictionary of slang.
- - "global information tracker": you're in a good mood, and it actually
-   works for you. Angels sing, and a light suddenly fills the room.
- - "goddamn idiotic truckload of sh*t": when it breaks
-
 Git is a fast, scalable, distributed revision control system with an
 unusually rich command set that provides both high-level operations
 and full access to internals.
@@ -51,6 +40,18 @@ list the current status of various development topics to the mailing
 list.  The discussion following them give a good reference for
 project status, development direction and remaining tasks.
 
+The name "git" was given by Linus Torvalds when he wrote the very
+first version. He described it as (depending on your mood):
+
+ - random three-letter combination that is pronounceable, and not
+   actually used by any common UNIX command.  The fact that it is a
+   mispronunciation of "get" may or may not be relevant.
+ - stupid. contemptible and despicable. simple. Take your pick from the
+   dictionary of slang.
+ - "global information tracker": you're in a good mood, and it actually
+   works for you. Angels sing, and a light suddenly fills the room.
+ - "goddamn idiotic truckload of sh*t": when it breaks
+
 [INSTALL]: INSTALL
 [Documentation/gittutorial.txt]: Documentation/gittutorial.txt
 [Documentation/giteveryday.txt]: Documentation/giteveryday.txt
-- 
2.7.2.334.g35ed2ae.dirty

Re: [RFC/PATCH 0/5] Make README more pleasant to read

[Jeff King]

On Tue, Feb 23, 2016 at 06:40:24PM +0100, Matthieu Moy wrote:

> This patch series was inspired by a discussion I had with Emma Jane
> after Git Merge last year. It tries both to make the README file less
> agressive and generally more pleasant to read.
> 
> To get a quick overview, compare the old one:
> 
>   https://github.com/git/git#readme
> 
> and my proposal:
> 
>   https://github.com/moy/git/tree/git-readme#readme
> 
> Matthieu Moy (5):
>   README: use markdown syntax
>   README.md: add hyperlinks on filenames
>   README.md: move the link to git-scm.com up
>   README.md: don't call git stupid in the title
>   README.md: move down historical explanation about the name

Thanks for working on this. I think the end product is much nicer on the
web, with very little downside for local viewing.

I'm especially happy about the final patch. I don't look at Git's README
often, but I always cringe when I see that intro paragraph and think
that it's some people's first introduction to what git is.

>  README => README.md | 54 ++++++++++++++++++++++++++++-------------------------
>  t/t7001-mv.sh       |  2 +-

I do not overly care, but I wonder if it would be nice to keep README as
a symlink. I don't think that complicates things for people checking out
on Windows (we already have RelNotes as a symlink, and IIRC they just
get a file with the link contents. Not helpful, but not harmful to them
either).

-Peff

Re: [RFC/PATCH 0/5] Make README more pleasant to read

[Matthieu Moy]

Jeff King <peff@peff.net> writes:

> On Tue, Feb 23, 2016 at 06:40:24PM +0100, Matthieu Moy wrote:
>
>>  README => README.md | 54 ++++++++++++++++++++++++++++-------------------------
>>  t/t7001-mv.sh       |  2 +-
>
> I do not overly care, but I wonder if it would be nice to keep README as
> a symlink.

I can add it if people want to see it, but we already have so many files
at the root, I'd rather avoid adding duplicates through symlinks.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC/PATCH 0/5] Make README more pleasant to read

[Jeff King]

On Wed, Feb 24, 2016 at 02:37:05PM +0100, Matthieu Moy wrote:

> Jeff King <peff@peff.net> writes:
> 
> > On Tue, Feb 23, 2016 at 06:40:24PM +0100, Matthieu Moy wrote:
> >
> >>  README => README.md | 54 ++++++++++++++++++++++++++++-------------------------
> >>  t/t7001-mv.sh       |  2 +-
> >
> > I do not overly care, but I wonder if it would be nice to keep README as
> > a symlink.
> 
> I can add it if people want to see it, but we already have so many files
> at the root, I'd rather avoid adding duplicates through symlinks.

That's reasonable. I thought it might appease the "I use `less README`
to view the README" crowd, but it is probably not that hard to find the
`.md` variant.

-Peff

Re: [RFC/PATCH 0/5] Make README more pleasant to read

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>> > I do not overly care, but I wonder if it would be nice to keep README as
>> > a symlink.
>> 
>> I can add it if people want to see it, but we already have so many files
>> at the root, I'd rather avoid adding duplicates through symlinks.
>
> That's reasonable. I thought it might appease the "I use `less README`
> to view the README" crowd, but it is probably not that hard to find the
> `.md` variant.

Well, "less README" folks would not be happy with a mere symbolic
link anyway--things like [INSTALL][] are pure eyesore and regression
relative to the straight text version.

I do not overly care, either.  I do not think people would complain
too much about the eyesore as long as the file is named README.md,
so in that sense, we'd be better off not having such a symbolic
link.

[PATCH v2 0/5] Make README more pleasant to read

[Matthieu Moy]

Minor tweaks after discussion on v1 (for those who missed it, this
series makes README render nicely on GitHub and tries to present
important information early).

The result is here:

  https://github.com/moy/git/tree/git-readme#readme

Changes since v1:

* Visible on the rendered page: resurect "the stupid content tracker"
  at the bottom ("He described the tool as "the stupid content
  tracker" and the name as (depending on your mood)") as suggested by
  Junio. I first disagreed, but that's part of the explanation why Git
  is called Git, so why not.

* Visible only in the source: change

  # title

  to

  title
  =====

  (I chose the first because it was more easy to type, but for someone
  not familiar with markdown, the second makes it more obvious that
  its' a title)

I kept the patch introducing explicit links on filenames. I do not
care deeply about it.

Matthieu Moy (5):
  README: use markdown syntax
  README.md: add hyperlinks on filenames
  README.md: move the link to git-scm.com up
  README.md: don't call git stupid in the title
  README.md: move down historical explanation about the name

 README => README.md | 56 +++++++++++++++++++++++++++++------------------------
 t/t7001-mv.sh       |  2 +-
 2 files changed, 32 insertions(+), 26 deletions(-)
 rename README => README.md (65%)

-- 
2.7.2.334.g35ed2ae.dirty

[PATCH v2 1/5] README: use markdown syntax

[Matthieu Moy]

This allows repository browsers like GitHub to display the content of
the file nicely formatted.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README => README.md | 7 ++-----
 t/t7001-mv.sh       | 2 +-
 2 files changed, 3 insertions(+), 6 deletions(-)
 rename README => README.md (93%)

diff --git a/README b/README.md
similarity index 93%
rename from README
rename to README.md
index 1083735..600779c 100644
--- a/README
+++ b/README.md
@@ -1,8 +1,5 @@
-////////////////////////////////////////////////////////////////
-
-	Git - the stupid content tracker
-
-////////////////////////////////////////////////////////////////
+Git - the stupid content tracker
+================================
 
 "git" can mean anything, depending on your mood.
 
diff --git a/t/t7001-mv.sh b/t/t7001-mv.sh
index 51dd2b4..4008fae 100755
--- a/t/t7001-mv.sh
+++ b/t/t7001-mv.sh
@@ -102,7 +102,7 @@ test_expect_success \
 
 test_expect_success \
     'adding another file' \
-    'cp "$TEST_DIRECTORY"/../README path0/README &&
+    'cp "$TEST_DIRECTORY"/../README.md path0/README &&
      git add path0/README &&
      git commit -m add2 -a'
 
-- 
2.7.2.334.g35ed2ae.dirty

[PATCH v2 2/5] README.md: add hyperlinks on filenames

[Matthieu Moy]

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 600779c..e54f9e7 100644
--- a/README.md
+++ b/README.md
@@ -21,17 +21,17 @@ License version 2 (some parts of it are under different licenses,
 compatible with the GPLv2). It was originally written by Linus
 Torvalds with help of a group of hackers around the net.
 
-Please read the file INSTALL for installation instructions.
+Please read the file [INSTALL][] for installation instructions.
 
-See Documentation/gittutorial.txt to get started, then see
-Documentation/giteveryday.txt for a useful minimum set of commands, and
-Documentation/git-commandname.txt for documentation of each command.
+See [Documentation/gittutorial.txt][] to get started, then see
+[Documentation/giteveryday.txt][] for a useful minimum set of commands, and
+[Documentation/git-commandname.txt][] for documentation of each command.
 If git has been correctly installed, then the tutorial can also be
 read with "man gittutorial" or "git help tutorial", and the
 documentation of each command with "man git-commandname" or "git help
 commandname".
 
-CVS users may also want to read Documentation/gitcvs-migration.txt
+CVS users may also want to read [Documentation/gitcvs-migration.txt][]
 ("man gitcvs-migration" or "git help cvs-migration" if git is
 installed).
 
@@ -41,7 +41,7 @@ including full documentation and Git related tools.
 The user discussion and development of Git take place on the Git
 mailing list -- everyone is welcome to post bug reports, feature
 requests, comments and patches to git@vger.kernel.org (read
-Documentation/SubmittingPatches for instructions on patch submission).
+[Documentation/SubmittingPatches][] for instructions on patch submission).
 To subscribe to the list, send an email with just "subscribe git" in
 the body to majordomo@vger.kernel.org. The mailing list archives are
 available at http://news.gmane.org/gmane.comp.version-control.git/,
@@ -51,3 +51,10 @@ The maintainer frequently sends the "What's cooking" reports that
 list the current status of various development topics to the mailing
 list.  The discussion following them give a good reference for
 project status, development direction and remaining tasks.
+
+[INSTALL]: INSTALL
+[Documentation/gittutorial.txt]: Documentation/gittutorial.txt
+[Documentation/giteveryday.txt]: Documentation/giteveryday.txt
+[Documentation/git-commandname.txt]: Documentation/git-commandname.txt
+[Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
+[Documentation/SubmittingPatches]: Documentation/SubmittingPatches
-- 
2.7.2.334.g35ed2ae.dirty

[PATCH v2 3/5] README.md: move the link to git-scm.com up

[Matthieu Moy]

The documentation available on git-scm.com is nicely formatted. It's
better to point users to it than to the source code of the
documentation.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e54f9e7..5500f8a 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,9 @@ Torvalds with help of a group of hackers around the net.
 
 Please read the file [INSTALL][] for installation instructions.
 
+Many Git online resources are accessible from http://git-scm.com/
+including full documentation and Git related tools.
+
 See [Documentation/gittutorial.txt][] to get started, then see
 [Documentation/giteveryday.txt][] for a useful minimum set of commands, and
 [Documentation/git-commandname.txt][] for documentation of each command.
@@ -35,9 +38,6 @@ CVS users may also want to read [Documentation/gitcvs-migration.txt][]
 ("man gitcvs-migration" or "git help cvs-migration" if git is
 installed).
 
-Many Git online resources are accessible from http://git-scm.com/
-including full documentation and Git related tools.
-
 The user discussion and development of Git take place on the Git
 mailing list -- everyone is welcome to post bug reports, feature
 requests, comments and patches to git@vger.kernel.org (read
-- 
2.7.2.334.g35ed2ae.dirty

[PATCH v2 4/5] README.md: don't call git stupid in the title

[Matthieu Moy]

"the stupid content tracker" was true in the early days of Git, but
hardly applicable these days. "fast, scalable, distributed" describes
Git more accuralety.

Also, "stupid" can be seen as offensive by some people. Let's not use it
in the very first words of the README.

The new formulation is taken from the description of the Debian package.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5500f8a..e3ddc3e 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-Git - the stupid content tracker
-================================
+Git - fast, scalable, distributed revision control system
+=========================================================
 
 "git" can mean anything, depending on your mood.
 
-- 
2.7.2.334.g35ed2ae.dirty

[PATCH v2 5/5] README.md: move down historical explanation about the name

[Matthieu Moy]

The explanations about why the name was chosen are secondary compared to
the description and link to the documentation.

Some consider these explanations as good computer scientists joke, but
other see it as needlessly offensive vocabulary.

This patch preserves the historical joke, but gives it less importance
by moving it to the end of the README, and makes it clear that it is a
historical explanation, that does not necessarily reflect the state of
mind of current developers.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index e3ddc3e..d1ffbb6 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,6 @@
 Git - fast, scalable, distributed revision control system
 =========================================================
 
-"git" can mean anything, depending on your mood.
-
- - random three-letter combination that is pronounceable, and not
-   actually used by any common UNIX command.  The fact that it is a
-   mispronunciation of "get" may or may not be relevant.
- - stupid. contemptible and despicable. simple. Take your pick from the
-   dictionary of slang.
- - "global information tracker": you're in a good mood, and it actually
-   works for you. Angels sing, and a light suddenly fills the room.
- - "goddamn idiotic truckload of sh*t": when it breaks
-
 Git is a fast, scalable, distributed revision control system with an
 unusually rich command set that provides both high-level operations
 and full access to internals.
@@ -52,6 +41,19 @@ list the current status of various development topics to the mailing
 list.  The discussion following them give a good reference for
 project status, development direction and remaining tasks.
 
+The name "git" was given by Linus Torvalds when he wrote the very
+first version. He described the tool as "the stupid content tracker"
+and the name as (depending on your mood):
+
+ - random three-letter combination that is pronounceable, and not
+   actually used by any common UNIX command.  The fact that it is a
+   mispronunciation of "get" may or may not be relevant.
+ - stupid. contemptible and despicable. simple. Take your pick from the
+   dictionary of slang.
+ - "global information tracker": you're in a good mood, and it actually
+   works for you. Angels sing, and a light suddenly fills the room.
+ - "goddamn idiotic truckload of sh*t": when it breaks
+
 [INSTALL]: INSTALL
 [Documentation/gittutorial.txt]: Documentation/gittutorial.txt
 [Documentation/giteveryday.txt]: Documentation/giteveryday.txt
-- 
2.7.2.334.g35ed2ae.dirty