Re: Minor documentation bug: license section numbering

[Eric Blake]

[adding bug-texinfo]

On 2/22/20 5:24 AM, Aaaaaa 123456789 wrote:
> Good evening,
>
> I was reading the m4 documentation you have posted at
> https://www.gnu.org/savannah-checkouts/gnu/m4/manual/m4-1.4.18/m4.html,
> and I noticed that there's a very minor bug with the included copy of
> the GPLv3 (in appendix A). The original GPLv3 text numbers its
> sections starting from 0, but your copy uses 1-based numbering,
> causing all cross-references to other sections to be off by one. (For
> instance, "You may convey a covered work in object code form under the
> terms of sections 4 and 5" at the beginning of the "Conveying
> Non-Source Forms" section should actually reference sections 5 and 6
> by your renumbering.)
> The GFDL in appendix B also uses 1-based numbering, but I'm not
> familiar with it enough to determine if there are any similar
> off-by-one errors or not.

Thanks for the report.  Both appendices are generated via verbatim 
inclusion of pre-existing .texi files from upstream, and a quick scan of 
both documents shows that they use '@enumerate 0' prior to the headings 
in question.  The html rendering is generated with 'makeinfo'.

The effect that you are seeing is not limited to m4; I see the same 
1-based html rendering in the coreutils manual, for example:
https://www.gnu.org/savannah-checkouts/gnu/coreutils/manual/coreutils.html#GNU-Free-Documentation-License
shows "1. PREAMBLE", but
info coreutils 'GNU Free Documentation License'
shows "0. PREAMBLE"

So this smells like a makeinfo bug, in that it is unable to properly 
render @enumerate 0 into something that adjusts the html rendering.  But 
it also looks like a bug that was fixed recently, because when I do 
'make -C doc html' locally with texinfo 6.6 installed (on Fedora 31), 
the html output is different: the online page used <ol>, but my local 
page used <ol start="0">.  So all that really remains is to release m4 
1.4.19 with updated gnulib dependencies (needed anyways), where the 
release process will trigger a rebuild of the web pages with newer 
makeinfo, such that the resulting web page will then have correct numbering.

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org