Closed jnavila closed 1 week ago
/submit
Submitted as pull.1766.git.1721774680.gitgitgadget@gmail.com
To fetch this version into FETCH_HEAD
:
git fetch https://github.com/gitgitgadget/git/ pr-1766/jnavila/doc_synopsis_para-v1
To fetch this version to local tag pr-1766/jnavila/doc_synopsis_para-v1
:
git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1766/jnavila/doc_synopsis_para-v1
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
Sorry for the noise: this patch series does not work on macOS.
BR
Jean-Noël
/submit
Submitted as pull.1766.v2.git.1721855179.gitgitgadget@gmail.com
To fetch this version into FETCH_HEAD
:
git fetch https://github.com/gitgitgadget/git/ pr-1766/jnavila/doc_synopsis_para-v2
To fetch this version to local tag pr-1766/jnavila/doc_synopsis_para-v2
:
git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1766/jnavila/doc_synopsis_para-v2
On the Git mailing list, Junio C Hamano wrote (reply to this):
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Following several issues with the way the formatting of synopsis is done in
> the manpages that were recently reworked, this patch series introduces the
> processing of a new custom paragraph attribute 'synopsis'.
The rendered result looks OK but the source being just like what we
would write in plain text files without any extra mark-up makes it
look quite nice.
I wonder what we want to do with some oddballs, like git-shortlog
that uses "|" not as an alternative but literally a pipe (i.e. "feed
the output of this other command via a pipe to this command"),
though.
git log --pretty=short | git shortlog [<options>]
There may be also some page that indicates "this command takes its
input from its standard input" by using something like
git cmd [--foo] [--bar] <input-file
which we may need to think how to handle. The easiest way out may
be to say "don't do these to indicate/force where the input comes
from". I dunno.
Thanks.
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
On Thursday, 25 July 2024 01:15:48 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > Following several issues with the way the formatting of synopsis is done
in
> > the manpages that were recently reworked, this patch series introduces the
> > processing of a new custom paragraph attribute 'synopsis'.
>
> The rendered result looks OK but the source being just like what we
> would write in plain text files without any extra mark-up makes it
> look quite nice.
>
> I wonder what we want to do with some oddballs, like git-shortlog
> that uses "|" not as an alternative but literally a pipe (i.e. "feed
> the output of this other command via a pipe to this command"),
> though.
>
> git log --pretty=short | git shortlog [<options>]
I must confess that while reviewing my patch, by switching all [verse] to
[synopsis] , I looked at this line and understood the pipe as an alternative
from the grammar, not as a shell pipe. I also noted a few spots where the
grammar may be misinterpreted e.g. parenthesis in git-grep.
In theory the typesetting should tell the keyword apart from the grammar, but
for signs such as pipes and parenthesis the rendering does not change enough.
>
> There may be also some page that indicates "this command takes its
> input from its standard input" by using something like
>
> git cmd [--foo] [--bar] <input-file
>
> which we may need to think how to handle. The easiest way out may
> be to say "don't do these to indicate/force where the input comes
> from". I dunno.
>
The form
git cmd [--foo] [--bar] < <input-file>
is completely acceptable , would render correctly and would remove the use of
the pipe. The thing is that this pipe isn't even part of the command. It is
just an example. Maybe it should not appear in the synopsis at all.
For keyword signs that are already used in expressing the grammar, we could
quote the sign to indicate that it is a keyword : "(" .
Thanks
On the Git mailing list, Junio C Hamano wrote (reply to this):
Jean-Noël AVILA <jn.avila@free.fr> writes:
> The form
>
> git cmd [--foo] [--bar] < <input-file>
>
> is completely acceptable , would render correctly and would remove the use of
> the pipe.
Nice. I was afraid that it might be interpreted as a placeholder
whose description is "<input-file" ;-)
> The thing is that this pipe isn't even part of the command. It is
> just an example. Maybe it should not appear in the synopsis at all.
Historically the command was designed to read from "git log" as its
upstream and nothing else, which was where that sample command in
the synopsis originated, but it is unusual to spell out the upstream
(or downstream for that matter) of a pipe even when the command is
often used inside a pipeline in the synopsis section.
> For keyword signs that are already used in expressing the grammar, we could
> quote the sign to indicate that it is a keyword : "(" .
This patch series was integrated into seen via https://github.com/git/git/commit/a4a76879c7c4d90b41d836400e990e136526825b.
This branch is now known as ja/doc-synopsis-markup
.
This patch series was integrated into seen via https://github.com/git/git/commit/f040e0f0e5999aeb94f81e38510a01263b971646.
This patch series was integrated into seen via https://github.com/git/git/commit/4971d1105a69405e154823df4908a0fefdd731f8.
There was a status update in the "New Topics" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Inviting further discussion. source: <pull.1766.v2.git.1721855179.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/f5cf4032ffa40082971ed5d36732ed0f2eb2a4f0.
This patch series was integrated into seen via https://github.com/git/git/commit/1b553a718aad1bd4e61a3d9f55d61069940dcf19.
This patch series was integrated into seen via https://github.com/git/git/commit/391ba1d383c79c94847c65ff128f524495db7429.
This patch series was integrated into seen via https://github.com/git/git/commit/bf0d2713ccc99d41499060c421573fa76db982fb.
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Inviting further discussion. source: <pull.1766.v2.git.1721855179.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/306287d18f5a7c6ce8460aabc3a92ae509941716.
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Inviting further discussion. source: <pull.1766.v2.git.1721855179.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/ceed50100c37023a98cd2fed2c668d1e5719724a.
This patch series was integrated into seen via https://github.com/git/git/commit/3a21e2e1e88e9f2a8d6c30e2b34eaf910e05bca4.
This patch series was integrated into seen via https://github.com/git/git/commit/52ac49474e39f8f8f4b950ed72d3207e118132b4.
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Inviting further discussion. source: <pull.1766.v2.git.1721855179.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/bd4d5569a0c9f02362c282f87d93c41ab01490a4.
/submit
Submitted as pull.1766.v3.git.1723389612.gitgitgadget@gmail.com
To fetch this version into FETCH_HEAD
:
git fetch https://github.com/gitgitgadget/git/ pr-1766/jnavila/doc_synopsis_para-v3
To fetch this version to local tag pr-1766/jnavila/doc_synopsis_para-v3
:
git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1766/jnavila/doc_synopsis_para-v3
User Eric Sunshine <sunshine@sunshineco.com>
has been added to the cc: list.
User Jean-Noël Avila <jean-noel.avila@scantech.com>
has been added to the cc: list.
This patch series was integrated into seen via https://github.com/git/git/commit/bd72cd75aa63009ed83486d3f21becbf6366bb8a.
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Comments? source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Comments? source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Comments? source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/faa381447334a3836fafd1c48b11273aa7386c6f.
This patch series was integrated into seen via https://github.com/git/git/commit/9a923944baa9b7e7091abbf1b95bdd701ab2dc62.
On the Git mailing list, Junio C Hamano wrote (reply to this):
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Jean-Noël Avila (3):
> doc: introduce a synopsis custom paragraph attribute
> doc: update the guidelines to reflect the current formatting rules
> doc: apply synopsis simplification on git-clone and git-init
This topic has become quiet. I still find s:["someything you really
want to say"] notation a bit annoying to my eyes, but its may be the
best compromise we can come up with.
So unless we have a strong objection, or (even better) an objection
with an alternative that is less yucky, perhaps it is time to
declare that this is the variant of AsciiDoc/Asciidoctor that we'd
adopt for our documentation. Comments?
Thanks.
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Will merge to 'next'? cf. <xmqqzfp8cm30.fsf@gitster.g> source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/eba038aad990db9a86a7a170a4ad828cd88a6bed.
This patch series was integrated into seen via https://github.com/git/git/commit/0f4d96a7804f7f30710e1f41f773d32cfdf57768.
This patch series was integrated into seen via https://github.com/git/git/commit/1b165e3c1d6f0ae27c042147aa8a782a79c855d3.
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
Le lundi 19 août 2024, 22:08:19 CEST Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > Jean-Noël Avila (3):
> > doc: introduce a synopsis custom paragraph attribute
> > doc: update the guidelines to reflect the current formatting rules
> > doc: apply synopsis simplification on git-clone and git-init
>
> This topic has become quiet. I still find s:["someything you really
> want to say"] notation a bit annoying to my eyes, but its may be the
> best compromise we can come up with.
>
> So unless we have a strong objection, or (even better) an objection
> with an alternative that is less yucky, perhaps it is time to
> declare that this is the variant of AsciiDoc/Asciidoctor that we'd
> adopt for our documentation. Comments?
>
> Thanks.
>
I understand that you are reluctant to include a change that, as the
maintainer, you do not feel comfortable keeping alive.
The whole discussion thread tells me that other developers are not ready to go
down the "full markup" path. Understandably, this makes it more difficult for
everyone to propose changes and review them, as there's no tool to track such
formatting errors and we have to rely on careful manual cross-checking.
I would like to thank you for pushing so that the markup can be simplified as
much as can be. It can be simplified further one step further: it is possible
both in asciidoc/asciidoctor to override the formatting of inline verbatim
texts, so that everything that is backquoted is processed as a synopsis
string.
This way, strings like
`<commit>`
`diff.statGraphWidth=<width>`
` --dirstat-by-file[=<param>,...]`
are automatically rendered with the expected styles.
However, contrary to the s macro, this is quite disruptive as it forces the
new processing on all existing manpages. Another drawback is that it is no
longer genuine asciidoc, but it seems more in line with the critics. I'm
refining the regexp at the moment to check for side-effects.
Is this proposition more appropriate?
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Will merge to 'next'? cf. <xmqqzfp8cm30.fsf@gitster.g> source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/8e8a241a282c347348d7efe41c5d9af628ac0bfe.
This patch series was integrated into seen via https://github.com/git/git/commit/8469758040599819959dcca0211f81f42364cb6e.
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Will merge to 'next'? cf. <xmqqzfp8cm30.fsf@gitster.g> source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/603e036bc782dd2e6b3df401a87114ecc911b321.
This patch series was integrated into seen via https://github.com/git/git/commit/1ae9a08d726f62f7d7b21b01102b7b9bbd1f4bb7.
This patch series was integrated into seen via https://github.com/git/git/commit/963e68c72fea1d69769739fc8149cd56babe2349.
There was a status update in the "Cooking" section about the branch ja/doc-synopsis-markup
on the Git mailing list:
The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got vastly pleasant to work with. Will merge to 'next'? cf. <xmqqzfp8cm30.fsf@gitster.g> source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>
This patch series was integrated into seen via https://github.com/git/git/commit/02c39533f3f7c29c24ddeb1a1288e9f26917e729.
In the continuation of the simplification of manpage editing, the synopsis processing that was developed for synopsis paragraph style is also applied to all inline backquoted texts.
Refining the magic regexp took more time than expected, but this one should really enhance writers'experience. I had to fight a bit more with asciidoctor, due to discrepancies between version 2.0 on my laptop and the 1.5.6 used by Github actions.
The git-init and git-clone manpages are converted to this new system.
Changes since V1:
Changes since V2:
Changes since V3:
Changes since V4:
cc: Eric Sunshine sunshine@sunshineco.com cc: Josh Steadmon steadmon@google.com cc: Chris Torek chris.torek@gmail.com cc: Torsten Bögershausen tboegi@web.de