| Message ID | pull.1115.git.1642182615339.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | README.md: add CodingGuidelines and a link for Translators | expand |
"Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Philip Oakley <philipoakley@iee.email> > > Also space out the list joining instructions and clarify the subscription the instructions to join the list? > requests, comments and patches to git@vger.kernel.org (read > -[Documentation/SubmittingPatches][] for instructions on patch submission). > +[Documentation/SubmittingPatches][] for instructions on patch submission > +and [Documentation/CodingGuidelines]() ). Remind me the significance of using [] and () after [File Reference]? > +Those wishing to help with error message translation (localization L10) > +should see [po/README.md]() Same here. https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links seems to indicate () is to enclose URL the text goes to, and if there is no URL to go to, perhaps it does the right thing, but the current page (which has "[Documentation/SubmittingPatches][]" and all other reference into in-tree files with that format) seems to render correctly with links that work, so... > +(a `po` file is a portable object file for the translations). > + > 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 <https://lore.kernel.org/git/>, > +the body to majordomo@vger.kernel.org (not the 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 > > base-commit: 1ffcbaa1a5f10c9f706314d77f88de20a4a498c2
On 14/01/2022 20:54, Junio C Hamano wrote: > "Philip Oakley via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> From: Philip Oakley <philipoakley@iee.email> >> >> Also space out the list joining instructions and clarify the subscription > the instructions to join the list? Correct. > >> requests, comments and patches to git@vger.kernel.org (read >> -[Documentation/SubmittingPatches][] for instructions on patch submission). >> +[Documentation/SubmittingPatches][] for instructions on patch submission >> +and [Documentation/CodingGuidelines]() ). > Remind me the significance of using [] and () after [File Reference]? The [] is the original method used by the unchanged text, while the () appears to be the method required now. > >> +Those wishing to help with error message translation (localization L10) >> +should see [po/README.md]() > Same here. > > https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links > > seems to indicate () is to enclose URL the text goes to, and if > there is no URL to go to, perhaps it does the right thing, but the > current page (which has "[Documentation/SubmittingPatches][]" and > all other reference into in-tree files with that format) seems to > render correctly with links that work, so... Unfortunately it `[]` is not working for me for the new additions. GitHub magic? > >> +(a `po` file is a portable object file for the translations). >> + >> 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 <https://lore.kernel.org/git/>, >> +the body to majordomo@vger.kernel.org (not the 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 >> >> base-commit: 1ffcbaa1a5f10c9f706314d77f88de20a4a498c2
Philip Oakley <philipoakley@iee.email> writes: > Unfortunately it `[]` is not working for me for the new additions. > GitHub magic? Let's step back a bit. Is there somebody reading README.md as a more generic MarkDown? I do not think our build procedure creates any rendered document from it. My recollection was that we moved from README.txt to README.md for the sole purpose of showing it https://github.com/git/git/ as more than just a plain text, so it is a hard requirement that GitHub flavored MarkDown renderer is happy with whatever we write in the file. If GitHub flavored MarkDown only supports [] and breaks with (), then there is no need for further discussion. We must stick to [] that has been working for us in the file. On the other hand, if both () and [] work well at GitHub, I am OK to replace [] to (), so that it shows well at GitHub and also it can be used with other MarkDown renderers. I prefer, from the organizational point of view, to see two patches, in this order, if we were to go that way. [PATCH 1/2] README: link to more contributor documents which uses [] (not ()). After this, README.md uses only [], including the two links you add in this step. And then [PATCH 2/2] README: use "()", not "[]", to please more MarkDown processors which replaces all uses of [] with (). That would allow us to queue both, try them out, and we can back out [2/2] if GitHub's renderer does not like the result.
diff --git a/README.md b/README.md index f6f43e78deb..5c956dea6e0 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@vger.kernel.org (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 for the translations). + 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 <https://lore.kernel.org/git/>, +the body to majordomo@vger.kernel.org (not the 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