diff mbox series

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

Message ID 20240801170131.3977807-3-peter.maydell@linaro.org
State Superseded
Headers show
Series docs: more conversions from txt to rst | expand

Commit Message

Peter Maydell Aug. 1, 2024, 5:01 p.m. UTC
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

Comments

Eric Blake Aug. 1, 2024, 6:38 p.m. UTC | #1
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)?

>  F: docs/tools/qemu-nbd.rst
>  F: tests/qemu-iotests/tests/*nbd*
>  T: git https://repo.or.cz/qemu/ericb.git nbd
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index ed65395bfb2..b9ceaabc648 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -14,6 +14,7 @@ are useful for making QEMU interoperate with other software.
>     dbus-vmstate
>     dbus-display
>     live-block-operations
> +   nbd
>     pr-helper
>     qmp-spec
>     qemu-ga
> diff --git a/docs/interop/nbd.rst b/docs/interop/nbd.rst
> new file mode 100644
> index 00000000000..de079d31fd8
> --- /dev/null
> +++ b/docs/interop/nbd.rst
> @@ -0,0 +1,89 @@
> +QEMU NBD protocol support
> +=========================
> +
> +QEMU supports the NBD protocol, and has an internal NBD client (see
> +``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an
> +external NBD server tool (see ``qemu-nbd.c``). The common code is placed
> +in ``nbd/*``.

Accurate translation, and accurate information although incomplete -
maybe I should do a followup patch to mention that qemu-storage-daemon
can also expose an NBD server?  Doesn't affect review of this patch.

> +
> +The NBD protocol is specified here:
> +https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
> +
> +The following paragraphs describe some specific properties of NBD
> +protocol realization in QEMU.
> +
> +Metadata namespaces
> +-------------------
> +
> +QEMU supports the ``base:allocation`` metadata context as defined in the
> +NBD protocol specification, and also defines an additional metadata
> +namespace ``qemu``.
> +
> +``qemu`` namespace
> +------------------
> +
> +The ``qemu`` namespace currently contains two available metadata context
> +types.  The first is related to exposing the contents of a dirty
> +bitmap alongside the associated disk contents.  That metadata context
> +is named with the following form::
> +
> +    qemu:dirty-bitmap:<dirty-bitmap-export-name>
> +
> +Each dirty-bitmap metadata context defines only one flag for extents
> +in reply for ``NBD_CMD_BLOCK_STATUS``:
> +
> +bit 0:
> +  ``NBD_STATE_DIRTY``, set when the extent is "dirty"
> +
> +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.

Reviewed-by: Eric Blake <eblake@redhat.com>
Peter Maydell Aug. 2, 2024, 8:39 a.m. UTC | #2
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
Eric Blake Aug. 2, 2024, 1:29 p.m. UTC | #3
On Fri, Aug 02, 2024 at 09:39:41AM GMT, Peter Maydell wrote:
> 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.
> > >
> > > -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.

Okay, a stability symlink is not necessary.  Currently, the NBD spec
points to the raw qemu.txt because nothing is rendered into our online
pages; but I plan to instead point it into the rendered version
reachable from https://www.qemu.org/docs/master/interop/index.html
once your patch lands.  I also found a typo in that page (right next
to where nbd will appear), so I'm submitting that patch as a followup
to this thread, if that's okay.
diff mbox series

Patch

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
 F: docs/tools/qemu-nbd.rst
 F: tests/qemu-iotests/tests/*nbd*
 T: git https://repo.or.cz/qemu/ericb.git nbd
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index ed65395bfb2..b9ceaabc648 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -14,6 +14,7 @@  are useful for making QEMU interoperate with other software.
    dbus-vmstate
    dbus-display
    live-block-operations
+   nbd
    pr-helper
    qmp-spec
    qemu-ga
diff --git a/docs/interop/nbd.rst b/docs/interop/nbd.rst
new file mode 100644
index 00000000000..de079d31fd8
--- /dev/null
+++ b/docs/interop/nbd.rst
@@ -0,0 +1,89 @@ 
+QEMU NBD protocol support
+=========================
+
+QEMU supports the NBD protocol, and has an internal NBD client (see
+``block/nbd.c``), an internal NBD server (see ``blockdev-nbd.c``), and an
+external NBD server tool (see ``qemu-nbd.c``). The common code is placed
+in ``nbd/*``.
+
+The NBD protocol is specified here:
+https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
+
+The following paragraphs describe some specific properties of NBD
+protocol realization in QEMU.
+
+Metadata namespaces
+-------------------
+
+QEMU supports the ``base:allocation`` metadata context as defined in the
+NBD protocol specification, and also defines an additional metadata
+namespace ``qemu``.
+
+``qemu`` namespace
+------------------
+
+The ``qemu`` namespace currently contains two available metadata context
+types.  The first is related to exposing the contents of a dirty
+bitmap alongside the associated disk contents.  That metadata context
+is named with the following form::
+
+    qemu:dirty-bitmap:<dirty-bitmap-export-name>
+
+Each dirty-bitmap metadata context defines only one flag for extents
+in reply for ``NBD_CMD_BLOCK_STATUS``:
+
+bit 0:
+  ``NBD_STATE_DIRTY``, set when the extent is "dirty"
+
+The second is related to exposing the source of various extents within
+the image, with a single metadata context named::
+
+    qemu:allocation-depth
+
+In the allocation depth context, the entire 32-bit value represents a
+depth of which layer in a thin-provisioned backing chain provided the
+data (0 for unallocated, 1 for the active layer, 2 for the first
+backing layer, and so forth).
+
+For ``NBD_OPT_LIST_META_CONTEXT`` the following queries are supported
+in addition to the specific ``qemu:allocation-depth`` and
+``qemu:dirty-bitmap:<dirty-bitmap-export-name>``:
+
+``qemu:``
+  returns list of all available metadata contexts in the namespace
+``qemu:dirty-bitmap:``
+  returns list of all available dirty-bitmap metadata contexts
+
+Features by version
+-------------------
+
+The following list documents which qemu version first implemented
+various features (both as a server exposing the feature, and as a
+client taking advantage of the feature when present), to make it
+easier to plan for cross-version interoperability.  Note that in
+several cases, the initial release containing a feature may require
+additional patches from the corresponding stable branch to fix bugs in
+the operation of that feature.
+
+2.6
+  ``NBD_OPT_STARTTLS`` with TLS X.509 Certificates
+2.8
+  ``NBD_CMD_WRITE_ZEROES``
+2.10
+  ``NBD_OPT_GO``, ``NBD_INFO_BLOCK``
+2.11
+  ``NBD_OPT_STRUCTURED_REPLY``
+2.12
+  ``NBD_CMD_BLOCK_STATUS`` for ``base:allocation``
+3.0
+  ``NBD_OPT_STARTTLS`` with TLS Pre-Shared Keys (PSK),
+  ``NBD_CMD_BLOCK_STATUS`` for ``qemu:dirty-bitmap:``, ``NBD_CMD_CACHE``
+4.2
+  ``NBD_FLAG_CAN_MULTI_CONN`` for shareable read-only exports,
+  ``NBD_CMD_FLAG_FAST_ZERO``
+5.2
+  ``NBD_CMD_BLOCK_STATUS`` for ``qemu:allocation-depth``
+7.1
+  ``NBD_FLAG_CAN_MULTI_CONN`` for shareable writable exports
+8.2
+  ``NBD_OPT_EXTENDED_HEADERS``, ``NBD_FLAG_BLOCK_STATUS_PAYLOAD``
diff --git a/docs/interop/nbd.txt b/docs/interop/nbd.txt
deleted file mode 100644
index 18efb251de9..00000000000
--- a/docs/interop/nbd.txt
+++ /dev/null
@@ -1,72 +0,0 @@ 
-QEMU supports the NBD protocol, and has an internal NBD client (see
-block/nbd.c), an internal NBD server (see blockdev-nbd.c), and an
-external NBD server tool (see qemu-nbd.c). The common code is placed
-in nbd/*.
-
-The NBD protocol is specified here:
-https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md
-
-The following paragraphs describe some specific properties of NBD
-protocol realization in QEMU.
-
-= Metadata namespaces =
-
-QEMU supports the "base:allocation" metadata context as defined in the
-NBD protocol specification, and also defines an additional metadata
-namespace "qemu".
-
-== "qemu" namespace ==
-
-The "qemu" namespace currently contains two available metadata context
-types.  The first is related to exposing the contents of a dirty
-bitmap alongside the associated disk contents.  That metadata context
-is named with the following form:
-
-    qemu:dirty-bitmap:<dirty-bitmap-export-name>
-
-Each dirty-bitmap metadata context defines only one flag for extents
-in reply for NBD_CMD_BLOCK_STATUS:
-
-    bit 0: NBD_STATE_DIRTY, set when the extent is "dirty"
-
-The second is related to exposing the source of various extents within
-the image, with a single metadata context named:
-
-    qemu:allocation-depth
-
-In the allocation depth context, the entire 32-bit value represents a
-depth of which layer in a thin-provisioned backing chain provided the
-data (0 for unallocated, 1 for the active layer, 2 for the first
-backing layer, and so forth).
-
-For NBD_OPT_LIST_META_CONTEXT the following queries are supported
-in addition to the specific "qemu:allocation-depth" and
-"qemu:dirty-bitmap:<dirty-bitmap-export-name>":
-
-* "qemu:" - returns list of all available metadata contexts in the
-            namespace.
-* "qemu:dirty-bitmap:" - returns list of all available dirty-bitmap
-                         metadata contexts.
-
-= Features by version =
-
-The following list documents which qemu version first implemented
-various features (both as a server exposing the feature, and as a
-client taking advantage of the feature when present), to make it
-easier to plan for cross-version interoperability.  Note that in
-several cases, the initial release containing a feature may require
-additional patches from the corresponding stable branch to fix bugs in
-the operation of that feature.
-
-* 2.6: NBD_OPT_STARTTLS with TLS X.509 Certificates
-* 2.8: NBD_CMD_WRITE_ZEROES
-* 2.10: NBD_OPT_GO, NBD_INFO_BLOCK
-* 2.11: NBD_OPT_STRUCTURED_REPLY
-* 2.12: NBD_CMD_BLOCK_STATUS for "base:allocation"
-* 3.0: NBD_OPT_STARTTLS with TLS Pre-Shared Keys (PSK),
-NBD_CMD_BLOCK_STATUS for "qemu:dirty-bitmap:", NBD_CMD_CACHE
-* 4.2: NBD_FLAG_CAN_MULTI_CONN for shareable read-only exports,
-NBD_CMD_FLAG_FAST_ZERO
-* 5.2: NBD_CMD_BLOCK_STATUS for "qemu:allocation-depth"
-* 7.1: NBD_FLAG_CAN_MULTI_CONN for shareable writable exports
-* 8.2: NBD_OPT_EXTENDED_HEADERS, NBD_FLAG_BLOCK_STATUS_PAYLOAD