Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

["Hugo Osvaldo Barrera" <hugo@whynothugo.nl>]

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@gmail.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