doc: convert git log man page to new synopsis format #1933
Closed
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There are issues in commit c06e18a: |
|
/submit |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
|
/preview |
|
Preview email sent as [email protected] |
jnavila
changed the title
|
This patch series was integrated into seen via git@3caf8f8. |
|
This patch series was integrated into seen via git@603c449. |
|
This patch series was integrated into seen via git@48deb1f. |
|
This patch series was integrated into seen via git@7dc835f. |
|
This patch series was integrated into seen via git@8ec5fe7. |
|
This patch series was integrated into seen via git@a6ff8bc. |
|
This patch series was integrated into seen via git@c632d58. |
|
This patch series was integrated into seen via git@e6dbbaa. |
|
This patch series was integrated into seen via git@0c1ffc9. |
![gitgitgadget[bot]](https://avatars.githubusercontent.com/in/12836?s=60&v=4){kind=small}
| ---- | ||
| git-log - Show commit logs | ||
|
|
||
|
|
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" <[email protected]> writes:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
>
> - Switch the synopsis to a synopsis block which will automatically
> format placeholders in italics and keywords in monospace
> - Use _<placeholder>_ instead of <placeholder> in the description
> - Use `backticks` for keywords and more complex option
> descriptions. The new rendering engine will apply synopsis rules to
> these spans.
>
> Signed-off-by: Jean-Noël Avila <[email protected]>
> ---
> Documentation/git-log.adoc | 83 ++++++++++++++++++++------------------
> 1 file changed, 44 insertions(+), 39 deletions(-)
This hunk (lightly edited to shift contexts) ...
> ---no-decorate::
> ---decorate[=short|full|auto|no]::
> - Print out the ref names of any commits that are shown. If 'short' is
> - specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
> - 'refs/remotes/' will not be printed. If 'full' is specified, the
> - full ref name (including prefix) will be printed. If 'auto' is
> - specified, then if the output is going to a terminal, the ref names
> - are shown as if 'short' were given, otherwise no ref names are
> - shown. The option `--decorate` is short-hand for `--decorate=short`.
> - Default to configuration value of `log.decorate` if configured,
> - otherwise, `auto`.
> +`--no-decorate`::
> +`--decorate[=(short|full|auto|no)]`::
> + Print out the ref names of any commits that are shown. Possible values
> + are:
> ++
> +----
> +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
> + `refs/remotes/` are not printed.
> +`full`;; the full ref name (including prefix) is printed.
> +`auto`:: if the output is going to a terminal, the ref names
> + are shown as if `short` were given, otherwise no ref names are
> + shown.
> +----
> ++
> +The option `--decorate` is short-hand for `--decorate=short`. Default to
> +configuration value of `log.decorate` if configured, otherwise, `auto`.
... does more than what the three-bullet list in the proposed log
message describes. The result is certainly easier to follow and
more extensible to have these possible values in an enumerated list
than in a prose.
> +`--decorate-refs=<pattern>`::
> +`--decorate-refs-exclude=<pattern>`::
> For each candidate reference, do not use it for decoration if it
> - matches any patterns given to `--decorate-refs-exclude` or if it
> - doesn't match any of the patterns given to `--decorate-refs`. The
> + matches any of _<pattern>_ given to `--decorate-refs-exclude` or if it
> + doesn't match any of _<pattern>_ given to `--decorate-refs`. The
"any patterns" in the original may not be grammatical, but the
rewritten "any of _<pattern>_" does not sound grammatical, either.
"any of the _<pattern>_s"? I dunno what the convention should be
when more than one <placeholder> instances have to be referenced.There was a problem hiding this comment.
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
On Tuesday, 17 June 2025 01:02:11 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
> >
> > - Switch the synopsis to a synopsis block which will automatically
> >
> > format placeholders in italics and keywords in monospace
> >
> > - Use _<placeholder>_ instead of <placeholder> in the description
> > - Use `backticks` for keywords and more complex option
> > descriptions. The new rendering engine will apply synopsis rules to
> > these spans.
> >
> > Signed-off-by: Jean-Noël Avila <[email protected]>
> > ---
> >
> > Documentation/git-log.adoc | 83 ++++++++++++++++++++------------------
> > 1 file changed, 44 insertions(+), 39 deletions(-)
>
> This hunk (lightly edited to shift contexts) ...
>
> > ---no-decorate::
> > ---decorate[=short|full|auto|no]::
> > - Print out the ref names of any commits that are shown. If 'short'
is
> > - specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
> > - 'refs/remotes/' will not be printed. If 'full' is specified, the
> > - full ref name (including prefix) will be printed. If 'auto' is
> > - specified, then if the output is going to a terminal, the ref names
> > - are shown as if 'short' were given, otherwise no ref names are
> > - shown. The option `--decorate` is short-hand for `--
decorate=short`.
> > - Default to configuration value of `log.decorate` if configured,
> > - otherwise, `auto`.
> > +`--no-decorate`::
> > +`--decorate[=(short|full|auto|no)]`::
> > + Print out the ref names of any commits that are shown. Possible
values
> > + are:
> > ++
> > +----
> > +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
> > + `refs/remotes/` are not printed.
> > +`full`;; the full ref name (including prefix) is printed.
> > +`auto`:: if the output is going to a terminal, the ref names
> > + are shown as if `short` were given, otherwise no ref names are
> > + shown.
> > +----
> > ++
> > +The option `--decorate` is short-hand for `--decorate=short`. Default to
> > +configuration value of `log.decorate` if configured, otherwise, `auto`.
>
> ... does more than what the three-bullet list in the proposed log
> message describes. The result is certainly easier to follow and
> more extensible to have these possible values in an enumerated list
> than in a prose.
True. That may become a new rule too.
>
> > +`--decorate-refs=<pattern>`::
> >
> > +`--decorate-refs-exclude=<pattern>`::
> > For each candidate reference, do not use it for decoration if it
> >
> > - matches any patterns given to `--decorate-refs-exclude` or if it
> > - doesn't match any of the patterns given to `--decorate-refs`. The
> > + matches any of _<pattern>_ given to `--decorate-refs-exclude` or
if it
> > + doesn't match any of _<pattern>_ given to `--decorate-refs`. The
>
> "any patterns" in the original may not be grammatical, but the
> rewritten "any of _<pattern>_" does not sound grammatical, either.
> "any of the _<pattern>_s"? I dunno what the convention should be
> when more than one <placeholder> instances have to be referenced.
Good question for which I was more inclined to consider placeholders as
invariant, even if the result may sound "ungrammatical". This also simplifies
the translation process where the plural forms can be complicated in some
languages.
|
This patch series was integrated into seen via git@5aa46aa. |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): "Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> This series converts the man page of git log to the synopsis format style.
> Git log is the second largest manpage after git config, which makes the
> changes quite large.
;-)
Other than the "add % to literal" in [5/9], which I couldn't figure
out if it truly belongs to "doc: git-log: convert rev list options
to new doc format", everything looked pretty reasonable.
|
|
This patch series was integrated into seen via git@a677050. |
| ----------------------------------------------------------------------- | ||
| endif::git-log[] | ||
|
|
||
| means "list all the commits which are reachable from 'foo' or 'bar', but |
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" <[email protected]> writes:
> -A special notation "'<commit1>'..'<commit2>'" can be used as a
> -short-hand for "^'<commit1>' '<commit2>'". For example, either of
> +A special notation "`<commit1>..<commit2>`" can be used as a
> +short-hand for "`^<commit1> <commit2>`". For example, either of
It didn't look like there are huge differences in the rendered
output with this change (and the below hunk) ...
> the following may be used interchangeably:
>
> ifdef::git-rev-list[]
> @@ -43,7 +43,7 @@ $ git log HEAD ^origin
> -----------------------------------------------------------------------
> endif::git-log[]
>
> -Another special notation is "'<commit1>'...'<commit2>'" which is useful
> +Another special notation is "`<commit1>...<commit2>`" which is useful
... or without, but semantically the updated one of course is more
correct ;-)There was a problem hiding this comment.
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
On Thursday, 19 June 2025 03:24:03 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> > -A special notation "'<commit1>'..'<commit2>'" can be used as a
> > -short-hand for "^'<commit1>' '<commit2>'". For example, either of
> > +A special notation "`<commit1>..<commit2>`" can be used as a
> > +short-hand for "`^<commit1> <commit2>`". For example, either of
>
> It didn't look like there are huge differences in the rendered
> output with this change (and the below hunk) ...
>
> > the following may be used interchangeably:
> >
> > ifdef::git-rev-list[]
> >
> > @@ -43,7 +43,7 @@ $ git log HEAD ^origin
> >
> > -----------------------------------------------------------------------
> > endif::git-log[]
> >
> > -Another special notation is "'<commit1>'...'<commit2>'" which is useful
> > +Another special notation is "`<commit1>...<commit2>`" which is useful
>
> ... or without, but semantically the updated one of course is more
> correct ;-)
I have a special setup where bold and italic are rendered as colors in the
manpages, red for bold, green for italic. The dots turn red with this change.
|
This patch series was integrated into seen via git@e316509. |
|
This patch series was integrated into seen via git@56ebd3f. |
|
This patch series was integrated into seen via git@8e60509. |
|
This patch series was integrated into seen via git@569da53. |
|
This patch series was integrated into seen via git@6e42a28. |
jnavila
force-pushed
the
doc_git_log
branch
2 times, most recently
from
8dfa1d8 to
b12b829
Compare
|
/submit |
|
This patch series was integrated into seen via git@9711508. |
|
/submit |
|
Submitted as [email protected] 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" <[email protected]> writes:
> This series converts the man page of git log to the synopsis format style.
> Git log is the second largest manpage after git config, which makes the
> changes quite large.
>
> A special note about the log format description which required escaping the
> synopsis processing of parentheses.
>
> Changes since V1:
>
> * rework the grammar style when refering to plural placeholders . The text
> is more descriptive and does not rely on puns. Puns may be difficult to
> understand and to translate.
> * change commit message to reflect the conversion of inline description of
> several option to a list.
Changes since v2 is a minor but necessary mark-up fix, as we do not
want to leave `enclosing` mark-up elements unclosed.
Will queue. Shall we mark the topic for 'next' now?
Thanks. |
|
On the Git mailing list, Jean-Noël AVILA wrote (reply to this): On Monday, 7 July 2025 22:59:35 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> > This series converts the man page of git log to the synopsis format style.
> > Git log is the second largest manpage after git config, which makes the
> > changes quite large.
> >
> > A special note about the log format description which required escaping
the
> > synopsis processing of parentheses.
> >
> > Changes since V1:
> > * rework the grammar style when refering to plural placeholders . The
text
> >
> > is more descriptive and does not rely on puns. Puns may be difficult to
> > understand and to translate.
> >
> > * change commit message to reflect the conversion of inline description of
> >
> > several option to a list.
>
> Changes since v2 is a minor but necessary mark-up fix, as we do not
> want to leave `enclosing` mark-up elements unclosed.
>
> Will queue. Shall we mark the topic for 'next' now?
>
> Thanks.
I think so. Reworking the formatter logic will be proposed in another patch
series.
|
|
This patch series was integrated into seen via git@8f6eefb. |
|
This patch series was integrated into seen via git@a80ea93. |
|
This patch series was integrated into seen via git@dc2f2b1. |
|
This patch series was integrated into seen via git@459d076. |
|
This branch is now known as |
|
This patch series was integrated into seen via git@64e6008. |
|
This patch series was integrated into seen via git@63090d3. |
|
This patch series was integrated into seen via git@578d0ce. |
|
There was a status update in the "Cooking" section about the branch Doc mark-up updates. Will merge to 'next'. source: <[email protected]> |
|
There was a status update in the "Cooking" section about the branch Doc mark-up updates. Will merge to 'next'. source: <[email protected]> |
|
This patch series was integrated into seen via git@d49caa8. |
|
This patch series was integrated into next via git@8eb14e9. |
|
This patch series was integrated into seen via git@b943eb6. |
|
This patch series was integrated into seen via git@f43ca03. |
|
There was a status update in the "Cooking" section about the branch Doc mark-up updates. Will merge to 'master'. source: <[email protected]> |
|
This patch series was integrated into seen via git@d9f8cfe. |
|
This patch series was integrated into seen via git@fe02fe7. |
|
This patch series was integrated into master via git@fe02fe7. |
|
This patch series was integrated into next via git@fe02fe7. |
|
Closed via fe02fe7. |
| @@ -1,37 +1,37 @@ | |||
| PRETTY FORMATS | |||
| -------------- | |||
There was a problem hiding this comment.
On the Git mailing list, SZEDER Gábor wrote (reply to this):
On Mon, Jul 07, 2025 at 06:53:30PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
>
> - Use _<placeholder>_ instead of <placeholder> in the description
> - Use `backticks` for keywords and more complex option
> descriptions. The new rendering engine will apply synopsis rules to
> these spans.
>
> For all the formats in the form of %(foo), the formatting needs to be
> heavier because we not want the parentheses to be rendered as syntax
> elements,but as keywords, i.e. we need to circumvent the syntax highlighting
> of synopsis. In this particular case, this requires the heavy escaping of
> the parts that contain parentheses with ++.
>
> Signed-off-by: Jean-Noël Avila <[email protected]>
> ---
> Documentation/pretty-formats.adoc | 283 +++++++++++++++---------------
> 1 file changed, 143 insertions(+), 140 deletions(-)
>
> diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
> index 07475de8c337..9ed0417fc811 100644
> --- a/Documentation/pretty-formats.adoc
> +++ b/Documentation/pretty-formats.adoc
> +++%(decorate++`[:<option>,...]`++)++::
> ref names with custom decorations. The `decorate` string may be followed by a
> colon and zero or more comma-separated options. Option values may contain
> literal formatting codes. These must be used for commas (`%x2C`) and closing
> parentheses (`%x29`), due to their role in the option syntax.
> +
> -** 'prefix=<value>': Shown before the list of ref names. Defaults to "{nbsp}`(`".
> -** 'suffix=<value>': Shown after the list of ref names. Defaults to "`)`".
> -** 'separator=<value>': Shown between ref names. Defaults to "`,`{nbsp}".
> -** 'pointer=<value>': Shown between HEAD and the branch it points to, if any.
> - Defaults to "{nbsp}`->`{nbsp}".
> -** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}".
> +** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}+(+".
> +** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+".
> +** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}".
> +** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
> + Defaults to "{nbsp}+->+{nbsp}".
> +** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
>
> +
> For example, to produce decorations with no wrapping
> or tag annotations, and spaces as separators:
> +
> -`%(decorate:prefix=,suffix=,tag=,separator= )`
> +++%(decorate:prefix=,suffix=,tag=,separator= )++
This section now looks like this when the man page is built with
Asciidoctor:
%(decorate[:<option>,...])
ref names with custom decorations. The decorate string may
be followed by a colon and zero or more comma-separated
options. Option values may contain literal formatting
codes. These must be used for commas (%x2C) and closing
parentheses (%x29), due to their role in the option syntax.
parentheses (%x29), due to their role in the option syntax.
• prefix=<value>: Shown before the list of ref names.
Defaults to " +(+".
• suffix=<value>: Shown after the list of ref names.
Defaults to ")".
• separator=<value>: Shown between ref names. Defaults to
", ".
• pointer=<value>: Shown between HEAD and the branch it
points to, if any. Defaults to " +→+ ".
• tag=<value>: Shown before tag names. Defaults to
"tag: ".
For example, to produce decorations with no wrapping or tag
annotations, and spaces as separators:
+ %(decorate:prefix=,suffix=,tag=,separator= )
Note the unnecessary + characters in the default values for 'prefix'
and 'pointer', and in the latter the "ASCII art" arrow ("->") is now
replaced with a unicode arrow character.
Also note that the last three lines are not aligned properly and the
example format string starts with a + character as well, but this was
the case even before this patch.
I use the distro packaged version of Asciidoctor:
$ asciidoctor --version
Asciidoctor 2.0.16 [https://asciidoctor.org]
Runtime Environment (ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
There was a problem hiding this comment.
On the Git mailing list, Jean-Noël Avila wrote (reply to this):
Asciidoc.py and Asciidoctor do not process the same '+' verbatim syntax in
the same way. For most usages, Asciidoctor requires a double '+'.
Unfortunately, the postprocessing of verbatim synopsis in asciidoctor cannot
be bypassed and formatting of the parentheses is forced in syntax sign
instead of keywords, unless a proper grammar analyzer is used.
Signed-off-by: Jean-Noël Avila <[email protected]>
---
Documentation/pretty-formats.adoc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
index 9ed0417fc8..618ddc4a0c 100644
--- a/Documentation/pretty-formats.adoc
+++ b/Documentation/pretty-formats.adoc
@@ -233,11 +233,11 @@ colon and zero or more comma-separated options. Option values may contain
literal formatting codes. These must be used for commas (`%x2C`) and closing
parentheses (`%x29`), due to their role in the option syntax.
+
-** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}+(+".
+** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}++(++".
** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+".
** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}".
** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
- Defaults to "{nbsp}+->+{nbsp}".
+ Defaults to "{nbsp}++->++{nbsp}".
** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
+
--
2.51.0
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
Jean-Noël Avila <[email protected]> writes:
> Asciidoc.py and Asciidoctor do not process the same '+' verbatim syntax in
> the same way. For most usages, Asciidoctor requires a double '+'.
The word "same" on the first line is probably unwanted?
> Unfortunately, the postprocessing of verbatim synopsis in asciidoctor cannot
> be bypassed and formatting of the parentheses is forced in syntax sign
> instead of keywords, unless a proper grammar analyzer is used.
Sorry, I've read the above three times, but it would not explain why
the change is needed for the "prefix" line, but no change is needed
for the "suffix" line or for the "separator" line, even though they
look quite similar. Is open-parenthesis somehow special? And '>'
also special in the same way?
>
> Signed-off-by: Jean-Noël Avila <[email protected]>
> ---
> Documentation/pretty-formats.adoc | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
> index 9ed0417fc8..618ddc4a0c 100644
> --- a/Documentation/pretty-formats.adoc
> +++ b/Documentation/pretty-formats.adoc
> @@ -233,11 +233,11 @@ colon and zero or more comma-separated options. Option values may contain
> literal formatting codes. These must be used for commas (`%x2C`) and closing
> parentheses (`%x29`), due to their role in the option syntax.
> +
> -** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}+(+".
> +** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}++(++".
> ** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+".
> ** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}".
> ** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
> - Defaults to "{nbsp}+->+{nbsp}".
> + Defaults to "{nbsp}++->++{nbsp}".
> ** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
>
> +There was a problem hiding this comment.
On the Git mailing list, Jean-Noël Avila wrote (reply to this):
The change is needed because Asciidoc.py and Asciidoctor
do not process the '+' verbatim the same way. A span is
detected when the format sign (here '+')is preceded by a
non-word character. I haven't digged into the source,
but it seems that '{nbsp}' is considered a non-word sign
by Asciidoc.py, but not by Asciidoctor.
Using the double '+' opens 'unconstrained' span,
independent on the preceding character in both engines.There was a problem hiding this comment.
On the Git mailing list, Jean-Noël Avila wrote (reply to this):
Asciidoc.py and Asciidoctor do not parse the '+' verbatim syntax in the same
way. For most usages, Asciidoctor requires a double '+'.
Unfortunately, the post-processing of verbatim synopsis in asciidoctor
cannot be bypassed and formatting of the parentheses is forced in syntax
sign instead of keywords, unless a proper grammar analyzer is used.
Signed-off-by: Jean-Noël Avila <[email protected]>
---
Documentation/pretty-formats.adoc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
index 9ed0417fc8..618ddc4a0c 100644
--- a/Documentation/pretty-formats.adoc
+++ b/Documentation/pretty-formats.adoc
@@ -233,11 +233,11 @@ colon and zero or more comma-separated options. Option values may contain
literal formatting codes. These must be used for commas (`%x2C`) and closing
parentheses (`%x29`), due to their role in the option syntax.
+
-** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}+(+".
+** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}++(++".
** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+".
** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}".
** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
- Defaults to "{nbsp}+->+{nbsp}".
+ Defaults to "{nbsp}++->++{nbsp}".
** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
+
--
2.51.0
There was a problem hiding this comment.
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
On Tuesday, 19 August 2025 23:49:36 CEST Junio C Hamano wrote:
> Jean-Noël Avila <[email protected]> writes:
> > Asciidoc.py and Asciidoctor do not process the same '+' verbatim syntax in
> > the same way. For most usages, Asciidoctor requires a double '+'.
>
> The word "same" on the first line is probably unwanted?
>
Definitely. Rerolled in V2.
> > Unfortunately, the postprocessing of verbatim synopsis in asciidoctor
cannot
> > be bypassed and formatting of the parentheses is forced in syntax sign
> > instead of keywords, unless a proper grammar analyzer is used.
>
> Sorry, I've read the above three times, but it would not explain why
> the change is needed for the "prefix" line, but no change is needed
> for the "suffix" line or for the "separator" line, even though they
> look quite similar. Is open-parenthesis somehow special? And '>'
> also special in the same way?
The detection of opening of spans in Asciidoc is driven by a span markup
character (here '+') preceded by a non-word character. The condition is
symmetrical for closing of spans. I haven't dug into the source code, but it
seems that asciidoc.py considers '{nbsp}' as a non-word character, whereas
Asciidoctor does not.
Using double markup characters creates 'unconstrained' spans, which do not
need the non-word character condition.
Note also that this "feature" is very centric on roman based languages (like
many of light markup design decisions) and is a pain in other writing systems
which do not require space between words.
>
> > Signed-off-by: Jean-Noël Avila <[email protected]>
> > ---
> >
> > Documentation/pretty-formats.adoc | 4 ++--
> > 1 file changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/pretty-formats.adoc
> > b/Documentation/pretty-formats.adoc
> > index 9ed0417fc8..618ddc4a0c 100644
> > --- a/Documentation/pretty-formats.adoc
> > +++ b/Documentation/pretty-formats.adoc
> > @@ -233,11 +233,11 @@ colon and zero or more comma-separated options.
Option
> > values may contain>
> > literal formatting codes. These must be used for commas (`%x2C`) and
closing
> > parentheses (`%x29`), due to their role in the option syntax.
> > +
> >
> > -** `prefix=<value>`: Shown before the list of ref names. Defaults to
> > "{nbsp}+(+". +** `prefix=<value>`: Shown before the list of ref names.
Defaults
> > to "{nbsp}++(++".>
> > ** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)
+".
> > ** `separator=<value>`: Shown between ref names. Defaults to "+,+
{nbsp}".
> > ** `pointer=<value>`: Shown between HEAD and the branch it points to, if
any.
> >
> > - Defaults to "{nbsp}+->+{nbsp}".
> > + Defaults to "{nbsp}++->++{nbsp}".
> >
> > ** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
> >
> > +
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
Jean-Noël Avila <[email protected]> writes:
> The change is needed because Asciidoc.py and Asciidoctor
> do not process the '+' verbatim the same way. A span is
> detected when the format sign (here '+')is preceded by a
> non-word character. I haven't digged into the source,
> but it seems that '{nbsp}' is considered a non-word sign
> by Asciidoc.py, but not by Asciidoctor.
>
> Using the double '+' opens 'unconstrained' span,
> independent on the preceding character in both engines.
Thanks for explaining.
It is especially nice to see "independent on the preceding character
in both engines", meaning that this fixes Asciidoctor while not
breaking Asciidoc ;-)
Now, can you do give the explanation in the proposed commit log
message, so that later people do not have to ask the same question
while reading "git log -p" output?
Thanks.There was a problem hiding this comment.
On the Git mailing list, Jean-Noël Avila wrote (reply to this):
Asciidoc.py and Asciidoctor do not process the '+' verbatim the same way. A
span is detected when the format sign (here '+')is preceded by a non-word
character. It seems that '{nbsp}' is considered a non-word sign by
Asciidoc.py, but not by Asciidoctor.
Using a double format-sign opens 'unconstrained' span, independent on the
preceding character in both engines.
The '+' sign is used instead of the backtick '`' because it is not processed
as synopsis in asciidoc.py. Unfortunately, the post-processing of verbatim
synopsis in asciidoctor cannot be bypassed and formatting of the parentheses
is forced in syntax sign instead of keywords, unless a proper grammar
analyzer is used.
Signed-off-by: Jean-Noël Avila <[email protected]>
---
Documentation/pretty-formats.adoc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
index 9ed0417fc8..618ddc4a0c 100644
--- a/Documentation/pretty-formats.adoc
+++ b/Documentation/pretty-formats.adoc
@@ -233,11 +233,11 @@ colon and zero or more comma-separated options. Option values may contain
literal formatting codes. These must be used for commas (`%x2C`) and closing
parentheses (`%x29`), due to their role in the option syntax.
+
-** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}+(+".
+** `prefix=<value>`: Shown before the list of ref names. Defaults to "{nbsp}++(++".
** `suffix=<value>`: Shown after the list of ref names. Defaults to "+)+".
** `separator=<value>`: Shown between ref names. Defaults to "+,+{nbsp}".
** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
- Defaults to "{nbsp}+->+{nbsp}".
+ Defaults to "{nbsp}++->++{nbsp}".
** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
+
--
2.51.0
|
User |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This series converts the man page of git log to the synopsis format style. Git log is the second largest manpage after git config, which makes the changes quite large.
A special note about the log format description which required escaping the synopsis processing of parentheses.
Changes since V1:
cc: "Kristoffer Haugsbakk" [email protected]
cc: SZEDER Gábor [email protected]