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.
smime.p7s
Description: S/MIME cryptographic signature
