doc: introducing synopsis para

jnavila commented 3 months ago

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] commented 4 weeks ago

User Torsten Bögershausen <tboegi@web.de> has been added to the cc: list.

gitgitgadget[bot] commented 4 weeks ago

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

Torsten Bögershausen <tboegi@web.de> writes:

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

Since I haven't pushed out the 'seen' branch with latest iteration,
your sucess report is about the previous iteration that Josh said
"still breaks on MacOS" [*].  The plot thickens...

Thanks.

[Reference]

 * https://lore.kernel.org/git/4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn/

gitgitgadget[bot] commented 4 weeks ago

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

gitgitgadget[bot] commented 4 weeks ago

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

On 2024.09.23 14:14, Eric Sunshine wrote:
> On Mon, Sep 23, 2024 at 12:38 PM Junio C Hamano <gitster@pobox.com> wrote:
> > 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.
> >
> > 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.
> 
> I checked my High Sierra installation (macOS 10.13) which is even
> older than Big Sur (macOS 11), and High Sierra's "sed" also
> understands -E.

Hi folks, sorry for the false alarm and the delayed response. For some
reason our build environment has a >decade old version of sed. I'm still
tracking down why that is, but please do not hold back this topic any
longer due to our out-of-date-ness. Sorry again!

gitgitgadget[bot] commented 4 weeks ago

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

Josh Steadmon <steadmon@google.com> writes:

>> I checked my High Sierra installation (macOS 10.13) which is even
>> older than Big Sur (macOS 11), and High Sierra's "sed" also
>> understands -E.
>
> Hi folks, sorry for the false alarm and the delayed response. For some
> reason our build environment has a >decade old version of sed. I'm still
> tracking down why that is, but please do not hold back this topic any
> longer due to our out-of-date-ness. Sorry again!

Thanks.

I think Jean-Noël's latest rewrote ERE down to BRE but also tweaked
something else around U+2026 …. Please try that version again when
you have a chance.