Re: Intersphinx ([TECH TOPIC] Kernel documentation)

[Linus Torvalds <torvalds@linux-foundation.org>]

On Sat, 1 Jul 2023 at 18:46, Steven Rostedt <rostedt@goodmis.org> wrote:
>
> This is similar to using flex and bison, where I have the files they
> generate prebuilt and checked in so that the user doesn't need to do it
> when they build the repository.

We really strive not to do that in the kernel because it's too painful.

Yes, we used to. It was a disaster.  It's versioning hell with
different people having different tooling versions, so the "shipped"
binaries then end up constantly depending on who generated them if
anybody does any changes. And maintenance gets to be just more
painful.

So I think for lex/yacc we simply always build things now. No shipped copies.

We still have things like the aic7xxx scsi assembler thing that we do
*not* make people build, and so we have shipped pre-built version of
things like that.

But no. We do *not* want to "solve" some documentation thing by
including pre-build data as shipped files. It's a disaster. It always
has been.

It's just really tedious and error-prone and ugly to re-generate them
at random points.

We've been walking away from that broken model, not adding to it. See
commits like 12dd461ebd19, 7c0303ff7e67 for the crypto layer, but
perhaps more relevantly, commit 833e62245943 or 29c833061c1d where we
got rid of some old traditional flex/bison generated files for
Kconfig..

Or commit e039139be8c2 doing the same for dtc files.

IOW, we've been down the 'shipped' file path. It's a mistake. Let's
learn from our past mistakes, and not repeat them.

          Linus