doc: convert git log man page to new synopsis format #1933
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}
| @@ -8,8 +8,8 @@ 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. |
| @@ -26,8 +26,8 @@ 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 |
|
Submitted as [email protected] To fetch this version into To fetch this version to local tag |
|
This patch series was integrated into seen via git@42105a5. |
|
This patch series was integrated into seen via git@ac0848b. |
|
This patch series was integrated into seen via git@d7f8e30. |
| @@ -1,38 +1,38 @@ | |||
| --pretty[=<format>]:: | |||
| --format=<format>:: | |||
| `--pretty[=<format>]`:: | |||
There was a problem hiding this comment.
On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this):
On Sun, Jun 29, 2025, at 15:20, Jean-Noël Avila via GitGitGadget wrote:
> See the "PRETTY FORMATS" section for some additional details for each
> -format. When '=<format>' part is omitted, it defaults to 'medium'.
> +format. When `=<format>` part is omitted, it defaults to `medium.
s/`medium./`medium`./
|
User |
|
On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this), regarding d54e297 (outdated): On Sun, Jun 8, 2025, at 11:09, 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
nit: s/elements,but/elements, but/
> -** '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}".
`+->+` gets rendered as `+→+` in the HTMl output.
`Documentation/doc-diff` shows the same.
Has using `␣` to denote SP in verbatim code blocks been considered
by anyone?
> +** `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= )++ |
|
On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this), regarding d54e297 (outdated): On Fri, Jul 4, 2025, at 22:43, Kristoffer Haugsbakk wrote:
> Has using `␣` to denote SP in verbatim code blocks been considered
> by anyone?
Bad example to associate with ` -> ` (␣->␣). But it could work for some
things like `:␣` in git-interpret-trailers(1). |
|
On the Git mailing list, Jean-Noël AVILA wrote (reply to this): On Friday, 4 July 2025 23:39:31 CEST Kristoffer Haugsbakk wrote:
> On Fri, Jul 4, 2025, at 22:43, Kristoffer Haugsbakk wrote:
> > Has using `␣` to denote SP in verbatim code blocks been considered
> > by anyone?
>
> Bad example to associate with ` -> ` (␣->␣). But it could work for some
> things like `:␣` in git-interpret-trailers(1).
That's one issue when doing the conversion to the new format, mainly because
sometimes back-quoting the commands does not enclose them in a frame that
would preserve the spaces in the manpage format, what was done at git-scm.com.
However, using `␣` everywhere might be a bit overweight. It would be reserved
to places where spotting the space character is difficult
Thanks
JN
|
|
On the Git mailing list, Jean-Noël AVILA wrote (reply to this): On Wednesday, 18 June 2025 23:35:51 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.
>
> ;-)
>
> 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.
TBH, I'm not entirely satisfied with this patch, because it reintroduces
complicated format marks everywhere instead of pushing this complexity into
the formatting logic. The problem is coming again that we have some signs
which are used for the synopsis syntax but can appear as "keywords". First
there was the three dot notation, now it's the parenthesis. Coming up with
basic regexps that can handle the context difference to tell apart their
grammatical meaning is increasing difficult, if not impossible.
For git-scm.com, with asciidoctor, an extension managing the synopsis style
using a parser combinator was introduced to alleviate the difficulty of the
task.
The problem is that, as far as I can tell, asciidoc.py does not propose such
extensions in a programmable way. If anybody can direct me to an example of
using a parser combinator in asciidoc.py, that would be great. For the moment,
this patch is the best proposition.
Thanks
JN
|
- 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. We also transform inline descriptions of possible values of option --decorate into a list, which is more readable and extensible. Signed-off-by: Jean-Noël Avila <[email protected]>
Use `backticks` for commit ranges. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila <[email protected]>
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]>
- 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]>
- Fix some malformed synopis of options - 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. - Add the '%' sign to the characters of keywords. Signed-off-by: Jean-Noël Avila <[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. Signed-off-by: Jean-Noël Avila <[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]>
- Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. - In description lists, put each option on its own line, to make them more searchable and enable automatic translation of the options. Signed-off-by: Jean-Noël Avila <[email protected]>
- Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. - Explain possible options in description list instead of in a paragraph. Signed-off-by: Jean-Noël Avila <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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]