Re: [PATCH 0/7] docs: State QEMU version and license in all HTML footers

[Markus Armbruster]

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

> This patchset is an effort to fix something up which I promised
> Markus I would do after we got the initial conversion to Sphinx
> done. The old QAPI reference documentation noted the documentation
> license in the texinfo source (but not in the generated HTML or
> in the generated manpages); Sphinx generated docs currently don't.
>
> The patchset starts with some tidyup that is possible now that
> we have a single combined HTML manual rather than five separate ones.
> Rather than putting common-to-all-QEMU info like the deprecation,
> build and license pages into the "system" manual, we can move them
> out to a new top level section which I have called "About". So that
> the manual doesn't now start too abruptly, I've also added some
> actual "about" text here (mostly cribbed or adapted from our website
> or from other parts of the manual).
>
> Secondly, it uses the Sphinx template-override functionality to
> add more text to the footer added to each HTML page, which will
> now read:
>
> # © Copyright 2021, The QEMU Project Developers.
> #
> # Built with Sphinx using a theme provided by Read the Docs.
> #
> # This documentation is for QEMU version 6.0.50.
> #
> # QEMU and this manual are released under the GNU General Public License, 
> version 2.
>
> where the last line is a hyperlink to the about/license page.
>
> I'm open to suggestions on:
>  * name of the new top-level section

"About" sounds good to me.

>  * text wording

Since Daniel reviewed already, I'd prefer to pass.

>  * whether we need to have the version number in the footer
>    (it's already in the sidebar under the QEMU logo, but this
>    seemed a bit too inconspicious, so I added it to the footer
>    since I was messing with it anyway)

No objection.

> You can find a built version of the docs at:
> https://pm215.gitlab.io/-/qemu/-/jobs/1399259647/artifacts/public/index.html

Lovely improvements overall.

> I had a look at getting our manpages to also state the license,
> but this is tricky due to various deficiencies in Sphinx.
> (We never have stated the license in our manpages, so this isn't
> a regression compared to the old texinfo setup.)

Leaving further improvement for later is okay.

> Markus: do you feel this series is sufficient that we can remove
> the TODO lines in docs/interop/qemu-ga-ref.rst,
> docs/interop/qemu-qmp-ref.rst and docs/interop/qemu-storage-daemon-qmp-ref.rst
> as now being done?

These:

    ..
       TODO: the old Texinfo manual used to note that this manual
       is GPL-v2-or-later. We should make that reader-visible
       both here and in our Sphinx manuals more generally.

    ..
       TODO: display the QEMU version, both here and in our Sphinx manuals
       more generally.

Copyright, license information and version are all visible in the page
footers.  The TODOs can go.

In the old Texinfo manual, copyright and license information was also
visible in the source, like this

    @copying
    This is the QEMU QMP 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

Such per-file notices are not strictly required, but we habitually have
them in files holding source code.  I'm okay with omitting them in these
.rst files.

However, we got a bunch of .rst files with per-file copyright and
license notices, like this:

    ===================
    Vhost-user Protocol
    ===================
    :Copyright: 2014 Virtual Open Systems Sarl.
    :Copyright: 2019 Intel Corporation
    :Licence: This work is licensed under the terms of the GNU GPL,
              version 2 or later. See the COPYING file in the top-level
              directory.

Rendered to HTML, the page has *two* blocks of copyright and license
information: the above inline, and the footer.  This is confusing.
Worse, the license information is contradictory in places, e.g. with the
above, the inline license is GPLv2 or later, but the footer is GPLv2
exactly.  I know the intent (footer applies to QEMU as a whole, inline
just to this page), but legalese should be as clear as we can make it.

Can we downgrade the inline notices to comments?

This is a separate issue we can address on top for 6.1, so:
Acked-by: Markus Armbruster <armbru@redhat.com>