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

jnavila commented 3 months ago

/submit

gitgitgadget[bot] commented 3 months ago

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

gitgitgadget[bot] commented 3 months ago

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

jnavila commented 3 months ago

/submit

gitgitgadget[bot] commented 3 months ago

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

gitgitgadget[bot] commented 3 months ago

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.