Received-SPF: pass (google.com: domain of linux-kernel+bounces-39213-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
From: Jonathan Corbet <corbet@lwn.net>
To: Anna-Maria Behnsen <anna-maria@linutronix.de>, Randy Dunlap
 <rdunlap@infradead.org>, linux-kernel@vger.kernel.org
Cc: Thomas Gleixner <tglx@linutronix.de>, Frederic Weisbecker
 <frederic@kernel.org>, Ingo Molnar <mingo@kernel.org>, John Stultz
 <jstultz@google.com>, Stephen Boyd <sboyd@kernel.org>, Clemens Ladisch
 <clemens@ladisch.de>, linux-doc@vger.kernel.org
Subject: Re: [PATCH 6/8] Documentation: Create a new folder for all timer
 internals
In-Reply-To: <87zfwtbbjd.fsf@somnus>
References: <20240123164702.55612-1-anna-maria@linutronix.de>
 <20240123164702.55612-7-anna-maria@linutronix.de>
 <8eac7bf0-86c5-43ef-99e0-0896c994184a@infradead.org>
 <87o7d9d7dd.fsf@somnus> <87plxpbgpz.fsf@meer.lwn.net>
 <87zfwtbbjd.fsf@somnus>
Date: Thu, 25 Jan 2024 12:50:55 -0700
Message-ID: <87r0i59ops.fsf@meer.lwn.net>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain

Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

>> I've thought for a while that we should have a standard warning or two
>> along these lines, like Wikipedia does, but of course haven't done
>> anything about it.
>>
>
> Sure, if we could standardize it, I would definitely prefere it! For me
> as a not sphinx/rst/... expert, it would be great if only something like
>
> .. might_be_outdated:: <optional additional text>
>
> needs to be added to the code. And then the default lines would appear
> together with the optional additional text.
>
> Is this what you have been thinking about?

You've already put more thought into it than I have :)

I was just thinking in terms of some relatively standard text.  I'd
rather not create an extension just for this, but Jani's idea of using
the todo extension could work, or just a convention like:

  .. include crufty-stuff-note.rst

might be good enough and not require an extension at all.

Thanks,

jon