diff mbox series

[2/4] doc: allow literal and emphasis format in doc vs help tests

Message ID 202ed891463c134904b89a0d746d85bb62338d52.1711318739.git.gitgitgadget@gmail.com (mailing list archive)
State Superseded
Headers show
Series Doc new guidelines | expand

Commit Message

Jean-Noël Avila March 24, 2024, 10:18 p.m. UTC
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(-)

Comments

Jeff King March 28, 2024, 10:06 a.m. UTC | #1
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
Eric Sunshine March 28, 2024, 10:21 a.m. UTC | #2
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.
diff mbox series

Patch

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;
 			s/{litdd}/--/g;
 			s/'\''\(git[ a-z-]*\)'\''/\1/g;