On 16/01/2022 22:47, Junio C Hamano wrote: > "Philip Oakley via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > >> From: Philip Oakley <philipoakley@iee.email> >> >> The README.md does not use the GitHub Markdown URL links [1] of >> [txt](url), rather the reference method [2] of trailing empty square >> brackets. The references themselves are listed at the foot of the >> document. Those footers are not shown by GitHub/GitLab rendering. > Thanks for tracking down the differences. I found an additional GitHub link for the reference method (not easy to find), which I have added. > > The above only describes what we could do (i.e. use links instead of > reference), and how the current document is rendered (i.e. footers > are not shown). No changes come from the above description. > >> Also space out the list joining instructions and clarify that >> subscription is via the majordomo address. > So, seeing "Also" immediately after a paragraph that explains the > status quo confused me a lot. > > "Spell out the instructions to join the list, and clarify that the > subscription is via the majordomo address" is indeed a part of what > this patch does. Perhaps we need a separate paragraph _before_ this > "Also". > > So taking all together > > Before being told how to submit patches, new contributors need > to be told how to code for, or how to contribute translation to, > the project. Add references to the CodingGuidelines and the > README document on localization. > > Also, spell out the instructions to join the list and ... > > We use GitHub Markdown reference [2] with trailing empty square > brackets, to match existing text in the file. On GitHub/GitLab > pages, these references are not shown on the page, but it is OK > because they are empty. We could switch to using [text](url) > form [1] if we wanted to, but that is not done as part of this > patch. > > would be the presentation order that I would expect to be the most > readable. I moved the discussion between URL link and reference, as > it is merely a hint for future and not the core thing that needs to > be explained to understand the changes in this commit. I've taken your suggestions and added a small clarification about the awkward empty square bracket links, which are repeated in the README's footer, but not shown on the Github rendered web page.. I also took Bagas' text changes for the readme itself GGG V3 to follow,... Thank you > > Thanks. > > >> [1] https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links >> [2] https://gist.github.com/ChrisTollefson/a3af6d902a74a0afd1c2d79aadc9bb3f#reference-links >> >> Signed-off-by: Philip Oakley <philipoakley@iee.email> >> --- >> README.md: add CodingGuidelines and a link for Translators >> >> Also space out the list joining instructions and clarify the >> subscription via the majordomo address. >> >> >> Signed-off-by: Philip Oakley philipoakley@iee.email >> =================================================== >> >> cc: Philip Oakley philipoakley@iee.email cc: Junio C Hamano >> gitster@xxxxxxxxx cc: Jiang Xin worldhello.net@xxxxxxxxx >> >> changes since v1: >> >> * Used reference style links, rather than lnk [url] style. >> >> * added Jianf as L10 coordinator. >> >> * note: Patch is a response to a user question on the "Git for Human >> Beings" git-users list >> https://groups.google.com/d/msgid/git-users/aa68b9c8-4cf4-4193-8af3-79d7e3feafbbn%40googlegroups.com >> >> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1115%2FPhilipOakley%2FReadme-v2 >> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1115/PhilipOakley/Readme-v2 >> Pull-Request: https://github.com/gitgitgadget/git/pull/1115 >> >> Range-diff vs v1: >> >> 1: ac6d0abbdde ! 1: 48cc30b7cc8 README.md: add CodingGuidelines and a link for Translators >> @@ Metadata >> ## Commit message ## >> README.md: add CodingGuidelines and a link for Translators >> >> - Also space out the list joining instructions and clarify the subscription >> - via the majordomo address. >> + The README.md does not use the GitHub Markdown URL links [1] of >> + [txt](url), rather the reference method [2] of trailing empty square >> + brackets. The references themselves are listed at the foot of the >> + document. Those footers are not shown by GitHub/GitLab rendering. >> + >> + Also space out the list joining instructions and clarify that >> + subscription is via the majordomo address. >> + >> + [1] https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links >> + [2] https://gist.github.com/ChrisTollefson/a3af6d902a74a0afd1c2d79aadc9bb3f#reference-links >> >> Signed-off-by: Philip Oakley <philipoakley@iee.email> >> >> @@ README.md: installed). >> requests, comments and patches to git@xxxxxxxxxxxxxxx (read >> -[Documentation/SubmittingPatches][] for instructions on patch submission). >> +[Documentation/SubmittingPatches][] for instructions on patch submission >> -+and [Documentation/CodingGuidelines]() ). >> ++and [Documentation/CodingGuidelines][]). >> + >> +Those wishing to help with error message translation (localization L10) >> -+should see [po/README.md]() >> -+(a `po` file is a portable object file for the translations). >> ++should see [po/README.md][] (a `po` file is a Portable Object file that >> ++holds the translations). >> + >> To subscribe to the list, send an email with just "subscribe git" in >> -the body to majordomo@xxxxxxxxxxxxxxx. The mailing list archives are >> -available at <https://lore.kernel.org/git/>, >> -+the body to majordomo@xxxxxxxxxxxxxxx (not the list). The mailing list >> -+archives are available at <https://lore.kernel.org/git/>, >> ++the body to majordomo@xxxxxxxxxxxxxxx (not the Git list). The mailing >> ++list archives are available at <https://lore.kernel.org/git/>, >> <http://marc.info/?l=git> and other archival sites. >> >> Issues which are security relevant should be disclosed privately to >> +@@ README.md: and the name as (depending on your mood): >> + [Documentation/giteveryday.txt]: Documentation/giteveryday.txt >> + [Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt >> + [Documentation/SubmittingPatches]: Documentation/SubmittingPatches >> ++[Documentation/CodingGuidelines]: Documentation/CodingGuidelines >> ++[po/README.md]: po/README.md >> + \ No newline at end of file >> >> >> README.md | 14 +++++++++++--- >> 1 file changed, 11 insertions(+), 3 deletions(-) >> >> diff --git a/README.md b/README.md >> index f6f43e78deb..d2b061e3998 100644 >> --- a/README.md >> +++ b/README.md >> @@ -32,10 +32,16 @@ installed). >> 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@xxxxxxxxxxxxxxx (read >> -[Documentation/SubmittingPatches][] for instructions on patch submission). >> +[Documentation/SubmittingPatches][] for instructions on patch submission >> +and [Documentation/CodingGuidelines][]). >> + >> +Those wishing to help with error message translation (localization L10) >> +should see [po/README.md][] (a `po` file is a Portable Object file that >> +holds the translations). >> + >> To subscribe to the list, send an email with just "subscribe git" in >> -the body to majordomo@xxxxxxxxxxxxxxx. The mailing list archives are >> -available at <https://lore.kernel.org/git/>, >> +the body to majordomo@xxxxxxxxxxxxxxx (not the Git list). The mailing >> +list archives are available at <https://lore.kernel.org/git/>, >> <http://marc.info/?l=git> and other archival sites. >> >> Issues which are security relevant should be disclosed privately to >> @@ -64,3 +70,5 @@ and the name as (depending on your mood): >> [Documentation/giteveryday.txt]: Documentation/giteveryday.txt >> [Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt >> [Documentation/SubmittingPatches]: Documentation/SubmittingPatches >> +[Documentation/CodingGuidelines]: Documentation/CodingGuidelines >> +[po/README.md]: po/README.md >> \ No newline at end of file >> >> base-commit: 1ffcbaa1a5f10c9f706314d77f88de20a4a498c2
