Subject: [PATCH v2 0/9] doc: convert git log man page to new synopsis format

From: "Jean-Noël Avila via GitGitGadget" <[email-masked]>
Date: Sun, 29 Jun 2025 13:20:32 +0000

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.

Jean-Noël Avila (9):
  doc: convert git-log to new documentation format
  doc: git-log convert rev-list-description  to new doc format
  doc: git-log: convert line range options to new doc format
  doc: git-log: convert line range format to new doc format
  doc: git-log: convert rev list options to new doc format
  doc: git-log: convert pretty options to new doc format
  doc: git-log: convert pretty formats to new doc format
  doc: git-log: convert diff options to new doc format
  doc: git-log: convert log config to new doc format

 Documentation/asciidoc.conf.in             |   2 +-
 Documentation/asciidoctor-extensions.rb.in |   4 +-
 Documentation/config/log.adoc              |  47 +--
 Documentation/diff-options.adoc            |  40 ++-
 Documentation/git-log.adoc                 |  86 ++---
 Documentation/line-range-format.adoc       |  26 +-
 Documentation/line-range-options.adoc      |  10 +-
 Documentation/pretty-formats.adoc          | 283 +++++++--------
 Documentation/pretty-options.adoc          |  71 ++--
 Documentation/rev-list-description.adoc    |   6 +-
 Documentation/rev-list-options.adoc        | 390 ++++++++++-----------
 11 files changed, 493 insertions(+), 472 deletions(-)

base-commit: cf6f63ea6bf35173e02e18bdc6a4ba41288acff9
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1933%2Fjnavila%2Fdoc_git_log-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1933/jnavila/doc_git_log-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1933

Range-diff vs v1:

  1:  1ce06a18481 !  1:  f2b69588195 doc: convert git-log to new documentation format
     @@ Commit message
          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-masked]>
      
       ## Documentation/git-log.adoc ##
     @@ Documentation/git-log.adoc: each commit introduces are shown.
       	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
     - 	`log.excludeDecoration` config option allows excluding refs from
     +-	`log.excludeDecoration` config option allows excluding refs from
     ++	matches any of the _<pattern>_ parameters given to
     ++	`--decorate-refs-exclude` or if it doesn't match any of the
     ++	_<pattern>_ parameters given to `--decorate-refs`.
     ++	The `log.excludeDecoration` config option allows excluding refs from
       	the decorations, but an explicit `--decorate-refs` pattern will
       	override a match in `log.excludeDecoration`.
     + +
      @@ Documentation/git-log.adoc: If none of these options or config settings are given, then references are
       used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`,
       `refs/stash/`, or `refs/tags/`.
  2:  ff22d0f1adf =  2:  1f6c951726b doc: git-log convert rev-list-description  to new doc format
  3:  3992c1786ef =  3:  7bab515e136 doc: git-log: convert line range options to new doc format
  4:  d451d7f6c0a =  4:  384a7d23563 doc: git-log: convert line range format to new doc format
  5:  71d9a374102 =  5:  c2e857105d4 doc: git-log: convert rev list options to new doc format
  6:  5004a622c3f !  6:  01835272c2e doc: git-log: convert pretty options to new doc format
     @@ Documentation/pretty-options.adoc: people using 80-column terminals.
      +`--notes[=<ref>]`::
       	Show the notes (see linkgit:git-notes[1]) that annotate the
       	commit, when showing the commit log message.  This is the default
     - 	for `git log`, `git show` and `git whatchanged` commands when
     + ifndef::with-breaking-changes[]
      @@ Documentation/pretty-options.adoc: to display.  The ref can specify the full refname when it begins
       with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise
       `refs/notes/` is prefixed to form the full name of the ref.
  7:  d54e297567a =  7:  d5490f7d868 doc: git-log: convert pretty formats to new doc format
  8:  9f9ce432bd6 =  8:  c2346eb580c doc: git-log: convert diff options to new doc format
  9:  fa91d919fa0 !  9:  b12b8294b86 doc: git-log: convert log config to new doc format
     @@ Commit message
       ## Documentation/config/log.adoc ##
      @@
      -log.abbrevCommit::
     +-	If true, makes
      +`log.abbrevCommit`::
     - 	If true, makes linkgit:git-log[1], linkgit:git-show[1], and
     - 	linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
     ++	If `true`, make
     + ifndef::with-breaking-changes[]
     + 	linkgit:git-log[1], linkgit:git-show[1], and
     + 	linkgit:git-whatchanged[1]
     +@@ Documentation/config/log.adoc: endif::with-breaking-changes[]
     + 	assume `--abbrev-commit`. You may
       	override this option with `--no-abbrev-commit`.
       
      -log.date::

-- 
gitgitgadget