Doc new guidelines

[jnavila]

This version is a simplification of the markup. The behavior is variable, depending on versions of asciidoc[tor], but at least, it works both on my station and in github-ci. @Martin, please check on your platform.

Changes since v1:

• use unconstrained markup ++ for verbatim stuck to emphasis, instead of {empty} trickery
• document and apply markup on man page references
• split git-clone commit into markup and non-autoreference

cc: Martin Ågren martin.agren@gmail.com cc: Jeff King peff@peff.net cc: Eric Sunshine sunshine@sunshineco.com

[jnavila]

/submit

[gitgitgadget[bot]]

Submitted as pull.1702.git.1711318739.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1702/jnavila/doc_new_Guidelines-v1

To fetch this version to local tag pr-1702/jnavila/doc_new_Guidelines-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1702/jnavila/doc_new_Guidelines-v1

[gitgitgadget[bot]]

This branch is now known as ja/doc-markup-updates.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/86ecd93b774d83c97f2e22c44d8368c2f5fe37eb.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/ea6c2f2d27ad755b482635848583e3429d7b338f.

[gitgitgadget[bot]]

There was a status update in the "New Topics" section about the branch ja/doc-markup-updates on the Git mailing list:

Documentation rules has been explicitly described how to mark-up
literal parts and a few manual pages have been updated as examples.

Will merge to 'next'?
source: <pull.1702.git.1711318739.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

User Martin Ågren <martin.agren@gmail.com> has been added to the cc: list.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/ea6bc97d111e461bb7a17e1717714aa68a8e27b8.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/9ac9eaa931829335a31e731b55de879c8bad3a68.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/e3332c67edfc87753aa95d6ebe5f8063da52341d.

[gitgitgadget[bot]]

On the Git mailing list, Jeff King wrote (reply to this), regarding 202ed891463c134904b89a0d746d85bb62338d52 (outdated):

On Sun, Mar 24, 2024 at 10:18:57PM +0000, Jean-Noël Avila via GitGitGadget wrote:

> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
> 
> As the new formatting of literal and placeholders is introduced,
> the synopsis in the man pages can now hold additional markup with
> respect to the command help.
> 
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  t/t0450-txt-doc-vs-help.sh | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
> index cd3969e852b..e47599cbf26 100755
> --- a/t/t0450-txt-doc-vs-help.sh
> +++ b/t/t0450-txt-doc-vs-help.sh
> @@ -59,7 +59,7 @@ txt_to_synopsis () {
>       -e '/^\[verse\]$/,/^$/ {
>           /^$/d;
>           /^\[verse\]$/d;
> -
> +         s/{empty}\|_\|`//g;

It looks like this doesn't work in the macos CI jobs. E.g., this run:

  https://github.com/git/git/actions/runs/8460326247/job/23178326007

produced output from t0450 like:

  +++ diff -u txt help
  --- txt    2024-03-28 00:14:15
  +++ help   2024-03-28 00:14:15
  @@ -1,5 +1,5 @@
  -`git init` [`-q` | `--quiet`] [`--bare`] [`--template=`{empty}__<template-directory>__]
  -         [`--separate-git-dir` _<git-dir>_] [`--object-format=`{empty}__<format>__]
  -         [`--ref-format=`{empty}__<format>__]
  -         [`-b` _<branch-name>_ | `--initial-branch=`{empty}__<branch-name>__]
  -         [`--shared`[`=`{empty}__<permissions>__]] [_<directory>_]
  +git init [-q | --quiet] [--bare] [--template=<template-directory>]
  +         [--separate-git-dir <git-dir>] [--object-format=<format>]
  +         [--ref-format=<format>]
  +         [-b <branch-name> | --initial-branch=<branch-name>]
  +         [--shared[=<permissions>]] [<directory>]

I think the issue is that "|" alternation is not portable. In GNU sed,
doing "\|" with BRE is enough, but in BSD sed you need to enable ERE
with "-E". I'm not sure how portable that is (we do seem to have at
least one instance in t6030, so maybe it's OK). The most basic
alternative is just splitting it like:

  s/{empty}//g;
  s/[_`]//g;

-Peff

[gitgitgadget[bot]]

User Jeff King <peff@peff.net> has been added to the cc: list.

[gitgitgadget[bot]]

On the Git mailing list, Eric Sunshine wrote (reply to this), regarding 202ed891463c134904b89a0d746d85bb62338d52 (outdated):

On Thu, Mar 28, 2024 at 6:07 AM Jeff King <peff@peff.net> wrote:
> On Sun, Mar 24, 2024 at 10:18:57PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> > +                     s/{empty}\|_\|`//g;
>
> It looks like this doesn't work in the macos CI jobs. E.g., this run:
>
> I think the issue is that "|" alternation is not portable. In GNU sed,
> doing "\|" with BRE is enough, but in BSD sed you need to enable ERE
> with "-E". I'm not sure how portable that is (we do seem to have at
> least one instance in t6030, so maybe it's OK). The most basic
> alternative is just splitting it like:

After reading a patch very recently which used `sed -E`, but before
responding that it was not portable and wouldn't work on macOS, I did
a bit of research and was surprised to find that it is POSIX, and that
(at least) relatively recent macOS does support it. I recall that I
also spotted the existing instance in t6030, thus didn't respond after
all.

>   s/{empty}//g;
>   s/[_`]//g;

That said, I'm not sure how recently macOS started supporting `sed
-E`, so what you propose here may be a good idea anyhow; and it's
certainly going to be more portable done this way.

[gitgitgadget[bot]]

User Eric Sunshine <sunshine@sunshineco.com> has been added to the cc: list.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/b139f12a879fd724756c29158113e0a9d91f277a.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/34843d4fa669ed547168a25e96e2d8fe1b98a06c.

[gitgitgadget[bot]]

There was a status update in the "Cooking" section about the branch ja/doc-markup-updates on the Git mailing list:

Documentation rules has been explicitly described how to mark-up
literal parts and a few manual pages have been updated as examples.

Will merge to 'next'?
source: <pull.1702.git.1711318739.gitgitgadget@gmail.com>

[jnavila]

/submit

[gitgitgadget[bot]]

Submitted as pull.1702.v2.git.1711711181.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1702/jnavila/doc_new_Guidelines-v2

To fetch this version to local tag pr-1702/jnavila/doc_new_Guidelines-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1702/jnavila/doc_new_Guidelines-v2

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/eed311f76a207fa19f2978f358bccdf9bf05e82f.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/aa975fd74af6091f8b04f7be6331258730f01f00.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/4aab7c9d5b677386c73e552a2fbca1e380ededf5.

[gitgitgadget[bot]]

This patch series was integrated into next via https://github.com/git/git/commit/69b015d7ce779b7206ebd8354c2457b30cf25514.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/69b015d7ce779b7206ebd8354c2457b30cf25514.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/4aab7c9d5b677386c73e552a2fbca1e380ededf5.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/84371a6dea5ed5bb7101a84b3c2e01d93153bde4.

[gitgitgadget[bot]]

There was a status update in the "Cooking" section about the branch ja/doc-markup-updates on the Git mailing list:

Documentation rules has been explicitly described how to mark-up
literal parts and a few manual pages have been updated as examples.

Will merge to 'master'.
source: <pull.1702.v2.git.1711711181.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/1c8bdf586f649f7115ce75423b889a41cb7cce44.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/8e26e82845f767b1c1e00cc5cf630a599df9e9d4.

[gitgitgadget[bot]]

There was a status update in the "Cooking" section about the branch ja/doc-markup-updates on the Git mailing list:

Documentation rules has been explicitly described how to mark-up
literal parts and a few manual pages have been updated as examples.

Will merge to 'master'.
source: <pull.1702.v2.git.1711711181.gitgitgadget@gmail.com>

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/0de742bee027342b1c27573686a9e70953d40aeb.

[gitgitgadget[bot]]

This patch series was integrated into seen via https://github.com/git/git/commit/58dd7e4b116b1705cd809604a305de173ecc39e4.

[gitgitgadget[bot]]

This patch series was integrated into master via https://github.com/git/git/commit/58dd7e4b116b1705cd809604a305de173ecc39e4.

[gitgitgadget[bot]]

This patch series was integrated into next via https://github.com/git/git/commit/58dd7e4b116b1705cd809604a305de173ecc39e4.

[gitgitgadget[bot]]

Closed via 58dd7e4b116b1705cd809604a305de173ecc39e4.