Stop building the old texinfo qemu-doc; all its contents are
now available in the Sphinx-generated manuals and manpages.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/specs/ivshmem-spec.txt |  4 ++--
 Makefile                    | 39 ++++---------------------------------
 .gitignore                  |  3 ---
 docs/index.html.in          |  1 -
 4 files changed, 6 insertions(+), 41 deletions(-)

diff --git a/docs/specs/ivshmem-spec.txt b/docs/specs/ivshmem-spec.txt
index 042f7eae225..1beb3a01ec3 100644
--- a/docs/specs/ivshmem-spec.txt
+++ b/docs/specs/ivshmem-spec.txt
@@ -38,8 +38,8 @@ There are two basic configurations:
   Interrupts are message-signaled (MSI-X).  vectors=N configures the
   number of vectors to use.
 
-For more details on ivshmem device properties, see The QEMU Emulator
-User Documentation (qemu-doc.*).
+For more details on ivshmem device properties, see the QEMU Emulator
+user documentation.
 
 
 == The ivshmem PCI device's guest interface ==
diff --git a/Makefile b/Makefile
index ef10b9a031d..9d4b2241265 100644
--- a/Makefile
+++ b/Makefile
@@ -344,7 +344,6 @@ MANUAL_BUILDDIR := docs
 endif
 
 ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-doc.txt
 DOCS+=$(MANUAL_BUILDDIR)/system/qemu.1
 DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
 DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
@@ -768,10 +767,6 @@ distclean: clean
 	rm -f $(SUBDIR_DEVICES_MAK)
 	rm -f po/*.mo tests/qemu-iotests/common.env
 	rm -f roms/seabios/config.mak roms/vgabios/config.mak
-	rm -f qemu-doc.info qemu-doc.aux qemu-doc.cp qemu-doc.cps
-	rm -f qemu-doc.fn qemu-doc.fns qemu-doc.info qemu-doc.ky qemu-doc.kys
-	rm -f qemu-doc.log qemu-doc.pdf qemu-doc.pg qemu-doc.toc qemu-doc.tp
-	rm -f qemu-doc.vr qemu-doc.txt
 	rm -f qemu-plugins-ld.symbols qemu-plugins-ld64.symbols
 	rm -f config.log
 	rm -f linux-headers/asm
@@ -851,8 +846,6 @@ install-sphinxdocs: sphinxdocs
 install-doc: $(DOCS) install-sphinxdocs
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/index.html "$(DESTDIR)$(qemu_docdir)"
-	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
-	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)"
 ifdef CONFIG_POSIX
@@ -1110,34 +1103,10 @@ docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
 docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
 	@cp -p $< $@
 
-html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
-info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
-pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
-txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
-
-qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
-	qemu-options.texi \
-	qemu-monitor.texi \
-	qemu-monitor-info.texi \
-        docs/system/quickstart.texi \
-        docs/system/invocation.texi \
-        docs/system/keys.texi \
-        docs/system/mux-chardev.texi \
-        docs/system/monitor.texi \
-        docs/system/cpu-models-x86.texi \
-        docs/system/images.texi \
-        docs/system/net.texi \
-        docs/system/usb.texi \
-        docs/system/ivshmem.texi \
-        docs/system/linuxboot.texi \
-        docs/system/vnc-security.texi \
-        docs/system/tls.texi \
-        docs/system/gdb.texi \
-        docs/system/build-platforms.texi \
-        docs/system/license.texi \
-	docs/system/cpu-models-x86.texi docs/system/cpu-models-mips.texi \
-	docs/system/deprecated.texi docs/system/qemu-option-trace.texi \
-	docs/system/security.texi
+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 \
diff --git a/.gitignore b/.gitignore
index bc0a035f9cc..0c5af83aa74 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,9 +46,6 @@
 !/qapi/qapi-visit-core.c
 /qapi/qapi-visit.[ch]
 /qapi/qapi-doc.texi
-/qemu-doc.html
-/qemu-doc.info
-/qemu-doc.txt
 /qemu-edid
 /qemu-img
 /qemu-nbd
diff --git a/docs/index.html.in b/docs/index.html.in
index a576ace8a27..cc19aad2ec5 100644
--- a/docs/index.html.in
+++ b/docs/index.html.in
@@ -7,7 +7,6 @@
     <body>
         <h1>QEMU @@VERSION@@ Documentation</h1>
         <ul>
-            <li><a href="qemu-doc.html">User Documentation</a></li>
             <li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li>
             <li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</a></li>
             <li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li>
-- 
2.20.1

Peter Maydell <peter.maydell@linaro.org> writes:

> Stop building the old texinfo qemu-doc; all its contents are
> now available in the Sphinx-generated manuals and manpages.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée

Peter Maydell <peter.maydell@linaro.org> writes:

> Stop building the old texinfo qemu-doc; all its contents are
> now available in the Sphinx-generated manuals and manpages.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

This appears to lose plain text, PDF and info output.  Any chance to get
plain text back?

On Wed, 11 Mar 2020 at 14:53, Markus Armbruster <armbru@redhat.com> wrote:
> This appears to lose plain text, PDF and info output.  Any chance to get
> plain text back?

This is deliberate. Consensus when we decided on the docs
transition plan was that plain text was not a useful output
format. (discussed in
https://lists.gnu.org/archive/html/qemu-devel/2019-05/msg04932.html
and following thread).

Sphinx does support text file generation, so you can if
you really want it generate it with something like
 sphinx-build docs /tmp/docs-out -b text
but:
 * it produces one text file per input file, so you might
as well just read the rST sources
 * at least in the version of Sphinx I have, the text builder
does not implement some of the table markup we use,
so it will fall over partway with a NotImplementedError

PDF similarly is in theory possible via 'latex' builder
(and then running LaTeX on the results). You can also
download a PDF from
https://readthedocs.org/projects/qemu/downloads/
You will find that there are some bits where rendering
is not good (eg long lines that didn't get wrapped so were
just truncated).

Personally I think it's difficult enough managing two
output formats and checking that they look reasonable
(we already found places in the QAPI docs where
clearly nobody had looked at *any* of the rendered
formats) so I think settling on "our supported document
formats are HTML and manpage" is reasonable.

thanks
-- PMM

Peter Maydell <peter.maydell@linaro.org> writes:

> On Wed, 11 Mar 2020 at 14:53, Markus Armbruster <armbru@redhat.com> wrote:
>> This appears to lose plain text, PDF and info output.  Any chance to get
>> plain text back?
>
> This is deliberate. Consensus when we decided on the docs
> transition plan was that plain text was not a useful output
> format. (discussed in
> https://lists.gnu.org/archive/html/qemu-devel/2019-05/msg04932.html
> and following thread).

I missed this part.  Not your fault.

> Sphinx does support text file generation, so you can if
> you really want it generate it with something like
>  sphinx-build docs /tmp/docs-out -b text
> but:
>  * it produces one text file per input file, so you might
> as well just read the rST sources
>  * at least in the version of Sphinx I have, the text builder
> does not implement some of the table markup we use,
> so it will fall over partway with a NotImplementedError
>
> PDF similarly is in theory possible via 'latex' builder
> (and then running LaTeX on the results). You can also
> download a PDF from
> https://readthedocs.org/projects/qemu/downloads/
> You will find that there are some bits where rendering
> is not good (eg long lines that didn't get wrapped so were
> just truncated).
>
> Personally I think it's difficult enough managing two
> output formats and checking that they look reasonable
> (we already found places in the QAPI docs where
> clearly nobody had looked at *any* of the rendered
> formats) so I think settling on "our supported document
> formats are HTML and manpage" is reasonable.

I see.

With plain text gone, I'll certainly look at any of the rendered stuff
even less than before.

Would it be possible to additionally render a complete manual as one
humongous .html?  Without an index, there's only search, and the
ergonomics of searching within a single page are so much better.

I'm tempted to write a trivial QAPI doc comment backend to spit out
minimally processed doc comments as one plain text file just for that.

On Thu, 12 Mar 2020 at 06:06, Markus Armbruster <armbru@redhat.com> wrote:
> Would it be possible to additionally render a complete manual as one
> humongous .html?  Without an index, there's only search, and the
> ergonomics of searching within a single page are so much better.

There is a "build one big fat HTML page" Sphinx builder,
I think. But again, I'm dubious about increasing the number
of supported output formats -- it's all extra makefile complexity
and more things to get right in 'make install' and so on.

PS: assuming you have js enabled, each HTML manual has a js
search engine built in, eg the 'quick search' box at the bottom
of the LHS navigation bar on
https://www.qemu.org/docs/master/system/index.html

> I'm tempted to write a trivial QAPI doc comment backend to spit out
> minimally processed doc comments as one plain text file just for that.

What would be the difference there compared to just looking
at the manpage? The manpages don't have the full content
of all the HTML manuals, but the QAPI reference manpages
will have all the QAPI content.

thanks
-- PMM

Peter Maydell <peter.maydell@linaro.org> writes:

> On Thu, 12 Mar 2020 at 06:06, Markus Armbruster <armbru@redhat.com> wrote:
>> Would it be possible to additionally render a complete manual as one
>> humongous .html?  Without an index, there's only search, and the
>> ergonomics of searching within a single page are so much better.
>
> There is a "build one big fat HTML page" Sphinx builder,
> I think. But again, I'm dubious about increasing the number
> of supported output formats -- it's all extra makefile complexity
> and more things to get right in 'make install' and so on.
>
> PS: assuming you have js enabled, each HTML manual has a js
> search engine built in, eg the 'quick search' box at the bottom
> of the LHS navigation bar on
> https://www.qemu.org/docs/master/system/index.html
>
>> I'm tempted to write a trivial QAPI doc comment backend to spit out
>> minimally processed doc comments as one plain text file just for that.
>
> What would be the difference there compared to just looking
> at the manpage? The manpages don't have the full content
> of all the HTML manuals, but the QAPI reference manpages
> will have all the QAPI content.

I forgot qemu-qmp-ref.7 exists, and missed Paolo's hint earlier in this
thread.  Thanks!

Also, man to text is obviously doable with groff if we're content with the
man page content.

Paolo

Il mer 11 mar 2020, 16:16 Peter Maydell <peter.maydell@linaro.org> ha
scritto:

> On Wed, 11 Mar 2020 at 14:53, Markus Armbruster <armbru@redhat.com> wrote:
> > This appears to lose plain text, PDF and info output.  Any chance to get
> > plain text back?
>
> This is deliberate. Consensus when we decided on the docs
> transition plan was that plain text was not a useful output
> format. (discussed in
> https://lists.gnu.org/archive/html/qemu-devel/2019-05/msg04932.html
> and following thread).
>
> Sphinx does support text file generation, so you can if
> you really want it generate it with something like
>  sphinx-build docs /tmp/docs-out -b text
> but:
>  * it produces one text file per input file, so you might
> as well just read the rST sources
>  * at least in the version of Sphinx I have, the text builder
> does not implement some of the table markup we use,
> so it will fall over partway with a NotImplementedError
>
> PDF similarly is in theory possible via 'latex' builder
> (and then running LaTeX on the results). You can also
> download a PDF from
> https://readthedocs.org/projects/qemu/downloads/
> You will find that there are some bits where rendering
> is not good (eg long lines that didn't get wrapped so were
> just truncated).
>
> Personally I think it's difficult enough managing two
> output formats and checking that they look reasonable
> (we already found places in the QAPI docs where
> clearly nobody had looked at *any* of the rendered
> formats) so I think settling on "our supported document
> formats are HTML and manpage" is reasonable.
>
> thanks
> -- PMM
>
>

On Wed, 11 Mar 2020 at 15:22, Paolo Bonzini <pbonzini@redhat.com> wrote:
> Also, man to text is obviously doable with groff if we're content with the man page content.

The manpages are a small subset of the full HTML manual, though
(as was also the case for the texinfo generation process).

thanks
-- PMM