Hi; this series does a complete conversion of qemu-doc from
Texinfo to rST, including the hxtool-generated parts and
creation of the qemu.1 manpage from rST.

It's marked v3 because it's a development of the v2 that
Paolo sent out earlier this week.

Changes from v2:
 * I made the various review-comment fixes I suggested in
   replies to Paolo's series
 * rebased on current master
 * new patches at the end of the series which do the conversion
   of the .hx file doc fragments to rST
   (I did part of this semi-by-hand and then qemu-options.hx
   entirely automatically)
 * new patches which generate the qemu.1 manpage with Sphinx
 * new patches which remove the old qemu-doc makefile runes
   and other references to it
 * new patches which delete the old texinfo sources, etc

The only thing left still using Texinfo after this is the
docs autogenerated from the QAPI doc-comments, which are
their own standalone html and manpages so not affected by this.

A couple of notes:
 * I haven't actually been in a position to test the cocoa.m
   update of the HTML filename
 * qemu.nsi (the Windows installer config file) thinks that
   qemu-doc.html is the only doc file it needs to know about,
   which is clearly wrong. However I don't have any idea about
   the Windows installer to be able to update or test it...

The conversion is a little rough around the edges in a few
place (mostly I have noted in commit messages when this is
the case) but I would like to argue for (assuming we're happy
with the series broadly) taking it into master and then refining
it in-place. Having it out-of-tree for long is an invitation
to conflicts and to accidentally losing docs updates if they
hit master as changes to the texi or hx files before this
series goes in.

You can find a prerendered set of docs at
https://people.linaro.org/~peter.maydell/qdoc-no-texi/
(the interesting part is the system emulation user's guide,
mostly), and a copy of the new manpage at
https://people.linaro.org/~peter.maydell/qemu.1
(download and examine with 'man -l path/to/qemu.1').

thanks
-- PMM

Kashyap Chamarthy (1):
  docs/system: Convert qemu-cpu-models.texi to rST

Paolo Bonzini (13):
  qemu-doc: convert user-mode emulation to a separate Sphinx manual
  qemu-doc: remove target OS documentation
  texi2pod: parse @include directives outside "@c man" blocks
  qemu-doc: split CPU models doc between MIPS and x86 parts
  qemu-doc: split qemu-doc.texi in multiple files
  qemu-doc: extract common system emulator documentation from the PC
    section
  qemu-doc: move system requirements chapter inside PC section
  qemu-doc: split target sections to separate files
  qemu-doc: move qemu-tech.texi into main section
  qemu-doc: move included files to docs/system
  qemu-doc: remove indices other than findex
  docs/system: put qemu-block-drivers body in an included file
  docs/system: convert Texinfo documentation to rST

Peter Maydell (19):
  qemu-doc: Remove the "CPU emulation" part of the "Implementation
    notes"
  docs: Create defs.rst.inc as a place to define substitutions
  docs/system: Convert security.texi to rST format
  docs/system: convert managed startup to rST.
  docs/system: convert the documentation of deprecated features to rST.
  hmp-commands.hx: Add rST documentation fragments
  hmp-commands-info.hx: Add rST documentation fragments
  doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADING
  docs: Roll semihosting option information into qemu-options.hx
  docs: Roll -prom-env and -g target-specific info into qemu-options.hx
  scripts/hxtool-conv: Archive script used in qemu-options.hx conversion
  qemu-options.hx: Add rST documentation fragments
  qemu-options.hx: Fix up the autogenerated rST
  docs: Split out sections for the manpage into .rst.inc files
  docs: Generate qemu.1 manpage with Sphinx
  ui/cocoa.m: Update documentation file and pathname
  docs: Stop building qemu-doc
  docs: Remove old texinfo sources
  *.hx: Remove all the STEXI/ETEXI blocks

 docs/specs/ivshmem-spec.txt                   |    4 +-
 Makefile                                      |   47 +-
 .gitignore                                    |    3 -
 MAINTAINERS                                   |    7 +-
 docs/conf.py                                  |    6 +
 docs/defs.rst.inc                             |   15 +
 docs/index.html.in                            |    2 +-
 docs/index.rst                                |    1 +
 docs/qemu-cpu-models.texi                     |  677 --
 docs/sphinx/hxtool.py                         |   10 +-
 docs/system/build-platforms.rst               |   79 +
 docs/system/conf.py                           |    8 +-
 docs/system/cpu-models-mips.rst.inc           |  105 +
 docs/system/cpu-models-x86.rst.inc            |  365 +
 docs/system/deprecated.rst                    |  446 +
 docs/system/device-url-syntax.rst.inc         |  228 +
 docs/system/gdb.rst                           |   81 +
 docs/system/images.rst                        |   85 +
 docs/system/index.rst                         |   22 +-
 docs/system/invocation.rst                    |   18 +
 docs/system/ivshmem.rst                       |   64 +
 docs/system/keys.rst                          |    6 +
 docs/system/keys.rst.inc                      |   35 +
 docs/system/license.rst                       |   11 +
 docs/system/linuxboot.rst                     |   30 +
 docs/system/managed-startup.rst               |   35 +
 docs/system/monitor.rst                       |   31 +
 docs/system/mux-chardev.rst                   |    6 +
 docs/system/mux-chardev.rst.inc               |   27 +
 docs/system/net.rst                           |  100 +
 docs/system/qemu-block-drivers.rst            |  989 +--
 ...drivers.rst => qemu-block-drivers.rst.inc} |   59 +-
 docs/system/qemu-cpu-models.rst               |   20 +
 docs/system/qemu-manpage.rst                  |   45 +
 docs/system/quickstart.rst                    |   13 +
 docs/{security.texi => system/security.rst}   |   82 +-
 docs/system/target-arm.rst                    |  217 +
 docs/system/target-i386-desc.rst.inc          |   62 +
 docs/system/target-i386.rst                   |   23 +
 docs/system/target-m68k.rst                   |   21 +
 docs/system/target-mips.rst                   |  120 +
 docs/system/target-ppc.rst                    |   47 +
 docs/system/target-sparc.rst                  |   62 +
 docs/system/target-sparc64.rst                |   37 +
 docs/system/target-xtensa.rst                 |   27 +
 docs/system/targets.rst                       |   19 +
 docs/system/tls.rst                           |  328 +
 docs/system/usb.rst                           |  137 +
 docs/system/vnc-security.rst                  |  202 +
 docs/user/conf.py                             |   15 +
 docs/user/index.rst                           |   16 +
 docs/user/main.rst                            |  295 +
 hmp-commands-info.hx                          |  600 +-
 hmp-commands.hx                               | 1451 ++--
 qemu-deprecated.texi                          |  377 -
 qemu-doc.texi                                 | 2967 -------
 qemu-option-trace.texi                        |   28 -
 qemu-options.hx                               | 7291 +++++++++--------
 qemu-tech.texi                                |  195 -
 scripts/hxtool-conv.pl                        |  137 +
 scripts/texi2pod.pl                           |   36 +-
 ui/cocoa.m                                    |    4 +-
 62 files changed, 8341 insertions(+), 10135 deletions(-)
 create mode 100644 docs/defs.rst.inc
 delete mode 100644 docs/qemu-cpu-models.texi
 create mode 100644 docs/system/build-platforms.rst
 create mode 100644 docs/system/cpu-models-mips.rst.inc
 create mode 100644 docs/system/cpu-models-x86.rst.inc
 create mode 100644 docs/system/deprecated.rst
 create mode 100644 docs/system/device-url-syntax.rst.inc
 create mode 100644 docs/system/gdb.rst
 create mode 100644 docs/system/images.rst
 create mode 100644 docs/system/invocation.rst
 create mode 100644 docs/system/ivshmem.rst
 create mode 100644 docs/system/keys.rst
 create mode 100644 docs/system/keys.rst.inc
 create mode 100644 docs/system/license.rst
 create mode 100644 docs/system/linuxboot.rst
 create mode 100644 docs/system/managed-startup.rst
 create mode 100644 docs/system/monitor.rst
 create mode 100644 docs/system/mux-chardev.rst
 create mode 100644 docs/system/mux-chardev.rst.inc
 create mode 100644 docs/system/net.rst
 copy docs/system/{qemu-block-drivers.rst => qemu-block-drivers.rst.inc} (96%)
 create mode 100644 docs/system/qemu-cpu-models.rst
 create mode 100644 docs/system/qemu-manpage.rst
 create mode 100644 docs/system/quickstart.rst
 rename docs/{security.texi => system/security.rst} (77%)
 create mode 100644 docs/system/target-arm.rst
 create mode 100644 docs/system/target-i386-desc.rst.inc
 create mode 100644 docs/system/target-i386.rst
 create mode 100644 docs/system/target-m68k.rst
 create mode 100644 docs/system/target-mips.rst
 create mode 100644 docs/system/target-ppc.rst
 create mode 100644 docs/system/target-sparc.rst
 create mode 100644 docs/system/target-sparc64.rst
 create mode 100644 docs/system/target-xtensa.rst
 create mode 100644 docs/system/targets.rst
 create mode 100644 docs/system/tls.rst
 create mode 100644 docs/system/usb.rst
 create mode 100644 docs/system/vnc-security.rst
 create mode 100644 docs/user/conf.py
 create mode 100644 docs/user/index.rst
 create mode 100644 docs/user/main.rst
 delete mode 100644 qemu-deprecated.texi
 delete mode 100644 qemu-doc.texi
 delete mode 100644 qemu-option-trace.texi
 delete mode 100644 qemu-tech.texi
 create mode 100755 scripts/hxtool-conv.pl

-- 
2.20.1

Hi Stefan -- I meant to cc you on these but forgot, relating to the
"qemu.nsi needs updating to know that it should install
Sphinx documentation these days" part...

On Fri, 28 Feb 2020 at 15:36, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> Hi; this series does a complete conversion of qemu-doc from
> Texinfo to rST, including the hxtool-generated parts and
> creation of the qemu.1 manpage from rST.
>
> It's marked v3 because it's a development of the v2 that
> Paolo sent out earlier this week.
>
> Changes from v2:
>  * I made the various review-comment fixes I suggested in
>    replies to Paolo's series
>  * rebased on current master
>  * new patches at the end of the series which do the conversion
>    of the .hx file doc fragments to rST
>    (I did part of this semi-by-hand and then qemu-options.hx
>    entirely automatically)
>  * new patches which generate the qemu.1 manpage with Sphinx
>  * new patches which remove the old qemu-doc makefile runes
>    and other references to it
>  * new patches which delete the old texinfo sources, etc
>
> The only thing left still using Texinfo after this is the
> docs autogenerated from the QAPI doc-comments, which are
> their own standalone html and manpages so not affected by this.
>
> A couple of notes:
>  * I haven't actually been in a position to test the cocoa.m
>    update of the HTML filename
>  * qemu.nsi (the Windows installer config file) thinks that
>    qemu-doc.html is the only doc file it needs to know about,
>    which is clearly wrong. However I don't have any idea about
>    the Windows installer to be able to update or test it...
>
> The conversion is a little rough around the edges in a few
> place (mostly I have noted in commit messages when this is
> the case) but I would like to argue for (assuming we're happy
> with the series broadly) taking it into master and then refining
> it in-place. Having it out-of-tree for long is an invitation
> to conflicts and to accidentally losing docs updates if they
> hit master as changes to the texi or hx files before this
> series goes in.
>
> You can find a prerendered set of docs at
> https://people.linaro.org/~peter.maydell/qdoc-no-texi/
> (the interesting part is the system emulation user's guide,
> mostly), and a copy of the new manpage at
> https://people.linaro.org/~peter.maydell/qemu.1
> (download and examine with 'man -l path/to/qemu.1').
>
> thanks
> -- PMM

Am 28.02.20 um 19:36 schrieb Peter Maydell:

> Hi Stefan -- I meant to cc you on these but forgot, relating to the
> "qemu.nsi needs updating to know that it should install
> Sphinx documentation these days" part...
>
> On Fri, 28 Feb 2020 at 15:36, Peter Maydell <peter.maydell@linaro.org> wrote:
[...]
>> A couple of notes:
>>  * I haven't actually been in a position to test the cocoa.m
>>    update of the HTML filename
>>  * qemu.nsi (the Windows installer config file) thinks that
>>    qemu-doc.html is the only doc file it needs to know about,
>>    which is clearly wrong. However I don't have any idea about
>>    the Windows installer to be able to update or test it...


Maybe it is sufficient to update qemu.nsi after that series was merged.

Do you think that all documentation should be part of the Windows
installer, although it is also available online? Too much documentation
can be confusing, because it makes it more difficult to find the right
entry.

Kind regards

Stefan

On Fri, 28 Feb 2020 at 21:20, Stefan Weil <sw@weilnetz.de> wrote:
> Maybe it is sufficient to update qemu.nsi after that series was merged.

If you're happy to do it that way round I think that would certainly
make life easier in trying to get this series merged without too
much delay.

> Do you think that all documentation should be part of the Windows
> installer, although it is also available online? Too much documentation
> can be confusing, because it makes it more difficult to find the right
> entry.

I don't have a strong opinion here, but:
 * the contents that were in qemu-doc.html will now be in the
   various Sphinx manuals, so if we want to install any
   docs locally at all then installing at least the system/
   manual would be the equivalent of the old qemu-doc
 * is there a strong reason for the Windows installer not
   to just install the same set of HTML docs that the Linux
   'make install' does?

Three possible choices:
 (1) don't install any docs locally at all (rely on the online docs)
 (2) install just the 'system' manual (this will catch most of the
   documentation relevant for Windows, but misses a few bits
   like the guest-agent docs which might still matter for Windows users)
 (3) install all the manuals (this will include some manuals or sections
    definitely not of interest for Windows, like the linux-user manual)

thanks
-- PMM

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

> Hi; this series does a complete conversion of qemu-doc from
> Texinfo to rST, including the hxtool-generated parts and
> creation of the qemu.1 manpage from rST.
>
> It's marked v3 because it's a development of the v2 that
> Paolo sent out earlier this week.
<snip>

I should mention the whole thing is:

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

by virtue of my custom rtd branch:

  https://qemu-stsquad.readthedocs.io/en/doc-updates/index.html

-- 
Alex Bennée

On Fri, 28 Feb 2020 at 15:36, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> Hi; this series does a complete conversion of qemu-doc from
> Texinfo to rST, including the hxtool-generated parts and
> creation of the qemu.1 manpage from rST.
>

Advance notice: I would like to put these into a pull
request at the end of this week. This is your opportunity
to say "that would be a bad idea", "I need X more time
to review it", etc :-)

thanks
-- PMM

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

> On Fri, 28 Feb 2020 at 15:36, Peter Maydell <peter.maydell@linaro.org> wrote:
>>
>> Hi; this series does a complete conversion of qemu-doc from
>> Texinfo to rST, including the hxtool-generated parts and
>> creation of the qemu.1 manpage from rST.
>>
>
> Advance notice: I would like to put these into a pull
> request at the end of this week. This is your opportunity
> to say "that would be a bad idea", "I need X more time
> to review it", etc :-)

Just merge it, we can fix things up afterwards if we need to but it's a
big step in the right direction.

>
> thanks
> -- PMM


-- 
Alex Bennée

On Tue, Mar 03, 2020 at 05:35:01PM +0000, Peter Maydell wrote:
> On Fri, 28 Feb 2020 at 15:36, Peter Maydell <peter.maydell@linaro.org> wrote:
> >
> > Hi; this series does a complete conversion of qemu-doc from
> > Texinfo to rST, including the hxtool-generated parts and
> > creation of the qemu.1 manpage from rST.
> >
> 
> Advance notice: I would like to put these into a pull
> request at the end of this week. This is your opportunity
> to say "that would be a bad idea", "I need X more time
> to review it", etc :-)

I tried to probe some of the generated docs; I couldn't spot something
that is glaring.  (Granted, I didn't spend a _whole_ lot of time.)

And I'm with Paolo — yes, let's get this merged, and address other
issues as follow-ups :-)

-- 
/kashyap

On 03/03/20 18:35, Peter Maydell wrote:
> Advance notice: I would like to put these into a pull
> request at the end of this week. This is your opportunity
> to say "that would be a bad idea", "I need X more time
> to review it", etc :-)
> 

On the contrary, it's a great idea. :)

Paolo