threads / patch / 41486

patch, 5 partsREADME: use markdown syntax

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

## tl;dr

25 messages between Feb 23, 2016 and Feb 25, 2016. Diffs are folded; open one to read it.

replies: 24people: 5as markdown or json

Matthieu Moy· Feb 23, 2016, 17:40 UTC · lore

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

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
Matthieu Moy· Feb 23, 2016, 17:40 UTC · re: Matthieu Moy · lore

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%)
Show changes to 3 files +2 −6

README, README.md, t/t7001-mv.sh

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
Junio C Hamano· Feb 23, 2016, 19:07 UTC · re: Matthieu Moy · lore

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

Matthieu Moy <Matthieu.Moy@imag.fr> writes:
Show 5 quoted lines
> 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.

Show 34 quoted lines
>  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'
Matthieu Moy· Feb 23, 2016, 19:50 UTC · re: Junio C Hamano · lore

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

Junio C Hamano <gitster@pobox.com> writes:
Show 14 quoted lines
> 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:

Show 9 quoted lines
>> --- 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/
Johannes Schindelin· Feb 24, 2016, 07:08 UTC · re: Junio C Hamano · lore

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

Hi Junio,
On Tue, 23 Feb 2016, Junio C Hamano wrote:
Show 14 quoted lines
> 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.

Jeff King· Feb 24, 2016, 10:18 UTC · re: Johannes Schindelin · lore

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

On Wed, Feb 24, 2016 at 08:08:52AM +0100, Johannes Schindelin wrote:
Show 15 quoted lines
> > 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
Matthieu Moy· Feb 23, 2016, 17:40 UTC · re: Matthieu Moy · lore

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

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)
Show changes to README.md +13 −6
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
Junio C Hamano· Feb 23, 2016, 19:10 UTC · re: Matthieu Moy · lore

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

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.

Show 47 quoted lines
> 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
Matthieu Moy· Feb 23, 2016, 19:52 UTC · re: Junio C Hamano · lore

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

Junio C Hamano <gitster@pobox.com> writes:
Show 8 quoted lines
> 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.

Show 5 quoted lines
> 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/
Matthieu Moy· Feb 23, 2016, 17:40 UTC · re: Matthieu Moy · lore

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

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(-)
Show changes to README.md +3 −3
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
Matthieu Moy· Feb 23, 2016, 17:40 UTC · re: Matthieu Moy · lore

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

"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(-)
Show changes to README.md +1 −1
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
Junio C Hamano· Feb 23, 2016, 19:13 UTC · re: Matthieu Moy · lore

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

Matthieu Moy <Matthieu.Moy@imag.fr> writes:
Show 11 quoted lines
> "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.

Show 12 quoted lines
>  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.
Matthieu Moy· Feb 23, 2016, 20:51 UTC · re: Junio C Hamano · lore

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

Junio C Hamano <gitster@pobox.com> writes:
Show 19 quoted lines
> 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:
Show changes to README.md +2 −1
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/
Junio C Hamano· Feb 23, 2016, 21:37 UTC · re: Matthieu Moy · lore

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

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
Show 18 quoted lines
> 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.
Matthieu Moy· Feb 23, 2016, 17:40 UTC · re: Matthieu Moy · lore

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

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(-)
Show changes to README.md +12 −11
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
Jeff King· Feb 24, 2016, 10:22 UTC · re: Matthieu Moy · lore

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

On Tue, Feb 23, 2016 at 06:40:24PM +0100, Matthieu Moy wrote:
Show 18 quoted lines
> 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
Matthieu Moy· Feb 24, 2016, 13:37 UTC · re: Jeff King · lore

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

Jeff King <peff@peff.net> writes:
Show 7 quoted lines
> 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/
Jeff King· Feb 25, 2016, 06:14 UTC · re: Matthieu Moy · lore

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

On Wed, Feb 24, 2016 at 02:37:05PM +0100, Matthieu Moy wrote:
Show 12 quoted lines
> 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
Junio C Hamano· Feb 25, 2016, 06:22 UTC · re: Jeff King · lore

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

Jeff King <peff@peff.net> writes:
Show 9 quoted lines
>> > 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.

Matthieu Moy· Feb 25, 2016, 08:37 UTC · re: Matthieu Moy · lore

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

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
Matthieu Moy· Feb 25, 2016, 08:37 UTC · re: Matthieu Moy · lore

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

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%)
Show changes to 3 files +3 −6

README, README.md, t/t7001-mv.sh

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
Matthieu Moy· Feb 25, 2016, 08:37 UTC · re: Matthieu Moy · lore

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

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 README.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)
Show changes to README.md +13 −6
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
Matthieu Moy· Feb 25, 2016, 08:37 UTC · re: Matthieu Moy · lore

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

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(-)
Show changes to README.md +3 −3
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
Matthieu Moy· Feb 25, 2016, 08:37 UTC · re: Matthieu Moy · lore

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

"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(-)
Show changes to README.md +2 −2
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
Matthieu Moy· Feb 25, 2016, 08:37 UTC · re: Matthieu Moy · lore

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

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(-)
Show changes to README.md +13 −11
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

← back to recent threads