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 <jn.avila@xxxxxxx> ## 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
