On Sat, 27 Jan 2024 at 10:16, David Woodhouse <dw...@infradead.org> wrote: > > On Tue, 2023-12-12 at 15:04 +0000, Peter Maydell wrote: > > > > > --- a/docs/system/i386/xen.rst > > > +++ b/docs/system/i386/xen.rst > > > @@ -132,7 +132,7 @@ The example above provides the guest kernel command > > > line after a separator > > > (" ``--`` ") on the Xen command line, and does not provide the guest > > > kernel > > > with an actual initramfs, which would need to listed as a second > > > multiboot > > > module. For more complicated alternatives, see the command line > > > -documentation for the ``-initrd`` option. > > > +:ref:`documentation <initrd-reference-label>` for the ``-initrd`` option. > > > > I think we should include the hxfile basename in the label name > > we generate. We also don't need to say "label", it's implicitly a > > label. Then when we refer to things we can say > > <qemu-options-initrd> > > <hmp-commands-screendump> > > > > and it's fairly readable what we're referring back to. > > > > (We could alternatively have the emitrefs option take an argument > > for what to use in label names. I don't have a strong view on > > which would be better.) > > Hm, wait... I did this as you suggest in v2 but can I also use this > trick to eliminate the 'emitrefs' option altogether? > > Remember, the problem was that qemu-options.hx gets included *both* > from invocation.rst and from qemu-manpage.rst, so the label gets > emitted twice and is thus ambiguous. The 'emitrefs' option prevented it > from being emitted, but is one more hoop to jump through for the next > person who wants to use this facility. As I mentioned the 'emitrefs' > flag in the documentation, the "if it needs documenting, FIX IT" > instinct kicked in hard... > > What if we build the top-level filename into the label, e.g. > invocation-qemu-options-initrd > > Then we don't need 'emitrefs' at all.
Yeah, that seems like a reasonable approach too: the label name gets a bit longer and clunkier but avoiding the need to have to say specifically "emit labels like this" is nice. -- PMM