| Message ID | 3c475a2ee4ecfb79a1174fa693b592ebafdbf5f9.1722801936.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: git diff reformatting | expand |
Am 04.08.24 um 22:05 schrieb Jean-Noël Avila via GitGitGadget: > @@ -134,17 +135,18 @@ or like this (when the `--cc` option is used): > > 2. It is followed by one or more extended header lines > (this example shows a merge with two parents): > - > - index <hash>,<hash>..<hash> > - mode <mode>,<mode>..<mode> > - new file mode <mode> > - deleted file mode <mode>,<mode> > + > -The `mode <mode>,<mode>..<mode>` line appears only if at least one of > -the <mode> is different from the rest. Extended headers with > +[synopsis] > +index <hash>,<hash>`..`<hash> > +mode <mode>,<mode>`..`<mode> > +new file mode <mode> > +deleted file mode <mode>,<mode> > ++ > +The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if at least one of > +the _<mode>_ is different from the rest. Extended headers with I've a strong aversion to the formatting that this series applies, because it introduces many (IMHO) unnecessary punctuation that vandalizes the perfectly readable plain text. And this hunk now shows where it goes too far. These lines under the new [synopsis] header just aren't syopsis; they are comamnd output. The updated version abuses a semantic token to achieve syntactic highlighting. To me this series looks too much like "we must adapt to the tool" when the correct stance should be "the tool must adapt to us". If the tool (one of asciidoc and asciidoctor, I presume) does not cooperate well with out documents, then it is the tool that must be changed, not our documents. I understand that some compromises are needed, but with this extent of changes we give in to a sub-par tool too far. Just my 2c. -- Hannes
Johannes Sixt <j6t@kdbg.org> writes: > I've a strong aversion to the formatting that this series applies, > because it introduces many (IMHO) unnecessary punctuation that > vandalizes the perfectly readable plain text. And this hunk now shows > where it goes too far. These lines under the new [synopsis] header just > aren't syopsis; they are comamnd output. The updated version abuses a > semantic token to achieve syntactic highlighting. > > To me this series looks too much like "we must adapt to the tool" when > the correct stance should be "the tool must adapt to us". If the tool > (one of asciidoc and asciidoctor, I presume) does not cooperate well > with out documents, then it is the tool that must be changed, not our > documents. > > I understand that some compromises are needed, but with this extent of > changes we give in to a sub-par tool too far. Thanks for placing this into words a lot better than how I could have done. I share the same feeling.
On Monday, 5 August 2024 07:53:19 CEST Johannes Sixt wrote: > Am 04.08.24 um 22:05 schrieb Jean-Noël Avila via GitGitGadget: > > @@ -134,17 +135,18 @@ or like this (when the `--cc` option is used): > > > > 2. It is followed by one or more extended header lines > > (this example shows a merge with two parents): > > - > > - index <hash>,<hash>..<hash> > > - mode <mode>,<mode>..<mode> > > - new file mode <mode> > > - deleted file mode <mode>,<mode> > > + > > -The `mode <mode>,<mode>..<mode>` line appears only if at least one of > > -the <mode> is different from the rest. Extended headers with > > +[synopsis] > > +index <hash>,<hash>`..`<hash> > > +mode <mode>,<mode>`..`<mode> > > +new file mode <mode> > > +deleted file mode <mode>,<mode> > > ++ > > +The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if at least one of > > +the _<mode>_ is different from the rest. Extended headers with > > I've a strong aversion to the formatting that this series applies, > because it introduces many (IMHO) unnecessary punctuation that > vandalizes the perfectly readable plain text. And this hunk now shows > where it goes too far. These lines under the new [synopsis] header just > aren't syopsis; they are comamnd output. The updated version abuses a > semantic token to achieve syntactic highlighting. > > To me this series looks too much like "we must adapt to the tool" when > the correct stance should be "the tool must adapt to us". If the tool > (one of asciidoc and asciidoctor, I presume) does not cooperate well > with out documents, then it is the tool that must be changed, not our > documents. > > I understand that some compromises are needed, but with this extent of > changes we give in to a sub-par tool too far. > > Just my 2c. > > -- Hannes > > Hello, I was half expecting this kind of reactions. First there are some remarks on your remarks. * You think the markup is unnecessary. To me, it is critical in order to make the documentation output a little more meaningful. My experience as a translator is that there's a great lack of consistency in the vocabulary, the grammar styles, the typesetting and the cross-references of the pages. On top of that, they are clearly not user-oriented. Overall, the joke about how cryptic the man-pages of Git are is not coming from nowhere. There's no one to blame: we are all developers doing our best, but we are not technical writers dedicated to this project. * The fact that the source of the pages should be "perfectly readable" is a moot argument. Fair enough, it is not the objective to make it impossible to understand, but in the end, this is not what is consumed: these pages are compiled into other formats where the markup has been translated into styling. I suspect some writers are not thinking when quoting text, that this is not a quotation but an inline formatting command. But this is markup, and sometimes, it cannot be removed of the way. * I converted the lines to synopsis because there are placeholders in them. These lines are presented as an example but they are neither. This is another example of communication impedance, where the presented text is not what it is described as, and requires from the reader to interpret what the writer was thinking and forgot to make clear to a newcomer. As for the "need to adapt to the tool", for block formatting, I tried to get something bearable (the synopis style); I'd really like something similar for inline formatting but my asciidoc/asciidoctor Fu requires an upgrade in order to make it happen. As it seems to be too epidermic, I'll try to cook something anyway and keep being open to any proposition. In the mean time, a proper editor setup (syntax highlighting and fontification , two panels with one showing the compiled output) can alleviate your pain. JN
On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote: > Johannes Sixt <j6t@kdbg.org> writes: > > > I've a strong aversion to the formatting that this series applies, > > because it introduces many (IMHO) unnecessary punctuation that > > vandalizes the perfectly readable plain text. And this hunk now shows > > where it goes too far. These lines under the new [synopsis] header just > > aren't syopsis; they are comamnd output. The updated version abuses a > > semantic token to achieve syntactic highlighting. > > > > To me this series looks too much like "we must adapt to the tool" when > > the correct stance should be "the tool must adapt to us". If the tool > > (one of asciidoc and asciidoctor, I presume) does not cooperate well > > with out documents, then it is the tool that must be changed, not our > > documents. > > > > I understand that some compromises are needed, but with this extent of > > changes we give in to a sub-par tool too far. > > Thanks for placing this into words a lot better than how I could > have done. I share the same feeling. > I'm working on a form of macro that would work almost the same way as the synopsis paragraph. You would have some markup, but it would be surrounding the text to typeset: s:["--ignore-matching-lines=<regex>"] In this snippet the macro part (which is recognized by a regex) is s:[ ] The inside part is managed the same. If you need additional markup, it is possible: s:["<commit1>`...`<commit2>"] to have the three dots rendered as <code>, because they are part of the tokens. Square brackets are possible inside the double-quotes: s:["--ignore-submodules[=<when>]"] Is this something that wouldn't repel you? Best regards, JN
Am 07.08.24 um 22:43 schrieb Jean-Noël AVILA: > On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote: >> Johannes Sixt <j6t@kdbg.org> writes: >> >>> I've a strong aversion to the formatting that this series applies, >>> because it introduces many (IMHO) unnecessary punctuation that >>> vandalizes the perfectly readable plain text. And this hunk now shows >>> where it goes too far. These lines under the new [synopsis] header just >>> aren't syopsis; they are comamnd output. The updated version abuses a >>> semantic token to achieve syntactic highlighting. >>> >>> To me this series looks too much like "we must adapt to the tool" when >>> the correct stance should be "the tool must adapt to us". If the tool >>> (one of asciidoc and asciidoctor, I presume) does not cooperate well >>> with out documents, then it is the tool that must be changed, not our >>> documents. >>> >>> I understand that some compromises are needed, but with this extent of >>> changes we give in to a sub-par tool too far. >> >> Thanks for placing this into words a lot better than how I could >> have done. I share the same feeling. >> > > I'm working on a form of macro that would work almost the same way as the > synopsis paragraph. You would have some markup, but it would be surrounding > the text to typeset: > > s:["--ignore-matching-lines=<regex>"] > > In this snippet the macro part (which is recognized by a regex) is s:[ ] > The inside part is managed the same. If you need additional markup, it is > possible: > > s:["<commit1>`...`<commit2>"] to have the three dots rendered as <code>, > because they are part of the tokens. > > Square brackets are possible inside the double-quotes: > s:["--ignore-submodules[=<when>]"] > > Is this something that wouldn't repel you? You argued elsewhere in this thread: > * The fact that the source of the pages should be "perfectly readable" is a > moot argument. Fair enough, it is not the objective to make it impossible to > understand, but in the end, this is not what is consumed: these pages are > compiled into other formats where the markup has been translated into styling. I buy this argument, in particular, since not even I read the plain text files, but use the rendered version. I would like tone down my harsh opposition to mild opposition. IMO, it should still be easy to *write* the documentation. It should not be necessary that authors remember to use macros all over the place. And I still think that we should not introduce macros just to please all renderers. Let's just pick the one renderer that can do the job best. If it means that some distribution cannot render the documentation perfectly themselves (Debian? I don't know), they can always use the pre-rendered version that Junio kindly produces. -- Hannes
Johannes Sixt <j6t@kdbg.org> writes: >> Square brackets are possible inside the double-quotes: >> s:["--ignore-submodules[=<when>]"] >> >> Is this something that wouldn't repel you? > > You argued elsewhere in this thread: > >> * The fact that the source of the pages should be "perfectly readable" is a >> moot argument. Fair enough, it is not the objective to make it impossible to >> understand, but in the end, this is not what is consumed: these pages are >> compiled into other formats where the markup has been translated into styling. > > I buy this argument, in particular, since not even I read the plain text > files, but use the rendered version. FWIW, I do read the plain text files, and rarely if ever use the HTML version, except when checking the effect of changes to the mark-up. > I would like tone down my harsh opposition to mild opposition. IMO, it > should still be easy to *write* the documentation. It should not be > necessary that authors remember to use macros all over the place. Yeah, s:[...] does repel me, but also I do not think it is sensible to claim that we confortably edit the "source" form that we find it hard to read. > And I still think that we should not introduce macros just to please all > renderers. Let's just pick the one renderer that can do the job best. If > it means that some distribution cannot render the documentation > perfectly themselves (Debian? I don't know), they can always use the > pre-rendered version that Junio kindly produces. What Junio uses "Debian? I don't know" that cannot render the documentation ;-)?
On Monday, 12 August 2024 08:35:39 CEST Johannes Sixt wrote: > Am 07.08.24 um 22:43 schrieb Jean-Noël AVILA: > > I would like tone down my harsh opposition to mild opposition. IMO, it > should still be easy to *write* the documentation. It should not be > necessary that authors remember to use macros all over the place. The purpose of this series is to clarify the formatting rules for keywords and placeholders, and to uniformly apply them, so that the readers can relate the meaning of what they are reading with the visual cues in the text. The more uniform the typesetting, the less surprised the reader, the smaller the communication impedance. This requirement makes the documentation *less* easy to write, for sure. It is no question of forcing authors to use the formatting macro everywhere. As explained in the Guildelines V3 of the series, the macro is introduced in order to remove the most hairy forms where manually doing the formatting would lead to difficult to read/write sequences. I bet most writers will remember and use the s macro when they want to typeset something like --ignore-submodules[=<when>] As an added benefit, we can also simplify some existing parts, for instance see the ones in urls.txt. > > And I still think that we should not introduce macros just to please all > renderers. Let's just pick the one renderer that can do the job best. If > it means that some distribution cannot render the documentation > perfectly themselves (Debian? I don't know), they can always use the > pre-rendered version that Junio kindly produces. I do not understand how the renderer could solve the issue of typesetting the "good part" in the place of the writers. The macro is there to mechanize the typesetting of selected parts, but it is up to the writers to define what is a keyword and what is a placeholder in their prose. Please note also that using proper placeholder differentiating and typesetting should have the side-effect of making the prose lighter, by removing the need to express which placeholder we are talking about. To me, Asciidoc strikes a good balance for a tool that makes it easy to write simple things and not too complicated to write more complex ones. It is also customizable for specific needs, which is handy for our use case. I am not aware of an existing renderer that would do the job really best. What do you have in mind? JN
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 4b5aa5c2e04..0a4dc761e64 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -14,7 +14,7 @@ You can customize the creation of patch text via the `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables (see linkgit:git[1]), and the `diff` attribute (see linkgit:gitattributes[5]). -What the -p option produces is slightly different from the traditional +What the `-p` option produces is slightly different from the traditional diff format: 1. It is preceded by a "git diff" header that looks like this: @@ -30,20 +30,21 @@ name of the source file of the rename/copy and the name of the file that the rename/copy produces, respectively. 2. It is followed by one or more extended header lines: - - old mode <mode> - new mode <mode> - deleted file mode <mode> - new file mode <mode> - copy from <path> - copy to <path> - rename from <path> - rename to <path> - similarity index <number> - dissimilarity index <number> - index <hash>..<hash> <mode> + -File modes are printed as 6-digit octal numbers including the file type +[synopsis] +old mode <mode> +new mode <mode> +deleted file mode <mode> +new file mode <mode> +copy from <path> +copy to <path> +rename from <path> +rename to <path> +similarity index <number> +dissimilarity index <number> +index <hash>..<hash> <mode> ++ +File modes _<mode>_ are printed as 6-digit octal numbers including the file type and file permission bits. + Path names in extended headers do not include the `a/` and `b/` prefixes. @@ -56,7 +57,7 @@ files, while 100% dissimilarity means that no line from the old file made it into the new one. + The index line includes the blob object names before and after the change. -The <mode> is included if the file mode does not change; otherwise, +The _<mode>_ is included if the file mode does not change; otherwise, separate lines indicate the old and the new mode. 3. Pathnames with "unusual" characters are quoted as explained for @@ -134,17 +135,18 @@ or like this (when the `--cc` option is used): 2. It is followed by one or more extended header lines (this example shows a merge with two parents): - - index <hash>,<hash>..<hash> - mode <mode>,<mode>..<mode> - new file mode <mode> - deleted file mode <mode>,<mode> + -The `mode <mode>,<mode>..<mode>` line appears only if at least one of -the <mode> is different from the rest. Extended headers with +[synopsis] +index <hash>,<hash>`..`<hash> +mode <mode>,<mode>`..`<mode> +new file mode <mode> +deleted file mode <mode>,<mode> ++ +The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if at least one of +the _<mode>_ is different from the rest. Extended headers with information about detected content movement (renames and copying detection) are designed to work with the diff of two -<tree-ish> and are not used by combined diff format. +_<tree-ish>_ and are not used by combined diff format. 3. It is followed by a two-line from-file/to-file header: