Re: [PATCH 2/5] docs/interop/nbd.txt: Convert to rST

[Peter Maydell]

On Thu, 1 Aug 2024 at 19:39, Eric Blake <eblake@redhat.com> wrote:
>
> On Thu, Aug 01, 2024 at 06:01:28PM GMT, Peter Maydell wrote:
> > Convert nbd.txt to rST format.
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> > ---
> >  MAINTAINERS            |  2 +-
> >  docs/interop/index.rst |  1 +
> >  docs/interop/nbd.rst   | 89 ++++++++++++++++++++++++++++++++++++++++++
> >  docs/interop/nbd.txt   | 72 ----------------------------------
> >  4 files changed, 91 insertions(+), 73 deletions(-)
> >  create mode 100644 docs/interop/nbd.rst
> >  delete mode 100644 docs/interop/nbd.txt
> >
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 2a183fe960b..dd159053dbd 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -3869,7 +3869,7 @@ F: nbd/
> >  F: include/block/nbd*
> >  F: qemu-nbd.*
> >  F: blockdev-nbd.c
> > -F: docs/interop/nbd.txt
> > +F: docs/interop/nbd.rst
>
> Upstream NBD has a link to the nbd.txt page; I'll have to update that
> link to the new name.  Is it worth creating a git symlink so the old
> name remains a stable point to link to (even though it is no longer
> purely text)?

I'm not super enthusiastic about doing that -- we haven't created
symlinks for any of the other document conversions we've done.


> > +The second is related to exposing the source of various extents within
> > +the image, with a single metadata context named::
>
> I'm not an rst expert, so I'm assuming the difference between ending a
> line in : vs :: is intentional and affects the rendering; but as far
> as I can tell, the rendered result worked, so I don't see any problems
> with the patch.

Ending with double-colon is a shorthand for "display a single
colon, and then the following text is a literal block". It has
the same effect as if you used a single colon and then the
normal double-colon-on-its-own-line to mark the literal block.

Some sentence ending in a colon:

::
   This is a literal block, so it's monospaced

-- PMM