doc: introducing synopsis para

[jnavila]

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:

• switch to sed for asciidoc filter and refine the regex for support under macOS

Changes since V2:

• introduce the s macro to freely apply synopsis styling wherever needed, without formatting hassle.

Changes since V3:

• replace s macro by direct processing of literal text at the level of output processors.

Changes since V4:

• used BRE in sed filter
• rework the processing of three dots

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

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/1a75682019224e306f403a3f508a3cd5f1c5e825.

[gitgitgadget[bot]]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Jean-Noël AVILA <jn.avila@free.fr> writes:

> ... 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?

Thanks for thinking these things through.  The fact that such a
"magic" processing will hide the gory details from those whose
primary interest is to describe the commands and their options cuts
both ways.  It is a very welcome thing for developers around here, I
would assume.  At the same time, I can understand that purists would
find it unacceptably ugly, as `backticks` is now much more than a
mark-up that means "this text is typeset in monospace".  Inside it,
<text inside angle brackets>, [optional text], and (choices), all
signal that they have special meaning by being typeset differently.

I do not personally mind that, and I would even dream about a future
in which other projects notice what you did to AsciiDoctor, love it,
adopt it, and eventually it feeds back to improve AsciiDoctor proper.

It is very likely that is because I haven't seen any "side effects"
yet ;-)

Thanks.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/dc7dbf49e7a4c87e772dd15e5e33c11dc82fc847.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/995d561d155ce72d62ee9d6ec55de3b45185a8f6.

[gitgitgadget[bot]]

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.

cf. <1986021.PYKUYFuaPT@cayenne>
source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/b25ba86ca9478fc4c6bc59ab5746dec42b1d6879.

[gitgitgadget[bot]]

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.

cf. <1986021.PYKUYFuaPT@cayenne>
source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/3e83c834a379e887dfacdf94603c9bfb0224f014.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/a18da73b7f06cd357ec52ca0037d6cc5bd7ee77f.

[jnavila]

/submit

[gitgitgadget[bot]]

Submitted as pull.1766.v4.git.1725573126.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1766/jnavila/doc_synopsis_para-v4

To fetch this version to local tag pr-1766/jnavila/doc_synopsis_para-v4:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1766/jnavila/doc_synopsis_para-v4

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/447375576c0fa06ea76573da4fd82d26cc57dc6e.

[gitgitgadget[bot]]

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.

Expecting a reroll.
cf. <1986021.PYKUYFuaPT@cayenne>
source: <pull.1766.v3.git.1723389612.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/bea8e7a04f517550c538d80d8e3f2e484185aabc.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/bbfdef354d7a7ccfde468f2bff6a2e5f8ff3ab1b.

[gitgitgadget[bot]]

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.

Waiting for comments.
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/f8e26f556c127c640329626862e596a678a825ff.

[gitgitgadget[bot]]

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.

Waiting for comments.
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/97f6c366d1dc8a0c481fc715505a00f6103bbd08.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/cdba08a56cda89095b13204b11f2424367488bbc.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/cfbb5320ff74b931d2c0a3539b20e2a7187c8f9c.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/1cddde0d71dac7e52655a02090630f1340469704.

[gitgitgadget[bot]]

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.

Waiting for comments.
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> 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.

The fact that such a "magic" processing will hide the gory details
from those whose primary interest is to describe the commands and
their options cuts both ways.  While I can understand that purists
would find it ugly, as `backticks` is now much more than a mark-up
that means "this text is typeset in monospace", it is a very welcome
thing for developers around here, who just want to write their
document in a way even whose source is readable without having to
worry about suh gory details.  Maybe this gets popular enough after
other projects notice what you did to AsciiDoctor, love it, adopt
it, and eventually it feeds back to improve AsciiDoctor proper ;-).

So, unless there are objections and people want to discuss it further,
I'll mark the topic for 'next' soonish.

Thanks.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/163415a593994c719a156cd7ba64b9ceec159056.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/5b8595ddaabe60e60ae67d63849f3f2d0ca212b4.

[gitgitgadget[bot]]

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'.
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/ebc0c76b4b6054bdc9e0d4c47dfcf7d67a672f00.

[gitgitgadget[bot]]

This patch series was integrated into next via https://github.com/git/git/commit/d471154a0bf800b1d549eb65b9e73766310ed8c8.

[gitgitgadget[bot]]

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 'master'.
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/5fbc42f32335efb6030720a6a1050a79087fd3dc.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/b3324ca528b53ac4afb31b7b5b69234d991ea28e.

[gitgitgadget[bot]]

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 'master'.
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/bd03259d77d86da6684d2674276145635b6baf9a.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/042170779be7a38095c09c6dd2932fb78c0b2d50.

[gitgitgadget[bot]]

On the Git mailing list, Josh Steadmon wrote (reply to this):

On 2024.09.13 11:15, Junio C Hamano wrote:
> "Jean-No�l Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > 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.
> 
> The fact that such a "magic" processing will hide the gory details
> from those whose primary interest is to describe the commands and
> their options cuts both ways.  While I can understand that purists
> would find it ugly, as `backticks` is now much more than a mark-up
> that means "this text is typeset in monospace", it is a very welcome
> thing for developers around here, who just want to write their
> document in a way even whose source is readable without having to
> worry about suh gory details.  Maybe this gets popular enough after
> other projects notice what you did to AsciiDoctor, love it, adopt
> it, and eventually it feeds back to improve AsciiDoctor proper ;-).
> 
> So, unless there are objections and people want to discuss it further,
> I'll mark the topic for 'next' soonish.
> 
> Thanks.
> 

This still breaks on MacOS, as `sed` doesn't understand the '-E' option
there.

[gitgitgadget[bot]]

User Josh Steadmon <steadmon@google.com> has been added to the cc: list.

[gitgitgadget[bot]]

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 'master'.
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Josh Steadmon <steadmon@google.com> writes:

>> So, unless there are objections and people want to discuss it further,
>> I'll mark the topic for 'next' soonish.
>> 
>> Thanks.
>> 
>
> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
> there.

Thanks for a report.

What is sad is that we are seeing this after the topic gets very
close to 'master' (it has been in 'next' already for a few days).

Perhaps nobody builds documentation on macOS, in which case the
breakage may be totally acceptable?  Is that the message we are
hearing from mac based developers?

Grumpy...

[gitgitgadget[bot]]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Josh Steadmon <steadmon@google.com> writes:

> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
> there.

Can you try to see t6030 also breaks due to lack of ERE in the same
environment?  It seems it uses "sed -E", so it should fail to find
what it is trying to.

Thanks.

[gitgitgadget[bot]]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Junio C Hamano <gitster@pobox.com> writes:

> Josh Steadmon <steadmon@google.com> writes:
>
>> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
>> there.
>
> Can you try to see t6030 also breaks due to lack of ERE in the same
> environment?  It seems it uses "sed -E", so it should fail to find
> what it is trying to.
>
> Thanks.

The reason why I am curious is because https://ss64.com/mac/sed.html
claims that -E works.

Earlier I wrote somewhere whatever problem it is it would be shared
with BSD implementation of sed.  But apparently BSD's sed also works
with the -E option.  https://man.freebsd.org/cgi/man.cgi?sed(1)

So, I dunno.  Perhaps it is not -E but some specific construct used
in the pattern?

[gitgitgadget[bot]]

On the Git mailing list, Chris Torek wrote (reply to this):

On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:
> The reason why I am curious is because https://ss64.com/mac/sed.html
> claims that -E works.

It does for me, on my Mac, which is deliberately behind current: I am
still on Big Sur.

Chris

[gitgitgadget[bot]]

User Chris Torek <chris.torek@gmail.com> has been added to the cc: list.

[gitgitgadget[bot]]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Chris Torek <chris.torek@gmail.com> writes:

> On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:
>> The reason why I am curious is because https://ss64.com/mac/sed.html
>> claims that -E works.
>
> It does for me, on my Mac, which is deliberately behind current: I am
> still on Big Sur.

Thanks, Chris.

Josh, the topic has been cooking in 'next' long enough to graduate
to 'master' without anybody else complaining.  Could you
double-check and if possible see what is different in your
environment from others?

I can hold the topic in 'next' longer but not forever without
progress.  Help from macOS folks (if it is macOS specific issue)
is greatly appreciated.

Thanks.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/0eec0120ed1c38cc8f3157dfc31dd955dce1fb4e.

[gitgitgadget[bot]]

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.

On hold.
cf. <xmqqh6a6496d.fsf@gitster.g>
source: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

[jnavila]

/submit

[gitgitgadget[bot]]

Submitted as pull.1766.v5.git.1727161730.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1766/jnavila/doc_synopsis_para-v5

To fetch this version to local tag pr-1766/jnavila/doc_synopsis_para-v5:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1766/jnavila/doc_synopsis_para-v5

[gitgitgadget[bot]]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Changes since V4:
>
>  * used BRE in sed filter
>  * rework the processing of three dots

The topic has been deep in 'next' already, and I wasn't expecting a
wholesale replacement.  But thanks for updating.

As the patches are more in the technology demonstration phase by
converting only a few pages and making sure other uses of `` outside
the synopsis section in unconverted pages are not broken, we can
declare that the three-patch series will not be in 2.47 and will
keep it in 'next'.  So let me revert the merge of the previous one
out of 'next' and queue this one afresh to 'seen' to see how well it
works.

Josh (or whoever is taking over this week from him at Google), can
you see if the breakage you saw that stopped us merging the topic
before it causes us trouble on 'master' reproduces with this version
(either by running "make doc" on the topic branch by itself, or on
'seen' that merges the topic) in your environment that had trouble
with the previous round?

It would also be highly appreciated if other macOS users try "make
doc" and see the resulting git-init and git-clone documentation
pages are reasonable, both for the previous round that has been
cooking in 'next' and for this latest round.  Inputs from folks on
more mainstream platforms with modern asciidoc/asciidoctor toolchain
would also help.  The more people we have who look at how the new
way the synopsis section is written and how the resulting documents
get rendered, the more fairly we can assess the value of this topic.

Thanks.

[gitgitgadget[bot]]

On the Git mailing list, Torsten Bögershausen wrote (reply to this):

On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > Changes since V4:
> >
> >  * used BRE in sed filter
> >  * rework the processing of three dots
>
> The topic has been deep in 'next' already, and I wasn't expecting a
> wholesale replacement.  But thanks for updating.
>
> As the patches are more in the technology demonstration phase by
> converting only a few pages and making sure other uses of `` outside
> the synopsis section in unconverted pages are not broken, we can
> declare that the three-patch series will not be in 2.47 and will
> keep it in 'next'.  So let me revert the merge of the previous one
> out of 'next' and queue this one afresh to 'seen' to see how well it
> works.
>
> Josh (or whoever is taking over this week from him at Google), can
> you see if the breakage you saw that stopped us merging the topic
> before it causes us trouble on 'master' reproduces with this version
> (either by running "make doc" on the topic branch by itself, or on
> 'seen' that merges the topic) in your environment that had trouble
> with the previous round?
>
> It would also be highly appreciated if other macOS users try "make
> doc" and see the resulting git-init and git-clone documentation
> pages are reasonable, both for the previous round that has been
> cooking in 'next' and for this latest round.  Inputs from folks on
> more mainstream platforms with modern asciidoc/asciidoctor toolchain
> would also help.  The more people we have who look at how the new
> way the synopsis section is written and how the resulting documents
> get rendered, the more fairly we can assess the value of this topic.
>
> Thanks.
>

Here a report from a MacOs user,
asciidoc --version
asciidoc 10.2.0

installed via macports.

No problems seen in the seen branch.

I diffed git-init.html from seen of today against both master and next,
some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)
All in all it looks all sensible.
(and yes, `sed` understands -E)