Convert qemu-ga-ref to rST format. This includes dropping
the plain-text, pdf and info format outputs for this document;
as with all our other Sphinx-based documentation, we provide
HTML and manpage only.
The qemu-ga-ref.rst is somewhat more stripped down than
the .texi was, because we do not (currently) attempt to
generate indexes for the commands, events and data types
being documented.
As the GA ref is now part of the Sphinx 'interop' manual,
we can delete the direct link from index.html.in.
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/index.html.in | 1 -
docs/interop/conf.py | 2 +
docs/interop/index.rst | 1 +
docs/interop/qemu-ga-ref.rst | 4 ++
docs/interop/qemu-ga-ref.texi | 80 -----------------------------------
Makefile | 42 ++++++++----------
MAINTAINERS | 2 +-
7 files changed, 25 insertions(+), 107 deletions(-)
create mode 100644 docs/interop/qemu-ga-ref.rst
delete mode 100644 docs/interop/qemu-ga-ref.texi
diff --git a/docs/index.html.in b/docs/index.html.in
index 6736fa4360c..99d4d8075fc 100644
--- a/docs/index.html.in
+++ b/docs/index.html.in
@@ -13,7 +13,6 @@
<li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li>
<li><a href="specs/index.html">System Emulation Guest Hardware Specifications</a></li>
<li><a href="interop/qemu-qmp-ref.html">QMP Reference Manual</a></li>
- <li><a href="interop/qemu-ga-ref.html">Guest Agent Protocol Reference</a></li>
</ul>
</body>
</html>
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index 42ce7e3d365..e83632e0108 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -19,4 +19,6 @@ html_theme_options['description'] = u'System Emulation Management and Interopera
man_pages = [
('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
+ ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference',
+ [], 7),
]
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index 006f9864208..738cdbe185e 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -18,6 +18,7 @@ Contents:
live-block-operations
pr-helper
qemu-ga
+ qemu-ga-ref
vhost-user
vhost-user-gpu
vhost-vdpa
diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst
new file mode 100644
index 00000000000..013eac0bb53
--- /dev/null
+++ b/docs/interop/qemu-ga-ref.rst
@@ -0,0 +1,4 @@
+QEMU Guest Agent Protocol Reference
+===================================
+
+.. qapi-doc:: qga/qapi-schema.json
diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi
deleted file mode 100644
index ddb76ce1c2a..00000000000
--- a/docs/interop/qemu-ga-ref.texi
+++ /dev/null
@@ -1,80 +0,0 @@
-\input texinfo
-@setfilename qemu-ga-ref.info
-
-@include version.texi
-
-@exampleindent 0
-@paragraphindent 0
-
-@settitle QEMU Guest Agent Protocol Reference
-
-@iftex
-@center @image{docs/qemu_logo}
-@end iftex
-
-@copying
-This is the QEMU Guest Agent Protocol reference manual.
-
-Copyright @copyright{} 2016 The QEMU Project developers
-
-@quotation
-This manual is free documentation: you can redistribute it and/or
-modify it under the terms of the GNU General Public License as
-published by the Free Software Foundation, either version 2 of the
-License, or (at your option) any later version.
-
-This manual is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this manual. If not, see http://www.gnu.org/licenses/.
-@end quotation
-@end copying
-
-@dircategory QEMU
-@direntry
-* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference
-@end direntry
-
-@titlepage
-@title Guest Agent Protocol Reference Manual
-@subtitle QEMU version @value{VERSION}
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@contents
-
-@ifnottex
-@node Top
-@top QEMU Guest Agent protocol reference
-@end ifnottex
-
-@menu
-* API Reference::
-* Commands and Events Index::
-* Data Types Index::
-@end menu
-
-@node API Reference
-@chapter API Reference
-
-@c for texi2pod:
-@c man begin DESCRIPTION
-
-@include qemu-ga-qapi.texi
-
-@c man end
-
-@node Commands and Events Index
-@unnumbered Commands and Events Index
-@printindex fn
-
-@node Data Types Index
-@unnumbered Data Types Index
-@printindex tp
-
-@bye
diff --git a/Makefile b/Makefile
index 13dd708c4af..f0cca10b427 100644
--- a/Makefile
+++ b/Makefile
@@ -371,7 +371,7 @@ DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1
endif
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
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
+DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7
DOCS+=$(MANUAL_BUILDDIR)/index.html
ifdef CONFIG_VIRTFS
@@ -800,11 +800,11 @@ distclean: clean
rm -f config.log
rm -f linux-headers/asm
rm -f docs/version.texi
- rm -f docs/interop/qemu-ga-qapi.texi docs/interop/qemu-qmp-qapi.texi
- rm -f docs/interop/qemu-qmp-ref.7 docs/interop/qemu-ga-ref.7
- rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
- rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
- rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
+ rm -f docs/interop/qemu-qmp-qapi.texi
+ rm -f docs/interop/qemu-qmp-ref.7
+ rm -f docs/interop/qemu-qmp-ref.txt
+ rm -f docs/interop/qemu-qmp-ref.pdf
+ rm -f docs/interop/qemu-qmp-ref.html
rm -rf .doctrees
$(call clean-manual,devel)
$(call clean-manual,interop)
@@ -858,7 +858,7 @@ endif
# and also any sphinx-built manpages.
define install-manual =
for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
-for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
+for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
endef
# Note that we deliberately do not install the "devel" manual: it is
@@ -894,10 +894,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP
endif
ifneq (,$(findstring qemu-ga,$(TOOLS)))
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
- $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/interop"
- $(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)/interop"
- $(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)/interop"
- $(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
+ $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
endif
endif
ifdef CONFIG_VIRTFS
@@ -1090,7 +1087,7 @@ endef
$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
$(call build-manual,devel,html)
-$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
+$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qga/qapi-schema.json $(qapi-py)
$(call build-manual,interop,html)
$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
@@ -1105,7 +1102,10 @@ $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-
$(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user)
$(call build-manual,user,html)
-$(call define-manpage-rule,interop,qemu-ga.8)
+$(call define-manpage-rule,interop,\
+ qemu-ga.8 qemu-ga-ref.7,\
+ $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \
+ $(qapi-py))
$(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-models.7)
@@ -1122,18 +1122,10 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
@cp -p $< $@
-docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
- @cp -p $< $@
-
-html: docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
-info: docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
-pdf: docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
-txt: docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
-
-docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
- docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
- docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7: \
- docs/interop/qemu-ga-ref.texi docs/interop/qemu-ga-qapi.texi
+html: docs/interop/qemu-qmp-ref.html sphinxdocs
+info: docs/interop/qemu-qmp-ref.info
+pdf: docs/interop/qemu-qmp-ref.pdf
+txt: docs/interop/qemu-qmp-ref.txt
docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \
docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \
diff --git a/MAINTAINERS b/MAINTAINERS
index fdd38f412d7..6eae3625733 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2394,9 +2394,9 @@ M: Michael Roth <mdroth@linux.vnet.ibm.com>
S: Maintained
F: qga/
F: docs/interop/qemu-ga.rst
+F: docs/interop/qemu-ga-ref.rst
F: scripts/qemu-guest-agent/
F: tests/test-qga.c
-F: docs/interop/qemu-ga-ref.texi
T: git https://github.com/mdroth/qemu.git qga
QOM
--
2.20.1
Peter Maydell <peter.maydell@linaro.org> writes:
> Convert qemu-ga-ref to rST format. This includes dropping
> the plain-text, pdf and info format outputs for this document;
> as with all our other Sphinx-based documentation, we provide
> HTML and manpage only.
>
> The qemu-ga-ref.rst is somewhat more stripped down than
> the .texi was, because we do not (currently) attempt to
> generate indexes for the commands, events and data types
> being documented.
I'll miss the plain text output (I may get by with formatting the man
output, but even if that works, it's still an extra step). Others may
miss the index. Oh well, march of progress.
> As the GA ref is now part of the Sphinx 'interop' manual,
> we can delete the direct link from index.html.in.
>
> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
[...]
> diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst
> new file mode 100644
> index 00000000000..013eac0bb53
> --- /dev/null
> +++ b/docs/interop/qemu-ga-ref.rst
> @@ -0,0 +1,4 @@
> +QEMU Guest Agent Protocol Reference
> +===================================
> +
> +.. qapi-doc:: qga/qapi-schema.json
> diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi
> deleted file mode 100644
> index ddb76ce1c2a..00000000000
> --- a/docs/interop/qemu-ga-ref.texi
> +++ /dev/null
> @@ -1,80 +0,0 @@
> -\input texinfo
> -@setfilename qemu-ga-ref.info
> -
> -@include version.texi
> -
> -@exampleindent 0
> -@paragraphindent 0
> -
> -@settitle QEMU Guest Agent Protocol Reference
> -
> -@iftex
> -@center @image{docs/qemu_logo}
> -@end iftex
> -
> -@copying
> -This is the QEMU Guest Agent Protocol reference manual.
> -
> -Copyright @copyright{} 2016 The QEMU Project developers
> -
> -@quotation
> -This manual is free documentation: you can redistribute it and/or
> -modify it under the terms of the GNU General Public License as
> -published by the Free Software Foundation, either version 2 of the
> -License, or (at your option) any later version.
> -
> -This manual is distributed in the hope that it will be useful, but
> -WITHOUT ANY WARRANTY; without even the implied warranty of
> -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
> -General Public License for more details.
> -
> -You should have received a copy of the GNU General Public License
> -along with this manual. If not, see http://www.gnu.org/licenses/.
> -@end quotation
> -@end copying
Does the interop manual carry an equivalent copyright notice?
[...]
> diff --git a/Makefile b/Makefile
> index 13dd708c4af..f0cca10b427 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -371,7 +371,7 @@ DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1
> endif
> DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
> 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
> +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7
> DOCS+=$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7
> DOCS+=$(MANUAL_BUILDDIR)/index.html
> ifdef CONFIG_VIRTFS
> @@ -800,11 +800,11 @@ distclean: clean
> rm -f config.log
> rm -f linux-headers/asm
> rm -f docs/version.texi
> - rm -f docs/interop/qemu-ga-qapi.texi docs/interop/qemu-qmp-qapi.texi
> - rm -f docs/interop/qemu-qmp-ref.7 docs/interop/qemu-ga-ref.7
> - rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
> - rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
> - rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
> + rm -f docs/interop/qemu-qmp-qapi.texi
> + rm -f docs/interop/qemu-qmp-ref.7
> + rm -f docs/interop/qemu-qmp-ref.txt
> + rm -f docs/interop/qemu-qmp-ref.pdf
> + rm -f docs/interop/qemu-qmp-ref.html
> rm -rf .doctrees
> $(call clean-manual,devel)
> $(call clean-manual,interop)
Please update .gitignore. as well.
[...]
Comments apply to the next patch, too.
On Fri, 4 Sep 2020 at 14:16, Markus Armbruster <armbru@redhat.com> wrote: > > Peter Maydell <peter.maydell@linaro.org> writes: > > > Convert qemu-ga-ref to rST format. This includes dropping > > the plain-text, pdf and info format outputs for this document; > > as with all our other Sphinx-based documentation, we provide > > HTML and manpage only. > > > > The qemu-ga-ref.rst is somewhat more stripped down than > > the .texi was, because we do not (currently) attempt to > > generate indexes for the commands, events and data types > > being documented. > > I'll miss the plain text output (I may get by with formatting the man > output, but even if that works, it's still an extra step). Others may > miss the index. Oh well, march of progress. The index is definitely something I'd like to restore at some later date (for all the manuals, not just this one). thanks -- PMM
On Fri, 4 Sep 2020 at 14:16, Markus Armbruster <armbru@redhat.com> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > Convert qemu-ga-ref to rST format. This includes dropping
> > the plain-text, pdf and info format outputs for this document;
> > as with all our other Sphinx-based documentation, we provide
> > HTML and manpage only.
> > -@copying
> > -This is the QEMU Guest Agent Protocol reference manual.
> > -
> > -Copyright @copyright{} 2016 The QEMU Project developers
> > -
> > -@quotation
> > -This manual is free documentation: you can redistribute it and/or
> > -modify it under the terms of the GNU General Public License as
> > -published by the Free Software Foundation, either version 2 of the
> > -License, or (at your option) any later version.
> > -
> > -This manual is distributed in the hope that it will be useful, but
> > -WITHOUT ANY WARRANTY; without even the implied warranty of
> > -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
> > -General Public License for more details.
> > -
> > -You should have received a copy of the GNU General Public License
> > -along with this manual. If not, see http://www.gnu.org/licenses/.
> > -@end quotation
> > -@end copying
>
> Does the interop manual carry an equivalent copyright notice?
NB: in the Texinfo versions, Texinfo does not put this copyright/license
notice in its generated manpages, and it is in the generated HTML only
as an HTML comment, not visible to the ordinary reader.
The Sphinx interop manual has the usual footer:
https://www.qemu.org/docs/master/interop/index.html
"©2020, The QEMU Project Developers."
The system manual has an explicit "License" section:
https://www.qemu.org/docs/master/system/license.html
but that's documenting the license of the program, not the
manual (it's docs/system/license.rst).
We could do any or all of:
* decide that we're happy with the current situation
* expand the "copyright" footer to something like
'©2020, The QEMU Project Developers; this manual is GPLv2'
* have a docs/foo/license.rst for each manual, and expand
it to mention the documentation license as well as the
code license
Given that the Texinfo generated QMP/QGA references don't
actually present this text to the reader, my inclination
is to say that this is something we should address in
a separate patchseries, not as part of this conversion.
thanks
-- PMM
Peter Maydell <peter.maydell@linaro.org> writes:
> On Fri, 4 Sep 2020 at 14:16, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > Convert qemu-ga-ref to rST format. This includes dropping
>> > the plain-text, pdf and info format outputs for this document;
>> > as with all our other Sphinx-based documentation, we provide
>> > HTML and manpage only.
>
>> > -@copying
>> > -This is the QEMU Guest Agent Protocol reference manual.
>> > -
>> > -Copyright @copyright{} 2016 The QEMU Project developers
>> > -
>> > -@quotation
>> > -This manual is free documentation: you can redistribute it and/or
>> > -modify it under the terms of the GNU General Public License as
>> > -published by the Free Software Foundation, either version 2 of the
>> > -License, or (at your option) any later version.
>> > -
>> > -This manual is distributed in the hope that it will be useful, but
>> > -WITHOUT ANY WARRANTY; without even the implied warranty of
>> > -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
>> > -General Public License for more details.
>> > -
>> > -You should have received a copy of the GNU General Public License
>> > -along with this manual. If not, see http://www.gnu.org/licenses/.
>> > -@end quotation
>> > -@end copying
>>
>> Does the interop manual carry an equivalent copyright notice?
>
> NB: in the Texinfo versions, Texinfo does not put this copyright/license
> notice in its generated manpages, and it is in the generated HTML only
> as an HTML comment, not visible to the ordinary reader.
For what it's worth, the generated PDF has it on page 2.
> The Sphinx interop manual has the usual footer:
> https://www.qemu.org/docs/master/interop/index.html
> "©2020, The QEMU Project Developers."
>
> The system manual has an explicit "License" section:
> https://www.qemu.org/docs/master/system/license.html
> but that's documenting the license of the program, not the
> manual (it's docs/system/license.rst).
>
> We could do any or all of:
> * decide that we're happy with the current situation
> * expand the "copyright" footer to something like
> '©2020, The QEMU Project Developers; this manual is GPLv2'
> * have a docs/foo/license.rst for each manual, and expand
> it to mention the documentation license as well as the
> code license
>
> Given that the Texinfo generated QMP/QGA references don't
> actually present this text to the reader, my inclination
> is to say that this is something we should address in
> a separate patchseries, not as part of this conversion.
I think the manual should have a proper copyright notice.
If you'd prefer to (re-)add it later, stick in TODO comment.
On Tue, 22 Sep 2020 at 13:01, Markus Armbruster <armbru@redhat.com> wrote: > > Peter Maydell <peter.maydell@linaro.org> writes: > > The Sphinx interop manual has the usual footer: > > https://www.qemu.org/docs/master/interop/index.html > > "©2020, The QEMU Project Developers." > > > > The system manual has an explicit "License" section: > > https://www.qemu.org/docs/master/system/license.html > > but that's documenting the license of the program, not the > > manual (it's docs/system/license.rst). > > > > We could do any or all of: > > * decide that we're happy with the current situation > > * expand the "copyright" footer to something like > > '©2020, The QEMU Project Developers; this manual is GPLv2' > > * have a docs/foo/license.rst for each manual, and expand > > it to mention the documentation license as well as the > > code license > > > > Given that the Texinfo generated QMP/QGA references don't > > actually present this text to the reader, my inclination > > is to say that this is something we should address in > > a separate patchseries, not as part of this conversion. > > I think the manual should have a proper copyright notice. It does -- that's the standard Sphinx footer that reads "©2020, The QEMU Project Developers." What it's missing is more precise licensing information. > If you'd prefer to (re-)add it later, stick in TODO comment. Where would you want a TODO to be ? thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Tue, 22 Sep 2020 at 13:01, Markus Armbruster <armbru@redhat.com> wrote: >> >> Peter Maydell <peter.maydell@linaro.org> writes: >> > The Sphinx interop manual has the usual footer: >> > https://www.qemu.org/docs/master/interop/index.html >> > "©2020, The QEMU Project Developers." >> > >> > The system manual has an explicit "License" section: >> > https://www.qemu.org/docs/master/system/license.html >> > but that's documenting the license of the program, not the >> > manual (it's docs/system/license.rst). >> > >> > We could do any or all of: >> > * decide that we're happy with the current situation >> > * expand the "copyright" footer to something like >> > '©2020, The QEMU Project Developers; this manual is GPLv2' >> > * have a docs/foo/license.rst for each manual, and expand >> > it to mention the documentation license as well as the >> > code license >> > >> > Given that the Texinfo generated QMP/QGA references don't >> > actually present this text to the reader, my inclination >> > is to say that this is something we should address in >> > a separate patchseries, not as part of this conversion. >> >> I think the manual should have a proper copyright notice. > > It does -- that's the standard Sphinx footer that reads > "©2020, The QEMU Project Developers." What it's missing > is more precise licensing information. Yes. >> If you'd prefer to (re-)add it later, stick in TODO comment. > > Where would you want a TODO to be ? Before the patch, the licensing information is in docs/interop/qemu-ga-ref.texi. That file gets replaced by docs/interop/qemu-ga-ref.rst, losing the licensing information. What about putting the TODO right there?
On Tue, 22 Sep 2020 at 15:13, Markus Armbruster <armbru@redhat.com> wrote: > > Peter Maydell <peter.maydell@linaro.org> writes: > > > On Tue, 22 Sep 2020 at 13:01, Markus Armbruster <armbru@redhat.com> wrote: > >> If you'd prefer to (re-)add it later, stick in TODO comment. > > > > Where would you want a TODO to be ? > > Before the patch, the licensing information is in > docs/interop/qemu-ga-ref.texi. That file gets replaced by > docs/interop/qemu-ga-ref.rst, losing the licensing information. What > about putting the TODO right there? I can if you insist, but what makes that .rst file any different from all the other .rst files we have in docs/ which go into our various manuals and don't have explicit licensing comments or reader-visible text? If we want to improve how we inform readers of the docs license, we might: * add a license note to the existing copyright footer line * or to have every page to have a larger copyright/license text section at the bottom * or to have the interop and other manuals have a license.rst like the system manual does currently, and none of those changes would require editing qemu-ga-ref.rst or qemu-qmp-ref.rst, because the overall problem being addressed isn't specific to those parts of the documentation, it's a wider one that you'd fix in a different place. thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Tue, 22 Sep 2020 at 15:13, Markus Armbruster <armbru@redhat.com> wrote: >> >> Peter Maydell <peter.maydell@linaro.org> writes: >> >> > On Tue, 22 Sep 2020 at 13:01, Markus Armbruster <armbru@redhat.com> wrote: >> >> If you'd prefer to (re-)add it later, stick in TODO comment. >> > >> > Where would you want a TODO to be ? >> >> Before the patch, the licensing information is in >> docs/interop/qemu-ga-ref.texi. That file gets replaced by >> docs/interop/qemu-ga-ref.rst, losing the licensing information. What >> about putting the TODO right there? > > I can if you insist, but what makes that .rst file any > different from all the other .rst files we have in docs/ > which go into our various manuals and don't have explicit > licensing comments or reader-visible text? > > If we want to improve how we inform readers of the docs > license, we might: > * add a license note to the existing copyright footer line > * or to have every page to have a larger copyright/license > text section at the bottom > * or to have the interop and other manuals have a license.rst > like the system manual does currently, > and none of those changes would require editing qemu-ga-ref.rst > or qemu-qmp-ref.rst, because the overall problem being addressed > isn't specific to those parts of the documentation, it's a > wider one that you'd fix in a different place. My first preference is keeping the licensing information. How to keep it is up to you. If you'd prefer not to in this series, then all I ask for is a reminder *somewhere* that we've lost licensing information, and should put it back. You choose where to put it and how to phrase it. But since you asked, I made a suggestion. Feel free to choose anther place or phrasing.
© 2016 - 2026 Red Hat, Inc.