[PATCH] doc: add texinfodocs and infodocs targets

[PATCH] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

Sphinx supports generating Texinfo sources and Info documentation,
which can be navigated easily and is convenient to search (via the
indexed nodes or anchors, for example).  This is basically the same as
1f050e904dd6f2955eecbd22031d912ccb2e7683, which was recently applied
to the Linux kernel.

Signed-off-by: Maxim Cournoyer <maxim.cournoyer@savoirfairelinux.com>
---

 Makefile           |  2 +-
 doc/Makefile       | 11 +++++++++++
 doc/media/Makefile |  3 ++-
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index de5746399a..597a8886c3 100644
--- a/Makefile
+++ b/Makefile
@@ -2372,7 +2372,7 @@ tcheck:
 # Documentation targets
 # ---------------------------------------------------------------------------
 DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
-	       linkcheckdocs dochelp refcheckdocs
+	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
 	$(Q)$(MAKE) $(build)=doc $@
diff --git a/doc/Makefile b/doc/Makefile
index f5de65e927..62effd0fec 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -69,6 +69,15 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 htmldocs:
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 
+texinfodocs:
+	@$(srctree)/scripts/sphinx-pre-install --version-check
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
+
+# Note: the 'info' Make target is generated by sphinx itself when
+# running the texinfodocs target defined above.
+infodocs: texinfodocs
+	$(MAKE) -C $(BUILDDIR)/texinfo info
+
 linkcheckdocs:
 	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
 
@@ -109,6 +118,8 @@ cleandocs:
 dochelp:
 	@echo  ' U-Boot documentation in different formats from ReST:'
 	@echo  '  htmldocs        - HTML'
+	@echo  '  texinfodocs     - Texinfo'
+	@echo  '  infodocs        - Info'
 	@echo  '  latexdocs       - LaTeX'
 	@echo  '  pdfdocs         - PDF'
 	@echo  '  epubdocs        - EPUB'
diff --git a/doc/media/Makefile b/doc/media/Makefile
index b9b43a34c3..9b32258696 100644
--- a/doc/media/Makefile
+++ b/doc/media/Makefile
@@ -22,10 +22,11 @@ $(BUILDDIR)/linker_lists.h.rst: ${API}/linker_lists.h ${PARSER} $(SRC_DIR)/linke
 
 # Media build rules
 
-.PHONY: all html epub xml latex
+.PHONY: all html texinfo epub xml latex
 
 all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
 html: all
+texinfo: all
 epub: all
 xml: all
 latex: $(IMGPDF) all

base-commit: 9bd3d354a1a0712ac27c717df9ad60566b0406ee
-- 
2.38.1

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Heinrich Schuchardt]

On 12/17/22 02:51, Maxim Cournoyer wrote:
> Sphinx supports generating Texinfo sources and Info documentation,
> which can be navigated easily and is convenient to search (via the
> indexed nodes or anchors, for example).  This is basically the same as
> 1f050e904dd6f2955eecbd22031d912ccb2e7683, which was recently applied
> to the Linux kernel.
>
> Signed-off-by: Maxim Cournoyer <maxim.cournoyer@savoirfairelinux.com>
> ---
>
>   Makefile           |  2 +-
>   doc/Makefile       | 11 +++++++++++
>   doc/media/Makefile |  3 ++-
>   3 files changed, 14 insertions(+), 2 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index de5746399a..597a8886c3 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -2372,7 +2372,7 @@ tcheck:
>   # Documentation targets
>   # ---------------------------------------------------------------------------
>   DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
> -	       linkcheckdocs dochelp refcheckdocs
> +	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
>   PHONY += $(DOC_TARGETS)
>   $(DOC_TARGETS): scripts_basic FORCE
>   	$(Q)$(MAKE) $(build)=doc $@
> diff --git a/doc/Makefile b/doc/Makefile
> index f5de65e927..62effd0fec 100644
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -69,6 +69,15 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>   htmldocs:
>   	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>
> +texinfodocs:
> +	@$(srctree)/scripts/sphinx-pre-install --version-check
> +	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
> +
> +# Note: the 'info' Make target is generated by sphinx itself when
> +# running the texinfodocs target defined above.
> +infodocs: texinfodocs
> +	$(MAKE) -C $(BUILDDIR)/texinfo info
> +
>   linkcheckdocs:
>   	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
>
> @@ -109,6 +118,8 @@ cleandocs:
>   dochelp:
>   	@echo  ' U-Boot documentation in different formats from ReST:'
>   	@echo  '  htmldocs        - HTML'
> +	@echo  '  texinfodocs     - Texinfo'
> +	@echo  '  infodocs        - Info'

This does not work:

$ make infodocs
make[1]: ./scripts/sphinx-pre-install: No such file or directory

$ make texinfodocs
make[1]: ./scripts/sphinx-pre-install: No such file or directory
make[1]: *** [doc/Makefile:73: texinfodocs] Error 127
make: *** [Makefile:2378: texinfodocs] Error 2

@Tom:
Should we add a build step for each of the new targets to
.gitlab-ci.yml and .azure-pipelines.yml?

Best regards

Heinrich

>   	@echo  '  latexdocs       - LaTeX'
>   	@echo  '  pdfdocs         - PDF'
>   	@echo  '  epubdocs        - EPUB'
> diff --git a/doc/media/Makefile b/doc/media/Makefile
> index b9b43a34c3..9b32258696 100644
> --- a/doc/media/Makefile
> +++ b/doc/media/Makefile
> @@ -22,10 +22,11 @@ $(BUILDDIR)/linker_lists.h.rst: ${API}/linker_lists.h ${PARSER} $(SRC_DIR)/linke
>
>   # Media build rules
>
> -.PHONY: all html epub xml latex
> +.PHONY: all html texinfo epub xml latex
>
>   all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
>   html: all
> +texinfo: all
>   epub: all
>   xml: all
>   latex: $(IMGPDF) all
>
> base-commit: 9bd3d354a1a0712ac27c717df9ad60566b0406ee

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

Hi Heinrich,

Heinrich Schuchardt <xypron.glpk@gmx.de> writes:

> On 12/17/22 02:51, Maxim Cournoyer wrote:
>> Sphinx supports generating Texinfo sources and Info documentation,
>> which can be navigated easily and is convenient to search (via the
>> indexed nodes or anchors, for example).  This is basically the same as
>> 1f050e904dd6f2955eecbd22031d912ccb2e7683, which was recently applied
>> to the Linux kernel.
>>
>> Signed-off-by: Maxim Cournoyer <maxim.cournoyer@savoirfairelinux.com>
>> ---
>>
>>   Makefile           |  2 +-
>>   doc/Makefile       | 11 +++++++++++
>>   doc/media/Makefile |  3 ++-
>>   3 files changed, 14 insertions(+), 2 deletions(-)
>>
>> diff --git a/Makefile b/Makefile
>> index de5746399a..597a8886c3 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -2372,7 +2372,7 @@ tcheck:
>>   # Documentation targets
>>   # ---------------------------------------------------------------------------
>>   DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
>> -	       linkcheckdocs dochelp refcheckdocs
>> +	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
>>   PHONY += $(DOC_TARGETS)
>>   $(DOC_TARGETS): scripts_basic FORCE
>>   	$(Q)$(MAKE) $(build)=doc $@
>> diff --git a/doc/Makefile b/doc/Makefile
>> index f5de65e927..62effd0fec 100644
>> --- a/doc/Makefile
>> +++ b/doc/Makefile
>> @@ -69,6 +69,15 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>>   htmldocs:
>>   	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>>
>> +texinfodocs:
>> +	@$(srctree)/scripts/sphinx-pre-install --version-check
>> +	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
>> +
>> +# Note: the 'info' Make target is generated by sphinx itself when
>> +# running the texinfodocs target defined above.
>> +infodocs: texinfodocs
>> +	$(MAKE) -C $(BUILDDIR)/texinfo info
>> +
>>   linkcheckdocs:
>>   	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
>>
>> @@ -109,6 +118,8 @@ cleandocs:
>>   dochelp:
>>   	@echo  ' U-Boot documentation in different formats from ReST:'
>>   	@echo  '  htmldocs        - HTML'
>> +	@echo  '  texinfodocs     - Texinfo'
>> +	@echo  '  infodocs        - Info'
>
> This does not work:
>
> $ make infodocs
> make[1]: ./scripts/sphinx-pre-install: No such file or directory

Good catch; this is not a problem introduced by the new targets, I think
(already in the Makefile -- it must happen for other documentation
targets too, no?).  I'll look into it.

The reason I overlooked this was that I'm already patching out the
'sphinx-pre-install' script invocation in the to-become
'u-boot-documentation' Guix package, as that was problematic in the
Linux tree, which uses the same build system (I forgot why exactly,
perhaps it used sudo or wanted to setup its own virtualenvs).

-- 
Thanks,
Maxim

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Heinrich Schuchardt]

On 12/17/22 16:02, Maxim Cournoyer wrote:
> Hi Heinrich,
>
> Heinrich Schuchardt <xypron.glpk@gmx.de> writes:
>
>> On 12/17/22 02:51, Maxim Cournoyer wrote:
>>> Sphinx supports generating Texinfo sources and Info documentation,
>>> which can be navigated easily and is convenient to search (via the
>>> indexed nodes or anchors, for example).  This is basically the same as
>>> 1f050e904dd6f2955eecbd22031d912ccb2e7683, which was recently applied
>>> to the Linux kernel.
>>>
>>> Signed-off-by: Maxim Cournoyer <maxim.cournoyer@savoirfairelinux.com>
>>> ---
>>>
>>>    Makefile           |  2 +-
>>>    doc/Makefile       | 11 +++++++++++
>>>    doc/media/Makefile |  3 ++-
>>>    3 files changed, 14 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/Makefile b/Makefile
>>> index de5746399a..597a8886c3 100644
>>> --- a/Makefile
>>> +++ b/Makefile
>>> @@ -2372,7 +2372,7 @@ tcheck:
>>>    # Documentation targets
>>>    # ---------------------------------------------------------------------------
>>>    DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
>>> -	       linkcheckdocs dochelp refcheckdocs
>>> +	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
>>>    PHONY += $(DOC_TARGETS)
>>>    $(DOC_TARGETS): scripts_basic FORCE
>>>    	$(Q)$(MAKE) $(build)=doc $@
>>> diff --git a/doc/Makefile b/doc/Makefile
>>> index f5de65e927..62effd0fec 100644
>>> --- a/doc/Makefile
>>> +++ b/doc/Makefile
>>> @@ -69,6 +69,15 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>>>    htmldocs:
>>>    	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>>>
>>> +texinfodocs:
>>> +	@$(srctree)/scripts/sphinx-pre-install --version-check
>>> +	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
>>> +
>>> +# Note: the 'info' Make target is generated by sphinx itself when
>>> +# running the texinfodocs target defined above.
>>> +infodocs: texinfodocs
>>> +	$(MAKE) -C $(BUILDDIR)/texinfo info
>>> +
>>>    linkcheckdocs:
>>>    	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
>>>
>>> @@ -109,6 +118,8 @@ cleandocs:
>>>    dochelp:
>>>    	@echo  ' U-Boot documentation in different formats from ReST:'
>>>    	@echo  '  htmldocs        - HTML'
>>> +	@echo  '  texinfodocs     - Texinfo'
>>> +	@echo  '  infodocs        - Info'
>>
>> This does not work:
>>
>> $ make infodocs
>> make[1]: ./scripts/sphinx-pre-install: No such file or directory
>
> Good catch; this is not a problem introduced by the new targets, I think
> (already in the Makefile -- it must happen for other documentation
> targets too, no?).  I'll look into it.

make htmldocs is what we rely on to generate
https://u-boot.readthedocs.io. This works fine.

Best regards

Heinrich

>
> The reason I overlooked this was that I'm already patching out the
> 'sphinx-pre-install' script invocation in the to-become
> 'u-boot-documentation' Guix package, as that was problematic in the
> Linux tree, which uses the same build system (I forgot why exactly,
> perhaps it used sudo or wanted to setup its own virtualenvs).
>

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 2905 bytes --]

On Sat, Dec 17, 2022 at 01:27:52PM +0000, Heinrich Schuchardt wrote:
> On 12/17/22 02:51, Maxim Cournoyer wrote:
> > Sphinx supports generating Texinfo sources and Info documentation,
> > which can be navigated easily and is convenient to search (via the
> > indexed nodes or anchors, for example).  This is basically the same as
> > 1f050e904dd6f2955eecbd22031d912ccb2e7683, which was recently applied
> > to the Linux kernel.
> > 
> > Signed-off-by: Maxim Cournoyer <maxim.cournoyer@savoirfairelinux.com>
> > ---
> > 
> >   Makefile           |  2 +-
> >   doc/Makefile       | 11 +++++++++++
> >   doc/media/Makefile |  3 ++-
> >   3 files changed, 14 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Makefile b/Makefile
> > index de5746399a..597a8886c3 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -2372,7 +2372,7 @@ tcheck:
> >   # Documentation targets
> >   # ---------------------------------------------------------------------------
> >   DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
> > -	       linkcheckdocs dochelp refcheckdocs
> > +	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
> >   PHONY += $(DOC_TARGETS)
> >   $(DOC_TARGETS): scripts_basic FORCE
> >   	$(Q)$(MAKE) $(build)=doc $@
> > diff --git a/doc/Makefile b/doc/Makefile
> > index f5de65e927..62effd0fec 100644
> > --- a/doc/Makefile
> > +++ b/doc/Makefile
> > @@ -69,6 +69,15 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
> >   htmldocs:
> >   	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
> > 
> > +texinfodocs:
> > +	@$(srctree)/scripts/sphinx-pre-install --version-check
> > +	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
> > +
> > +# Note: the 'info' Make target is generated by sphinx itself when
> > +# running the texinfodocs target defined above.
> > +infodocs: texinfodocs
> > +	$(MAKE) -C $(BUILDDIR)/texinfo info
> > +
> >   linkcheckdocs:
> >   	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
> > 
> > @@ -109,6 +118,8 @@ cleandocs:
> >   dochelp:
> >   	@echo  ' U-Boot documentation in different formats from ReST:'
> >   	@echo  '  htmldocs        - HTML'
> > +	@echo  '  texinfodocs     - Texinfo'
> > +	@echo  '  infodocs        - Info'
> 
> This does not work:
> 
> $ make infodocs
> make[1]: ./scripts/sphinx-pre-install: No such file or directory
> 
> $ make texinfodocs
> make[1]: ./scripts/sphinx-pre-install: No such file or directory
> make[1]: *** [doc/Makefile:73: texinfodocs] Error 127
> make: *** [Makefile:2378: texinfodocs] Error 2
> 
> @Tom:
> Should we add a build step for each of the new targets to
> .gitlab-ci.yml and .azure-pipelines.yml?

We should rename the job and build all doc targets, once they've been
fixed I think.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

[PATCH] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

Sphinx supports generating Texinfo sources and Info documentation,
which can be navigated easily and is convenient to search (via the
indexed nodes or anchors, for example).

This change also causes the html output to appear under its own output
sub-directory, which makes it easier to install, since it's clean from
.doctrees or other output formats.

Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
---
 Documentation/Makefile                     | 13 ++++++++++++-
 Documentation/userspace-api/media/Makefile |  3 ++-
 Makefile                                   |  2 +-
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64d44c1ecad3..bd8dac560633 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -93,7 +93,16 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 
 htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
-	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),html,$(var)))
+
+texinfodocs:
+	@$(srctree)/scripts/sphinx-pre-install --version-check
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
+
+# Note: the 'info' Make target is generated by sphinx itself when
+# running the texinfodocs target define above.
+infodocs: texinfodocs
+	$(MAKE) -C $(BUILDDIR)/texinfo info
 
 linkcheckdocs:
 	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
@@ -143,6 +152,8 @@ cleandocs:
 dochelp:
 	@echo  ' Linux kernel internal documentation in different formats from ReST:'
 	@echo  '  htmldocs        - HTML'
+	@echo  '  texinfodocs     - Texinfo'
+	@echo  '  infodocs        - Info'
 	@echo  '  latexdocs       - LaTeX'
 	@echo  '  pdfdocs         - PDF'
 	@echo  '  epubdocs        - EPUB'
diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile
index 00922aa7efde..3d8aaf5c253b 100644
--- a/Documentation/userspace-api/media/Makefile
+++ b/Documentation/userspace-api/media/Makefile
@@ -47,10 +47,11 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
 
 # Media build rules
 
-.PHONY: all html epub xml latex
+.PHONY: all html texinfo epub xml latex
 
 all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
 html: all
+texinfo: all
 epub: all
 xml: all
 latex: $(IMGPDF) all
diff --git a/Makefile b/Makefile
index 58cd4f5e1c3a..b3266c408b6c 100644
--- a/Makefile
+++ b/Makefile
@@ -1785,7 +1785,7 @@ $(help-board-dirs): help-%:
 # Documentation targets
 # ---------------------------------------------------------------------------
 DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
-	       linkcheckdocs dochelp refcheckdocs
+	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS):
 	$(Q)$(MAKE) $(build)=Documentation $@

base-commit: 81e7cfa3a9eb4ba6993a9c71772fdab21bc5d870
-- 
2.38.1

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Jonathan Corbet]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Sphinx supports generating Texinfo sources and Info documentation,
> which can be navigated easily and is convenient to search (via the
> indexed nodes or anchors, for example).

Can you tell me a bit more about the use case for this?  Nobody has
asked for it so far...  I'm not really opposed to adding it, but it
would be nice to know why.

> This change also causes the html output to appear under its own output
> sub-directory, which makes it easier to install, since it's clean from
> .doctrees or other output formats.

"This change also ... " is a red flag saying that you should have split
it into a separate patch.

That change may be a bit harder to accept, since it's a behavioral
change that will certainly annoy some people.  At a minimum, it would
have to be coordinated with the automated docs builds at kernel.org.
One could certainly make the case that we should have done things this
way from the beginning; I'm a bit reluctant to change it now.

Thanks,

jon

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

Hi Jonathan,

Thank you for the quick reply.

Jonathan Corbet <corbet@lwn.net> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Sphinx supports generating Texinfo sources and Info documentation,
>> which can be navigated easily and is convenient to search (via the
>> indexed nodes or anchors, for example).

> Can you tell me a bit more about the use case for this?  Nobody has
> asked for it so far...  I'm not really opposed to adding it, but it
> would be nice to know why.

I didn't know about Texinfo much at all until I started using Guix
System, where is it used extensively as the main documentation system.
Since then I've grown to appreciate it, even favor it most of the time,
to HTML docs due to it being usable offline even when only a terminal
emulator is available, and matching the version of the software
installed.  In contrast with man pages, which are typically very flat,
info manual can be organized into sections that are rendered into menus
that can be navigated using just a keyboard.  Another point is size.
The compressed TheLinuxKernel.info.gz info documentation weighs 12 MiB
on disk, compared to 183 MiB for the HTML version.

In short, Texinfo gives you the organization/navigability of HTML in a
format that can be used anywhere, even on headless servers.  When the
document is well indexed, it's even faster than HTML at helping you find
something, via e.g.:

$ info TheLinuxKernel i rcu_ TAB
--8<---------------cut here---------------start------------->8---
40 completions:
rcu_access_pointer (C macro)               rcu_pointer_handoff (C macro)
rcu_assign_pointer (C macro)               RCU_POINTER_INITIALIZER (C macro)
rcu_barrier (C function)                   rcu_read_lock (C function)
rcu_dereference (C macro)                  rcu_read_lock_bh (C function)
rcu_dereference_bh (C macro)               rcu_read_lock_bh_held (C function)
rcu_dereference_bh_check (C macro)         rcu_read_lock_held (C function)
rcu_dereference_check (C macro)            rcu_read_lock_held_common (C function)
rcu_dereference_protected (C macro)        rcu_read_lock_sched (C function)
rcu_dereference_sched (C macro)            rcu_read_unlock (C function)
rcu_dereference_sched_check (C macro)      rcu_read_unlock_bh (C function)
rcu_expedite_gp (C function)               rcu_read_unlock_sched (C function)
rcu_head_after_call_rcu (C function)       rcu_replace_pointer (C macro)
rcu_head_init (C function)                 rcu_sync_dtor (C function)
RCU_INIT_POINTER (C macro)                 rcu_sync_enter (C function)
RCU_INITIALIZER (C macro)                  rcu_sync_enter_start (C function)
rcu_irq_exit_check_preempt (C function)    rcu_sync_exit (C function)
rcu_is_cpu_rrupt_from_idle (C function)    rcu_sync_func (C function)
rcu_is_watching (C function)               rcu_sync_init (C function)
RCU_LOCKDEP_WARN (C macro)                 rcu_sync_is_idle (C function)
RCU_NONIDLE (C macro)                      rcu_unexpedite_gp (C function)
--8<---------------cut here---------------end--------------->8---

rcu_barr TAB -> rcu_barrier (C function)
--8<---------------cut here---------------start------------->8---

 -- Function: void rcu_barrier (void)

     Wait until all in-flight *note call_rcu(): 4188. callbacks
     complete.

‘Parameters’

‘void’

     no arguments

‘Description’
[...]
--8<---------------cut here---------------end--------------->8---

Unfortunately only the kernel API seems to be indexed for now.  I was
trying to find the supported kernel boot parameters, but no index
appeared to be registered for it.  In these cases, one can always
fall-back to plain text search (regexp) via C-s, or navigate the menus
like you would in HTML:

$ info TheLinuxKernel
--8<---------------cut here---------------start------------->8---
* Menu:

* Licensing documentation::
* User-oriented documentation::
* Firmware-related documentation::
* Application-developer documentation::
* Introduction to kernel development::
* Kernel API documentation::
* Architecture-agnostic documentation::
* Architecture-specific documentation::
* Other documentation::
* Translations: Translations<2>.
* Indices and tables::
* Index::
--8<---------------cut here---------------end--------------->8---

Press 2 or m 'User-' TAB' to enter the 2nd section.
--8<---------------cut here---------------start------------->8---
Next: Firmware-related documentation,  Prev: Licensing documentation,  Up: Top

2 User-oriented documentation
*****************************

The following manuals are written for ‘users’ of the kernel — those who
are trying to get it to work optimally on a given system.

* Menu:

* The Linux kernel user’s and administrator’s guide::
* Kernel Build System::

--8<---------------cut here---------------end--------------->8---

Press 1 to select the first entry.
--8<---------------cut here---------------start------------->8---
Next: Kernel Build System,  Up: User-oriented documentation

2.1 The Linux kernel user’s and administrator’s guide
=====================================================

The following is a collection of user-oriented documents that have been

[...]
* Menu:

* GNU Linux-libre <http;//linux-libre.fsfla.org>: GNU Linux-libre <http //linux-libre fsfla org>.
* The kernel’s command-line parameters::
[...]
--8<---------------cut here---------------end--------------->8---

Press 2.  The section "2.1.2 The kernel’s command-line parameters" is
now displayed.

If you know the name of the section and if it doesn't contain funny
characters, you can jump straight to it from the command line, like so:

$ info '(TheLinuxKernel) cpu lists'

Anyway, I hope I was able to demonstrate some of the strengths of
Texinfo with the above.  In case your interest is piqued, 'info info'
has it all.

>> This change also causes the html output to appear under its own
>> output sub-directory, which makes it easier to install, since it's
>> clean from .doctrees or other output formats.
>
> "This change also ... " is a red flag saying that you should have split
> it into a separate patch.
>
> That change may be a bit harder to accept, since it's a behavioral
> change that will certainly annoy some people.  At a minimum, it would
> have to be coordinated with the automated docs builds at kernel.org.
> One could certainly make the case that we should have done things this
> way from the beginning; I'm a bit reluctant to change it now.

I'll split the html prefix change in a v2, and it can be discussed
separately.

-- 
Thanks,
Maxim