From: "Jean-Noël Avila" <jn.avila@free•fr>
To: Junio C Hamano <gitster@pobox•com>,
"D. Ben Knoble" <ben.knoble+github@gmail•com>
Cc: git@vger•kernel.org, Christian Couder <chriscool@tuxfamily•org>,
Kristoffer Haugsbakk <code@khaugsbakk•name>,
Elijah Newren <newren@gmail•com>,
"brian m. carlson" <sandals@crustytoothpaste•net>,
Sergey Organov <sorganov@gmail•com>
Subject: Re: [PATCH] replay: drop rev-list formatting options from manual
Date: Wed, 21 Jan 2026 14:27:05 +0100 [thread overview]
Message-ID: <adfdcc47-470a-4424-9268-31699decee16@free.fr> (raw)
In-Reply-To: <xmqqy0lrx4l2.fsf@gitster.g>
Le 21/01/2026 à 00:11, Junio C Hamano a écrit :
> Junio C Hamano <gitster@pobox•com> writes:
>
>> Junio C Hamano <gitster@pobox•com> writes:
>>
>>> "D. Ben Knoble" <ben.knoble+github@gmail•com> writes:
>>>
>>>> If I've understood all that correctly, then I have the Python version
>>>> installed for building Git and it understood the syntax. Given that
>>>> the Ruby version is newer, I think it should also work against the
>>>> spec.
>>>
>>> We have CI jobs to catch the differences so hopefully we know soon
>>> enough if one is so badly broken ;-)
>>>
>>> Thanks.
>>
>> We didn't have to wait for CI jobs. You can try
>>
>> make -C Documentation lint-docs
>>
>> which reveals that somebody is not expecting these multiple things
>> there. I think Documentation/lint-gitlink.perl needs updating.
>
> Perhaps something like this. Haven't thought things through to spot
> negative ramifications, though.
>
> The original comes from f81a574f (doc: test linkgit macros for
> well-formedness, 2025-08-11); its author Cc'ed for better ideas.
>
The initial motive for this script was to catch malformed linkgit
occurrences that were present in the docs: stray git-foo[1], without
the linkgit macro and misnamed gitlink:git-foo[1]. Not knowing what
would come next, the regex was coined very broad, with the assumed risk
of raising false positives.
The issue here is in handling the ifdef macros which are block macros
and are more easily detected as such. I would reject preemtively lines
with '^ifn?def::' instead.
----- >8 -----
Subject: [PATCH] lint-gitlink: preemptively ignore all /ifn?def|endif/ macros
Instead of testing if the macro name is ifn?def:: as if it were a inline
macro, it is faster and safer to just ignore such block macro lines before
hand.
Signed-off-by: Jean-Noël Avila <jn.avila@free•fr>
---
Documentation/lint-gitlink.perl | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
index f183a18df..b5d982e8e 100755
--- a/Documentation/lint-gitlink.perl
+++ b/Documentation/lint-gitlink.perl
@@ -41,10 +41,11 @@ sub report {
@ARGV = $to_check;
while (<>) {
my $line = $_;
+ next if $line =~ /^\s*(ifn?def|endif)::/;
while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) {
my $pos = pos $line;
my ($macro, $target, $page, $section) = ($1, $2, $3, $4);
- if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) {
+ if ( $macro ne "linkgit:" ) {
report($pos, $line, $target, "linkgit: macro expected");
}
}
next prev parent reply other threads:[~2026-01-21 13:27 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-01-20 1:47 [PATCH] replay: drop rev-list formatting options from manual D. Ben Knoble
2026-01-20 2:19 ` Junio C Hamano
2026-01-20 14:04 ` D. Ben Knoble
2026-01-20 15:37 ` Junio C Hamano
2026-01-20 21:49 ` Junio C Hamano
2026-01-20 23:11 ` Junio C Hamano
2026-01-21 13:27 ` Jean-Noël Avila [this message]
2026-01-21 16:26 ` Junio C Hamano
2026-01-21 20:03 ` D. Ben Knoble
2026-01-27 18:48 ` D. Ben Knoble
2026-01-20 14:05 ` [PATCH v2] " D. Ben Knoble
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=adfdcc47-470a-4424-9268-31699decee16@free.fr \
--to=jn.avila@free$(echo .)fr \
--cc=ben.knoble+github@gmail$(echo .)com \
--cc=chriscool@tuxfamily$(echo .)org \
--cc=code@khaugsbakk$(echo .)name \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=newren@gmail$(echo .)com \
--cc=sandals@crustytoothpaste$(echo .)net \
--cc=sorganov@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox