linux-kernel - Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <073bbd39-5173-4f6d-b9a6-0e4259959551@app.fastmail.com>
Date: Thu, 11 Sep 2025 14:16:34 +0200
From: "Hugo Osvaldo Barrera" <hugo@...nothugo.nl>
To: "Bagas Sanjaya" <bagasdotme@...il.com>, "Ard Biesheuvel" <ardb@...nel.org>
Cc: "Linux Kernel Mailing List" <linux-kernel@...r.kernel.org>,
 "Linux Documentation" <linux-doc@...r.kernel.org>,
 "Linux EFI" <linux-efi@...r.kernel.org>, "Jonathan Corbet" <corbet@....net>,
 "Thomas Gleixner" <tglx@...utronix.de>, "Ingo Molnar" <mingo@...hat.com>,
 "Borislav Petkov" <bp@...en8.de>,
 "Dave Hansen" <dave.hansen@...ux.intel.com>, x86@...nel.org,
 "H. Peter Anvin" <hpa@...or.com>
Subject: Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

On Thu, 11 Sep 2025, at 13:50, Bagas Sanjaya wrote:
> On Thu, Sep 11, 2025 at 01:22:54PM +0200, Hugo Osvaldo Barrera wrote:
>> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
>> > On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@...il.com> wrote:
>> >> +.. _pe-coff-entry-point:
>> >> +
>> >> +PE/COFF entry point
>> >> +===================
>> >> +
>> >> +When compiled with ``CONFIG_EFI_STUB=y``, the kernel can be executed as a
>> >> +regular PE/COFF binary. See Documentation/admin-guide/efi-stub.rst for
>> >> +implementation details.
>> >> +
>> 
>> This should be a link rather than a path to the source file.
>
> I think you miss the point of Jon's comment on your original submission [1].
> Long story short, in Sphinx, one would cross-reference to other documentation
> files (so-called internal linking) either with :doc: or :ref: directives. In
> case of kernel docs, there is third and preferred way: simply mentioning the
> full docs path. The latter is preferred as it is simpler and also allows
> building only portion of docs (with make SPHINXDIRS=<dir>) without triggering
> any reference warnings. Hence why I did addressing his comment.
> For more information, see Documentation/doc-guide/sphinx.rst.
>

The RST files are source files to produce documentation in HTML and PDF. If you
write the path to another source file, the resulting HTML files don't have
any link and the reference is completely lost.

Given the path Documentation/admin-guide/efi-stub.rst, if I'm looking at
https://www.kernel.org/doc/html/latest/arch/x86/boot.html, I'd have on idea
where this path is pointing me to.

WRT Jon's comment on the original submission, I do agree that the label
is unnecessary, since we can link to the page directly without a label at
the top.

> Thanks.
>
> [1]: https://lore.kernel.org/all/87ecx1x4su.fsf@trenco.lwn.net/
>
> -- 
> An old man doll... just what I always wanted! - Clara
>
> Attachments:
> * signature.asc

-- 
Hugo