| Message ID | 20200225154121.21116-1-peter.maydell@linaro.org |
|---|---|
| Headers | show |
| Series | docs: Miscellaneous rST conversions | expand |
On 25/02/20 16:41, Peter Maydell wrote: > This patchset converts some texi files used in qemu-doc.texi to rST: > > * docs/security.texi > * qemu-tech.texi > * qemu-deprecated.texi > > which all end up as sections of the "system" manual. > > In all cases, these pieces of the documentation are part of > the qemu-doc HTML file, but not included in the qemu.1 manpage, > so they are just a straightforward format conversion. > > security and deprecated are pure conversions with only > changes to the formatting, not to the contents. > > For qemu-tech.texi, a large part of it was an extremely out of > date and partial attempt to document the limitations of our > CPU emulation. Apart from a change to the Xtensa section in > 2012, no part of the actual text seems to have been updated > since 2008. I judged it better to simply dump this rather > than carry it over. Creating an actually accurate section > about the limitations of the various guest architectures > is probably easier done from scratch if we want it and are > prepared to actually keep it up to date this time... I assume these are not meant to be applied now, except patch 2? For what it's worth, security.texi can be converted just fine with: makeinfo -o - --docbook security.texi | pandoc -f docbook -t rst Paolo
On Tue, 25 Feb 2020 at 17:01, Paolo Bonzini <pbonzini@redhat.com> wrote: > > On 25/02/20 16:41, Peter Maydell wrote: > > This patchset converts some texi files used in qemu-doc.texi to rST: > > > > * docs/security.texi > > * qemu-tech.texi > > * qemu-deprecated.texi > > > > which all end up as sections of the "system" manual. > > > > In all cases, these pieces of the documentation are part of > > the qemu-doc HTML file, but not included in the qemu.1 manpage, > > so they are just a straightforward format conversion. > > > > security and deprecated are pure conversions with only > > changes to the formatting, not to the contents. > > > > For qemu-tech.texi, a large part of it was an extremely out of > > date and partial attempt to document the limitations of our > > CPU emulation. Apart from a change to the Xtensa section in > > 2012, no part of the actual text seems to have been updated > > since 2008. I judged it better to simply dump this rather > > than carry it over. Creating an actually accurate section > > about the limitations of the various guest architectures > > is probably easier done from scratch if we want it and are > > prepared to actually keep it up to date this time... > > I assume these are not meant to be applied now, except patch 2? No, I intended them to be reviewable and applied now. Why do you think we should wait? thanks -- PMM
On 25/02/20 18:11, Peter Maydell wrote: >> I assume these are not meant to be applied now, except patch 2? > No, I intended them to be reviewable and applied now. Why > do you think we should wait? Because they remove information from qemu-doc.texi. I think it's feasible to do a mass conversion quite soon, within a single pull request, the only important part that is missing is the hxtool conversion. (See also the patches I posted today, which take the opposite direction of making qemu-doc.texi's structure more like what we'll have in the end in docs/system). Paolo
On Tue, 25 Feb 2020 at 17:48, Paolo Bonzini <pbonzini@redhat.com> wrote: > > On 25/02/20 18:11, Peter Maydell wrote: > >> I assume these are not meant to be applied now, except patch 2? > > No, I intended them to be reviewable and applied now. Why > > do you think we should wait? > > Because they remove information from qemu-doc.texi. I think it's > feasible to do a mass conversion quite soon, within a single pull > request, the only important part that is missing is the hxtool conversion. My assumption was that we would attack this by: * converting chunks of the documentation which are in qemu-doc.texi but which aren't in the qemu.1 manpage (basically in the way this series is doing) * get the qapidoc generation conversion reviewed and into master (since at the moment it outputs into files included from qemu-doc) * convert the manpage parts; we have the machinery for dealing with the hxtool files, it just needs a little more work > (See also the patches I posted today, which take the opposite direction > of making qemu-doc.texi's structure more like what we'll have in the end > in docs/system). This ought to make it easier to do the conversion of the various subparts, right? Incidentally: > makeinfo -o - --docbook security.texi | pandoc -f docbook -t rst security texi was the really easy one here. I had to do more manual formatting fixups on qemu-deprecated.texi which I'm sceptical would have worked out as nicely done automatically. The automatic conversion rune also doesn't seem to get quotes and apostrophes right: it has turned "guest B's disk image" into something with a smartquote character in it, for instance. thanks -- PMM
On 25/02/20 18:59, Peter Maydell wrote: > My assumption was that we would attack this by: > * converting chunks of the documentation which are in qemu-doc.texi > but which aren't in the qemu.1 manpage (basically in the way this > series is doing) > * get the qapidoc generation conversion reviewed and into > master (since at the moment it outputs into files included > from qemu-doc) The QAPI docs are in other manuals in docs/interop/, aren't they? > * convert the manpage parts; we have the machinery for dealing > with the hxtool files, it just needs a little more work > >> (See also the patches I posted today, which take the opposite direction >> of making qemu-doc.texi's structure more like what we'll have in the end >> in docs/system). > > This ought to make it easier to do the conversion of the > various subparts, right? Right, and easier to review as well; I called it "the opposite direction" because the editing is done in Texinfo format and the rST conversion becomes relatively trivial. This would make it possible to do the conversion in a branch and pull it all at once (apart from qapidoc and possibly other small changes like removing obsolete parts). > Incidentally: >> makeinfo -o - --docbook security.texi | pandoc -f docbook -t rst > security texi was the really easy one here. I had to do more > manual formatting fixups on qemu-deprecated.texi which I'm > sceptical would have worked out as nicely done automatically. The automated conversion of qemu-deprecated.texi is indeed bad because the titles in the source are missing @code{...} to activate monospaced characters. > The automatic conversion rune also doesn't seem to get quotes > and apostrophes right: it has turned "guest B's disk image" into > something with a smartquote character in it, for instance. We probably don't want smartquotes at all, so you'd use "-t rst+smart" as the destination. Also pandoc does not use the "::" at the end of the previous paragraph. That can be fixed with for example perl -e '$/=undef; $_ = <>; s/:\n\n::/::/g; print' In general the result is more than acceptable, and I'd rather get a quick-and-slightly-dirty conversion done quickly than do everything manually but risk missing 5.0. Paolo
On Tue, 25 Feb 2020 at 18:28, Paolo Bonzini <pbonzini@redhat.com> wrote: > > On 25/02/20 18:59, Peter Maydell wrote: > > My assumption was that we would attack this by: > > * converting chunks of the documentation which are in qemu-doc.texi > > but which aren't in the qemu.1 manpage (basically in the way this > > series is doing) > > * get the qapidoc generation conversion reviewed and into > > master (since at the moment it outputs into files included > > from qemu-doc) > > The QAPI docs are in other manuals in docs/interop/, aren't they? Yes, but until we complete the conversion we can't get rid of the qemu-doc.html output, because that's where the HTML output from the QAPI doc generation goes. > > Incidentally: > >> makeinfo -o - --docbook security.texi | pandoc -f docbook -t rst > > security texi was the really easy one here. I had to do more > > manual formatting fixups on qemu-deprecated.texi which I'm > > sceptical would have worked out as nicely done automatically. > > The automated conversion of qemu-deprecated.texi is indeed bad because > the titles in the source are missing @code{...} to activate monospaced > characters. To be fair on the automated conversion, the markup in the source texinfo here is suboptimal :-) > > The automatic conversion rune also doesn't seem to get quotes > > and apostrophes right: it has turned "guest B's disk image" into > > something with a smartquote character in it, for instance. > > We probably don't want smartquotes at all, so you'd use "-t rst+smart" > as the destination. Also pandoc does not use the "::" at the end of the > previous paragraph. That can be fixed with for example > > perl -e '$/=undef; $_ = <>; s/:\n\n::/::/g; print' > > In general the result is more than acceptable, and I'd rather get a > quick-and-slightly-dirty conversion done quickly than do everything > manually but risk missing 5.0. Yeah, seems like a good plan. If the autoconversion works out then I think the main thing which makes "do all this for 5.0" at risk currently is that the qapidoc conversion series needs review and might need overhauling based on that review: it doesn't take many cycles of review-and-fix to push close to the softfreeze deadline. What do you want to do with this patchset? thanks -- PMM
Il mar 25 feb 2020, 19:57 Peter Maydell <peter.maydell@linaro.org> ha scritto: > > The QAPI docs are in other manuals in docs/interop/, aren't they? > > Yes, but until we complete the conversion we can't get > rid of the qemu-doc.html output, because that's where the > HTML output from the QAPI doc generation goes. > Right. > In general the result is more than acceptable, and I'd rather get a > > quick-and-slightly-dirty conversion done quickly than do everything > > manually but risk missing 5.0. > > Yeah, seems like a good plan. If the autoconversion works out > then I think the main thing which makes "do all this for 5.0" > at risk currently is that the qapidoc conversion series needs > review and might need overhauling based on that review: it > doesn't take many cycles of review-and-fix to push close to > the softfreeze deadline. > > What do you want to do with this patchset? > This could go in independently. It would make Kashyap's series conflict, but I have already rebased it on top. Perhaps we could have the files in both .texi and (automatically converted) .rst versions at the same time in the tree for a short period. If that's okay for you, I can post tomorrow a series to do that. Paolo
On Tue, 25 Feb 2020 at 19:10, Paolo Bonzini <pbonzini@redhat.com> wrote: > This could go in independently. It would make Kashyap's series > conflict, but I have already rebased it on top. I'm happy to collect up 'docs' patches for pullreqs (and fix up conflicts etc as they arise) if that helps in getting things into the tree. I feel like we're working a bit at cross purposes here so maybe we'd benefit from just nailing down who's going to do what and in which order? My current thought on ordering is something like: * commit this * commit Kashyap's series * commit (an adjusted version of) your split-out-the-texi series * (automated) conversion of more texi -- all in one series I guess ? * ??? * profit but I'm not very strongly attached to that. > Perhaps we could have the files in both .texi and (automatically > converted) .rst versions at the same time in the tree for a short > period. If that's okay for you, I can post tomorrow a series to do that. My instinct is to say that that's a bit dangerous as it means we might end up with changes to the "wrong" version of the two files. Would it let us do the conversion faster or more conveniently ? thanks -- PMM
Il mar 25 feb 2020, 20:50 Peter Maydell <peter.maydell@linaro.org> ha scritto: > On Tue, 25 Feb 2020 at 19:10, Paolo Bonzini <pbonzini@redhat.com> wrote: > I feel like we're working a bit at cross purposes here so maybe > we'd benefit from just nailing down who's going to do what and > in which order? > I am not going to do much more than what I posted today, basically only the automated conversion. > > My current thought on ordering is something like: > * commit this > * commit Kashyap's series > * commit (an adjusted version of) your split-out-the-texi series > * (automated) conversion of more texi -- all in one series I guess ? > * ??? > * profit > > but I'm not very strongly attached to that. > The main issue with this series and Kashyap's is that if we don't manage to get everything done in 5.0 we have a mutilated qemu-doc. Then either we keep it mutilated or we scramble to undo the work. So I would agree to commit the series in this order, but without the removal of the .texi files. > Perhaps we could have the files in both .texi and (automatically > > converted) .rst versions at the same time in the tree for a short > > period. If that's okay for you, I can post tomorrow a series to do that. > > My instinct is to say that that's a bit dangerous as it means > we might end up with changes to the "wrong" version of the > two files. Would it let us do the conversion faster or > more conveniently ? > It would be a kind of "insurance" against being late, basically. Doc changes are rare enough that we could manage it, I think (and as long as code review catches changes to only one version of the docs, no bitrot is possible since we would build both). Paolo > thanks > -- PMM > >
On Tue, 25 Feb 2020 at 20:10, Paolo Bonzini <pbonzini@redhat.com> wrote: > The main issue with this series and Kashyap's is that if we don't manage to get > everything done in 5.0 we have a mutilated qemu-doc. Then either we keep it > mutilated or we scramble to undo the work. So I would agree to commit the > series in this order, but without the removal of the .texi files. Kashyap's set is in the same ballpark as what we've currently converted (notably it's pretty much equivalent to the qemu-block-drivers conversion in that it takes what was part of qemu-doc plus a manpage and turns it into part of the system manual plus a manpage). It's also the most awkward to try to keep the texi around for, because the makefile runes for the texi want to generate the manpage too. So I think I would argue for taking that as-is, including removal of the texi files. I agree that it would be good to avoid a half-converted qemu-doc; if people think keeping two parallel doc files until we're sure we can do the conversion is useful insurance I'm happy to go along with that. If we ended up with "we managed all the conversion except for the qapi json doc comments parts" would we be ok with having a qemu-doc.html that just contained those, and all the actual docs transitioning to rST for this release? Or would we want to roll back the rST for the main qemu-doc parts too in that situation? thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Tue, 25 Feb 2020 at 17:48, Paolo Bonzini <pbonzini@redhat.com> wrote: >> >> On 25/02/20 18:11, Peter Maydell wrote: >> >> I assume these are not meant to be applied now, except patch 2? >> > No, I intended them to be reviewable and applied now. Why >> > do you think we should wait? >> >> Because they remove information from qemu-doc.texi. I think it's >> feasible to do a mass conversion quite soon, within a single pull >> request, the only important part that is missing is the hxtool conversion. > > My assumption was that we would attack this by: > * converting chunks of the documentation which are in qemu-doc.texi > but which aren't in the qemu.1 manpage (basically in the way this > series is doing) > * get the qapidoc generation conversion reviewed and into > master (since at the moment it outputs into files included > from qemu-doc) Not true. QAPI doc comments go into *separate* manuals, the "QEMU QMP reference" (docs/interop/qemu-qmp-ref.*), and the "QEMU Guest Agent protocol reference" (docs/interop/qemu-ga-ref.*). In more detail: scripts/qapi-gen.py generates docs/interop/qemu-qmp-qapi.texi from qapi/qapi-schema.json, and docs/interop/qemu-ga-qapi.texi from qga/qapi-schema.json. These are included into docs/interop/qemu-qmp-ref.texi and docs/interop/qemu-ga-ref.texi, respectively. > * convert the manpage parts; we have the machinery for dealing > with the hxtool files, it just needs a little more work [...]
On Wed, 26 Feb 2020 at 07:50, Markus Armbruster <armbru@redhat.com> wrote: > Peter Maydell <peter.maydell@linaro.org> writes: > > * get the qapidoc generation conversion reviewed and into > > master (since at the moment it outputs into files included > > from qemu-doc) > > Not true. QAPI doc comments go into *separate* manuals, the "QEMU QMP > reference" (docs/interop/qemu-qmp-ref.*), and the "QEMU Guest Agent > protocol reference" (docs/interop/qemu-ga-ref.*). So it does. I think I must have just assumed it was included in qemu-doc because just about everything else is. That makes things easier as the process of converting qemu-doc and the conversion of the QAPI doc comments can be handled separately without interdependencies. thanks -- PMM
This patchset converts some texi files used in qemu-doc.texi to rST: * docs/security.texi * qemu-tech.texi * qemu-deprecated.texi which all end up as sections of the "system" manual. In all cases, these pieces of the documentation are part of the qemu-doc HTML file, but not included in the qemu.1 manpage, so they are just a straightforward format conversion. security and deprecated are pure conversions with only changes to the formatting, not to the contents. For qemu-tech.texi, a large part of it was an extremely out of date and partial attempt to document the limitations of our CPU emulation. Apart from a change to the Xtensa section in 2012, no part of the actual text seems to have been updated since 2008. I judged it better to simply dump this rather than carry it over. Creating an actually accurate section about the limitations of the various guest architectures is probably easier done from scratch if we want it and are prepared to actually keep it up to date this time... thanks -- PMM Peter Maydell (4): docs: Convert security.texi to rST format docs: Remove the "CPU emulation" part of the "Implementation notes" docs: Convert 'managed start up options' docs to rST docs: Convert qemu-deprecated.texi to rST Makefile | 6 +- MAINTAINERS | 2 +- docs/system/deprecated.rst | 446 ++++++++++++++++++++ docs/system/index.rst | 3 + docs/system/managed-startup.rst | 35 ++ docs/{security.texi => system/security.rst} | 82 ++-- qemu-deprecated.texi | 386 ----------------- qemu-doc.texi | 10 - qemu-tech.texi | 195 --------- 9 files changed, 532 insertions(+), 633 deletions(-) create mode 100644 docs/system/deprecated.rst create mode 100644 docs/system/managed-startup.rst rename docs/{security.texi => system/security.rst} (77%) delete mode 100644 qemu-deprecated.texi delete mode 100644 qemu-tech.texi