doc: introducing synopsis para #1766
Conversation
jnavila
force-pushed
the
doc_synopsis_para
branch
2 times, most recently
from
338a04c
to
3bcbe45
Compare
|
/submit |
|
Submitted as pull.1766.git.1721774680.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
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
|
![gitgitgadget[bot]](https://avatars.githubusercontent.com/in/12836?s=60&v=4){kind=small}
| @@ -57,3 +57,17 @@ git-relative-html-prefix= | |||
| [linkgit-inlinemacro] | |||
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> +ifdef::backend-docbook[]
> +ifdef::doctype-manpage[]
> +[paradef-default]
> +#synopsis-style=template="verseparagraph",filter="sed -E 's!<[a-z-]+>!<emphasis>\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\1</literal>!g'"
> +synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([=+a-zA-Z0-9-:+=]+)!\\1<literal>\\2</literal>!g;s!(<\\;[a-zA-Z0-9-.]+>\\;)!<emphasis>\\1</emphasis>!g'"
> +#synopsis-style=template="verseparagraph"
This has three candidate definitions, but two are commented out?
> +endif::doctype-manpage[]
> +endif::backend-docbook[]
> +
> +ifdef::backend-xhtml11[]
> +[paradef-default]
> +synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([+a-zA-Z0-9-:+=]+)!\\1<code>\\2</code>!g;s!(<\\;[a-zA-z0-9-.]+>\\;)!<em>\\1</em>!g'"
> +endif::backend-xhtml11[]
With this update, do we now assume that anybody who want to format
the documentation from source must have a minimally working Perl on
their $PATH? It probably is an OK requirement to have.
| @@ -760,56 +760,60 @@ Markup: | |||
|
|
|||
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
> Documentation/CodingGuidelines | 34 +++++++++++++++++++---------------
> 1 file changed, 19 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 1d92b2da03e8..4d59e8f89ec8 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -760,56 +760,60 @@ Markup:
>
> Synopsis Syntax
>
> - Syntax grammar is formatted neither as literal nor as placeholder.
> + The synopsis (a paragraph with [synopsis] attribute) is automatically
> + formatted by the toolchain and does not need typesetting.
How pleasant ;-)
> And a somewhat more contrived example:
> - `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
> + --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
> Here "=" is outside the brackets, because "--diff-filter=" is a
> valid usage. "*" has its own pair of brackets, because it can
> (optionally) be specified only when one or more of the letters is
jnavila
force-pushed
the
doc_synopsis_para
branch
4 times, most recently
from
5e419d6
to
2a61e09
Compare
|
/submit |
|
Submitted as pull.1766.v2.git.1721855179.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
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 git@a4a7687. |
|
This branch is now known as |
|
This patch series was integrated into seen via git@f040e0f. |
|
This patch series was integrated into seen via git@4971d11. |
|
There was a status update in the "New Topics" section about the branch 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 git@f5cf403. |
|
This patch series was integrated into seen via git@1b553a7. |
|
This patch series was integrated into seen via git@391ba1d. |
|
This patch series was integrated into seen via git@bf0d271. |
|
There was a status update in the "Cooking" section about the branch 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 git@306287d. |
|
There was a status update in the "Cooking" section about the branch 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 git@ceed501. |
|
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.
|
|
This patch series was integrated into seen via git@c0a1d61. |
|
There was a status update in the "Cooking" section about the branch 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. Reverted out of 'next', and then replaced. Will merge to 'next'? source: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@6eb3a4e. |
|
There was a status update in the "Cooking" section about the branch 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. Reverted out of 'next', and then replaced. Will merge to 'next'? source: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@2291cb7. |
|
This patch series was integrated into seen via git@55e57e6. |
|
There was a status update in the "Cooking" section about the branch 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. Reverted out of 'next', and then replaced. Will merge to 'next'. source: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@95597c8. |
|
This patch series was integrated into next via git@15ec13e. |
|
There was a status update in the "Cooking" section about the branch 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.v5.git.1727161730.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@13da69d. |
|
There was a status update in the "Cooking" section about the branch 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 cook in 'next'. source: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com> |
|
On the Git mailing list, Josh Steadmon wrote (reply to this): On 2024.09.24 13:33, Junio C Hamano wrote:
> 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/
I finally got the chance to test this version on $DAYJOB's build
infrastructure, and I verified that it works (I also got a much more
recent version of sed installed). |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): Josh Steadmon <steadmon@google.com> writes:
> I finally got the chance to test this version on $DAYJOB's build
> infrastructure, and I verified that it works (I also got a much more
> recent version of sed installed).
Thanks for a follow-up.
|
|
This patch series was integrated into seen via git@54e1d00. |
|
This patch series was integrated into seen via git@09a010c. |
|
This patch series was integrated into seen via git@af08cec. |
|
There was a status update in the "Cooking" section about the branch 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 cook in 'next'. source: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@66a3e57. |
|
There was a status update in the "Cooking" section about the branch 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 cook in 'next'. source: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com> |
|
There was a status update in the "Cooking" section about the branch 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 cook in 'next'. source: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@ead5af0. |
|
This patch series was integrated into seen via git@a1cf574. |
|
This patch series was integrated into seen via git@7994503. |
|
This patch series was integrated into master via git@7994503. |
|
This patch series was integrated into next via git@7994503. |
|
Closed via 7994503. |
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