[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] qemu-nbd: Convert invocation documentation to rST
From: |
Peter Maydell |
Subject: |
Re: [PATCH] qemu-nbd: Convert invocation documentation to rST |
Date: |
Tue, 14 Jan 2020 09:36:25 +0000 |
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