[0/3] Documentation: Fix issues with Oxford Semiconductor PCIe (Tornado) 950

Hi,

 Here are fixes for the Sphinx processing warnings reported with `make 
htmldocs' for the description of the Oxford Semiconductor PCIe (Tornado) 
950 driver recently added.  I have split them into two parts so that they 
can be considered separately.

 First, Documentation/tty/ has been moved to driver-api, which I find not 
suitable for user documentation, so I have now moved the description to 
Documentation/misc-devices/.  I found no better place, but I can update 
the change again if you have a better suggestion.

 Second, actual warnings have been removed.  I have corrected quoting for 
symbol/parameter references, quoted tables and rewritten bibligraphy in
Sphinx's style.

 Third, the document has now been wired into the misc-devices document, so 
that it is not an orphan page in the HTML format anymore and it is also 
included in PDF documentation.

 I have verified the result and considered it visually sound with output 
produced by `make htmldocs' and `make pdfdocs'.

 For the latter command however I need to note that several other 
documents in our Documentation/ tree suffer from a problem that causes 
`make pdfdocs' to fail (and the failure cannot be worked around with 
make's `-k -i' options, i.e. no output is ever produced), e.g.:

Markup is unsupported in LaTeX:
filesystems/9p:: nested tables are not yet implemented.

and similarly for: filesystems/erofs, filesystems/f2fs, filesystems/ntfs, 
networking/device_drivers/ethernet/dlink/dl2k, scsi/arcmsr_spec, 
scsi/g_NCR5380, scsi/ncr53c8xx, and scsi/sym53c8xx_2.  I don't know if it 
is a known problem, possibly addressed in a newer version of tools, so 
I've thought it might be worth reporting.

 I have worked around the problem by removing the offending files, which 
let `make pdfdocs' proceed to completion.  I have spotted another problem 
there then in that the table of contents is only generated in the output 
file produced upon the second or subsequent invocations of `make pdfdocs'.  
Similarly bibligraphy links (but not the list itself).  Upon the first run 
of `make pdfdocs' on a clean Documentation/ tree the Contents section only 
has its heading and bibligraphy links are dead with `[?]' showing (the 
section is correctly populated however).  It's not clear to me if this is 
a bug in the tools used or something wrong with our Makefile system, so 
again I've thought it might be worth reporting.

 NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and 
Sphinx 1.8.4 here.

 The issues are not directly related to the changes proposed here though,
so please apply them.

  Maciej

Hi Maciej,

On Fri, 13 May 2022 23:41:57 +0100 (BST),
Maciej W. Rozycki wrote:
> Hi,
> 
[...]
> 
>  For the latter command however I need to note that several other 
> documents in our Documentation/ tree suffer from a problem that causes 
> `make pdfdocs' to fail (and the failure cannot be worked around with 
> make's `-k -i' options, i.e. no output is ever produced), e.g.:
> 
> Markup is unsupported in LaTeX:
> filesystems/9p:: nested tables are not yet implemented.
> 
> and similarly for: filesystems/erofs, filesystems/f2fs, filesystems/ntfs, 
> networking/device_drivers/ethernet/dlink/dl2k, scsi/arcmsr_spec, 
> scsi/g_NCR5380, scsi/ncr53c8xx, and scsi/sym53c8xx_2.  I don't know if it 
> is a known problem, possibly addressed in a newer version of tools, so 
> I've thought it might be worth reporting.
> 
[...]
> 
>  NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and 
> Sphinx 1.8.4 here.

As mentioned in the section titled "PDF and LaTeX builds" in
Documentation/doc-guide/sphinx.rst, "make pdfdocs" requires Sphinx 2.4 or
later.

Another hint for you.

You can say "make SPHINXDIRS=<sub dir> htmldocs pdfdocs" to
test-build docs under Documentation/<sub dir>/.
You might see false warnings of "WARNING: undefined label: ..."
which you wouldn't see in full builds, though.

Hope this helps.

I see there is no mention of the SPHINXDIRS make variable in the
doc-guide.  I'll see it can be explained somewhere in sphinx.rst.

        Thanks, Akira
> 
>  The issues are not directly related to the changes proposed here though,
> so please apply them.
> 
>   Maciej

On Sun, 15 May 2022, Akira Yokosawa wrote:

> >  NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and 
> > Sphinx 1.8.4 here.
> 
> As mentioned in the section titled "PDF and LaTeX builds" in
> Documentation/doc-guide/sphinx.rst, "make pdfdocs" requires Sphinx 2.4 or
> later.

 Ack, noted.  Note however that Documentation/Changes says:

Sphinx\ [#f1]_         1.7              sphinx-build --version
====================== ===============  ========================================
.. [#f1] Sphinx is needed only to build the Kernel documentation

Perhaps the additional requirement could be mentioned in the footnote?

[Also this is a production system and 1.8.4 is the only version available 
in the distribution it has installed, so I may not be able to upgrade for 
the foreseeable future anyway.]

> You can say "make SPHINXDIRS=<sub dir> htmldocs pdfdocs" to
> test-build docs under Documentation/<sub dir>/.
> You might see false warnings of "WARNING: undefined label: ..."
> which you wouldn't see in full builds, though.
> 
> Hope this helps.

 Sure, thanks a lot!

  Maciej