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
- 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 <jn.avila@free.fr>
Use `backticks` for commit ranges. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
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 <jn.avila@free.fr>
- 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 <jn.avila@free.fr>
- 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 <jn.avila@free.fr>
- 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 <jn.avila@free.fr>
|
There are issues in commit c06e18a: |
- 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 <jn.avila@free.fr>
- 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 <jn.avila@free.fr>
- 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 <jn.avila@free.fr>
|
/submit |
|
Submitted as pull.1933.git.1749373787.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
/preview |
|
Preview email sent as pull.1933.v2.git.1749374531.gitgitgadget@gmail.com |
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" <gitgitgadget@gmail.com> writes:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> - 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 <jn.avila@free.fr>
> ---
> 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.
|
This patch series was integrated into seen via git@5aa46aa. |
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.