Subject: [PATCH v2 0/3] A handful of doc synopsis/options update

From: Junio C Hamano <[email-masked]>
Date: Fri, 2 May 2025 18:15:34 -0700

Continuing what Jean-Noël started with 22293895 (doc: apply synopsis
simplification on git-clone and git-init, 2024-09-24), use more
[synopsis] (rather than [verse]) mark-up and also make sure

 - dashed options in the text, including the heading for enumerated
   dashed options in the OPTIONS section, are `backquoted` to be
   typeset verbatim.

 - both positive and negative variants are spelled out when the
   option is negatable, i.e. a heading "--[no-]opt::" is separated
   into "--opt::" and "--no-opt::", to help grep hit with simpler
   patterns.

 - non-options are not described in the OPTIONS section.

The changes in the first two patches are unchanged.

The update to "git daemon" documentation has acquired a bit more
`literal` mark-ups, prompted by a comment by Eric Sunshine on the
previous iteration.

The initial iteration contained a WIP on worktree documentation,
which has been dropped in this iteration.

1:  65a5556d4b = 1:  5e8ae75a6b git-verify-* doc: update mark-up of synopsis option descriptions
2:  a9c5bd63ee = 2:  c6cc44c72b git-{var,write-tree} docs: update mark-up of synopsis option descriptions
3:  eb0e783e21 ! 3:  d424d8c846 git-daemon doc: update mark-up of synopsis option descriptions
    @@ Documentation/git-daemon.adoc: git-daemon - A really simple server for Git repos
      
      DESCRIPTION
      -----------
    +@@ Documentation/git-daemon.adoc: that service if it is enabled.
    + It verifies that the directory has the magic file "git-daemon-export-ok", and
    + it will refuse to export any Git directory that hasn't explicitly been marked
    + for export this way (unless the `--export-all` parameter is specified). If you
    +-pass some directory paths as 'git daemon' arguments, the offers are limited to
    ++pass some directory paths as `git daemon` arguments, the offers are limited to
    + repositories within those directories.
    + 
    + By default, only `upload-pack` service is enabled, which serves
     @@ Documentation/git-daemon.adoc: An `upload-archive` also exists to serve 'git archive'.
      
      OPTIONS
    @@ Documentation/git-daemon.adoc: An `upload-archive` also exists to serve 'git arc
     +`--strict-paths`::
      	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
      	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
    - 	'git daemon' will refuse to start when this option is enabled and no
    +-	'git daemon' will refuse to start when this option is enabled and no
    ++	`git daemon` will refuse to start when this option is enabled and no
      	directory arguments are provided.
      
     ---base-path=<path>::
     +`--base-path=<path>`::
      	Remap all the path requests as relative to the given path.
    - 	This is sort of "Git root" - if you run 'git daemon' with
    - 	'--base-path=/srv/git' on example.com, then if you later try to pull
    - 	'git://example.com/hello.git', 'git daemon' will interpret the path
    - 	as `/srv/git/hello.git`.
    +-	This is sort of "Git root" - if you run 'git daemon' with
    +-	'--base-path=/srv/git' on example.com, then if you later try to pull
    +-	'git://example.com/hello.git', 'git daemon' will interpret the path
    +-	as `/srv/git/hello.git`.
    ++	This is sort of "Git root" - if you run `git daemon` with
    ++	`--base-path=/srv/git` on `example.com`, then if you later try
    ++	to pull from `git://example.com/hello.git`, `git daemon` will
    ++	interpret the path as `/srv/git/hello.git`.
      
     ---base-path-relaxed::
     -	If --base-path is enabled and repo lookup fails, with this option

Junio C Hamano (3):
  git-verify-* doc: update mark-up of synopsis option descriptions
  git-{var,write-tree} docs: update mark-up of synopsis option
    descriptions
  git-daemon doc: update mark-up of synopsis option descriptions

 Documentation/git-daemon.adoc        | 119 ++++++++++++++-------------
 Documentation/git-var.adoc           |   6 +-
 Documentation/git-verify-commit.adoc |  16 ++--
 Documentation/git-verify-pack.adoc   |  28 +++----
 Documentation/git-verify-tag.adoc    |  16 ++--
 Documentation/git-write-tree.adoc    |  16 ++--
 6 files changed, 97 insertions(+), 104 deletions(-)

-- 
2.49.0-601-ga5925c3955