Re: [PATCH] doc/sphinx/hxtool.py: add optional label argument to SRST directive

[Peter Maydell]

On Sat, 27 Jan 2024 at 10:16, David Woodhouse <dwmw2@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