Re: [PATCH] qemu-nbd: Convert invocation documentation to rST

[Peter Maydell]

On Mon, 13 Jan 2020 at 19:58, Eric Blake <address@hidden> wrote:
>
> On 1/13/20 12:08 PM, Peter Maydell wrote:
> > The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo
> > format, which we present to the user as:
> >   * a qemu-nbd manpage
> >   * a section of the main qemu-doc HTML documentation
> >
> > Convert the documentation to rST format, and present it to the user as:
> >   * a qemu-nbd manpage
> >   * part of the interop/ Sphinx manual
> >
> > This follows the same pattern as commit 27a296fce982 did for the
> > qemu-ga manpage.
> >
>
> I'm not an rST expert, but trust that you compared the resulting
> renderings.  Is there a quick recipe for doing the build locally so I
> can easily inspect local artifacts myself?

Yep -- assuming you have the prerequisites installed to
build the docs (should be just makeinfo, pod2man, sphinx),
apply the patch and then 'make' will build the docs -- the new
qemu-nbd.8 should be in docs/interop in the build tree,
assuming you do builds not in the source tree. If you do
builds in the source tree then the built artefacts
are created under docs/built. The html that forms part of
the interop manpage set is in docs/interop/qemu-nbd.html,
also in the build tree.

> > +++ b/Makefile
> > @@ -338,7 +338,7 @@ MANUAL_BUILDDIR := docs
> >   endif
> >
> >   ifdef BUILD_DOCS
> > -DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 
> > $(MANUAL_BUILDDIR)/interop/qemu-ga.8
> > +DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 
> > $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 $(MANUAL_BUILDDIR)/interop/qemu-ga.8
>
> Worth splitting this long line, either with \-newline, or
>
> >   DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt 
> > docs/interop/qemu-qmp-ref.7
> >   DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt 
> > docs/interop/qemu-ga-ref.7
>
> with additional DOCS+= lines?

I think I prefer the latter.

> > +++ b/MAINTAINERS
> > @@ -2503,6 +2503,7 @@ F: include/block/nbd*
> >   F: qemu-nbd.*
> >   F: blockdev-nbd.c
> >   F: docs/interop/nbd.txt
> > +F: docs/interop/qemu-nbd.rst
> >   T: git https://repo.or.cz/qemu/ericb.git nbd
>
> Would I be taking this patch through my NBD tree, or would you be
> bundling it with other doc patches?

Either way would work for me, depends a bit whether I
get round to trying to do another doc conversion
and whether you had any other pending updates to the
old texinfo doc.

> > +++ b/docs/interop/qemu-nbd.rst
> > @@ -0,0 +1,263 @@
>
> > +.. option:: -s, --snapshot
> > +
> > +  Use *filename* as an external snapshot, create a temporary
> > +  file with ``backing_file=``\ *filename*, redirect the write to
> > +  the temporary one.
>
> Pre-existing poor grammar. Better might be:
>
> Use *filename* as an external snapshot, by creating a temporary file
> with ``backing_file=``\ *filename*, and redirecting writes to the
> temporary file.
>
> But that could also be done as a separate patch, to keep this one as
> mechanical as possible on the conversion.

Yes. I noticed a few things I would consider docs nits
which I deliberately didn't fix up in this conversion patch;
I'd prefer those to be done separately afterwards.

thanks
-- PMM