[PATCH v3 0/6] Introduce more doc linting

["Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>]

Reviewing the documentation part of the last patches, it turns out that the
majority of my comments are related to the latest documentation guidelines
which are both easy to forget and almost trivial to automatically check.

This series implements the automatic tests for basic doc rules. At the
moment it conflicts with "[GSoC][PATCH v6 0/6] Add refs list subcommand" and
possibly with "[PATCH v4 0/9] refs: fix migration of reflog entries"

Changes since v1:

 * fix a small typo

Changes since v2:

 * extend range of check files for multiple entries in definition list
   entries
 * extend checks for new synopsis styles

Jean-Noël Avila (6):
  doc: test linkgit macros for well-formedness
  doc: check well-formedness of delimited sections
  doc: check for absence of multiple terms in each entry of desc list
  doc: check for absence of the form --[no-]parameter
  doc:git-for-each-ref: fix styling and typos
  doc lint: check that synopsis manpages have synopsis inlines

 Documentation/Makefile                        |  21 +-
 Documentation/RelNotes/1.6.2.4.adoc           |   1 +
 Documentation/blame-options.adoc              |   3 +-
 Documentation/diff-format.adoc                |   1 +
 Documentation/diff-options.adoc               |   3 +-
 Documentation/fetch-options.adoc              |  15 +-
 Documentation/git-am.adoc                     |   3 +-
 Documentation/git-backfill.adoc               |   3 +-
 Documentation/git-cat-file.adoc               |   6 +-
 Documentation/git-check-attr.adoc             |   3 +-
 Documentation/git-check-ignore.adoc           |   9 +-
 Documentation/git-check-ref-format.adoc       |   3 +-
 Documentation/git-checkout.adoc               |   2 +-
 Documentation/git-clone.adoc                  |  12 +-
 Documentation/git-commit-graph.adoc           |   3 +-
 Documentation/git-commit.adoc                 |   4 +-
 Documentation/git-config.adoc                 |   3 +-
 Documentation/git-difftool.adoc               |   9 +-
 Documentation/git-fast-import.adoc            |   5 +-
 Documentation/git-fmt-merge-msg.adoc          |   3 +-
 Documentation/git-for-each-ref.adoc           | 264 +++++++++---------
 Documentation/git-format-patch.adoc           |  12 +-
 Documentation/git-fsck.adoc                   |   9 +-
 Documentation/git-gc.adoc                     |   6 +-
 Documentation/git-http-fetch.adoc             |   5 +-
 Documentation/git-index-pack.adoc             |   3 +-
 Documentation/git-log.adoc                    |   6 +-
 Documentation/git-merge-tree.adoc             |   3 +-
 Documentation/git-multi-pack-index.adoc       |   3 +-
 Documentation/git-p4.adoc                     |   1 +
 Documentation/git-pack-objects.adoc           |   3 +-
 Documentation/git-pull.adoc                   |   3 +-
 Documentation/git-push.adoc                   |  18 +-
 Documentation/git-range-diff.adoc             |   3 +-
 Documentation/git-read-tree.adoc              |   3 +-
 Documentation/git-rebase.adoc                 |   2 +-
 Documentation/git-refs.adoc                   |  20 +-
 Documentation/git-reset.adoc                  |   3 +-
 Documentation/git-send-email.adoc             |  30 +-
 Documentation/git-send-pack.adoc              |   3 +-
 Documentation/git-submodule.adoc              |   6 +-
 Documentation/git-svn.adoc                    |   2 +
 Documentation/git-update-index.adoc           |  12 +-
 Documentation/git-upload-pack.adoc            |   3 +-
 Documentation/git-worktree.adoc               |  12 +-
 Documentation/gitprotocol-http.adoc           |   2 +-
 Documentation/gitsubmodules.adoc              |   3 +-
 Documentation/gitweb.conf.adoc                |   2 +-
 Documentation/lint-delimited-sections.perl    |  48 ++++
 Documentation/lint-documentation-style.perl   |  33 +++
 Documentation/lint-gitlink.perl               |   7 +
 Documentation/merge-options.adoc              |   3 +-
 Documentation/mergetools/vimdiff.adoc         |   8 +
 Documentation/scalar.adoc                     |  18 +-
 Documentation/technical/api-path-walk.adoc    |   5 +-
 .../long-running-process-protocol.adoc        |   1 +
 shared.mak                                    |   2 +
 57 files changed, 447 insertions(+), 232 deletions(-)
 create mode 100755 Documentation/lint-delimited-sections.perl
 create mode 100755 Documentation/lint-documentation-style.perl


base-commit: 112648dd6bdd8e4f485cd0ae11636807959d48be
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1945%2Fjnavila%2Fdoc_linting-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1945/jnavila/doc_linting-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1945

Range-diff vs v2:

 1:  e79bd6a67ef = 1:  e79bd6a67ef doc: test linkgit macros for well-formedness
 2:  322df2d8dde = 2:  322df2d8dde doc: check well-formedness of delimited sections
 3:  5806390052b ! 3:  4e0178218e8 doc: check for absence of multiple terms in each entry of desc list
     @@ Metadata
       ## Commit message ##
          doc: check for absence of multiple terms in each entry of desc list
      
     -    Due to portability issues, the script generate-configlist.sh was fixed to
     -    not use carriage returns in the output. However, the result is that it no
     -    longer correctly handles multiple terms in a single entry of the definition
     -    list.
     +    For simplifying automated translation of the documentation, it is better to
     +    only present one term in each entry of a description list of options. This
     +    is because most of these terms can automatically be marked as
     +    notranslatable.
      
     -    We now check that these entries do not exist in the documentation.
     +    Also, due to portability issues, the script generate-configlist.sh can no
     +    longer insert newlines in the output. However, the result is that it no
     +    longer correctly handles multiple terms in a single entry of definition
     +    lists.
      
     +    As a result, we now check that these entries do not exist in the
     +    documentation.
     +
     +    Reviewed-by: Collin Funk <collin.funk1@gmail.com>
          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Documentation/Makefile ##
     @@ Documentation/Makefile: $(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimi
       lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS)
       
      +## Lint: Documentation style
     -+LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(MAN_TXT))
     ++LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(DOC_DEP_TXT))
      +$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl
      +$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc
      +	$(call mkdir_p_parent_template)
     @@ Documentation/git-http-fetch.adoc: commit-id::
               pull.
       
      --a, -c, -t::
     -+-a::-c::
     ++-a::
     ++-c::
      +-t::
       	These options are ignored for historical reasons.
      +
 4:  03a8428849f = 4:  2b43e196ec0 doc: check for absence of the form --[no-]parameter
 5:  713c86dae92 = 5:  c32e74fad94 doc:git-for-each-ref: fix styling and typos
 6:  d57478ea5cd = 6:  8ec969fe4bd doc lint: check that synopsis manpages have synopsis inlines

-- 
gitgitgadget