Hi Jonathan,
Thank you for the quick reply.
Jonathan Corbet <corbet@xxxxxxx> writes:
> Maxim Cournoyer <maxim.cournoyer@xxxxxxxxx> 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
