lkml.org 
[lkml]   [2022]   [May]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
Subject[PATCH 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

\
 
 \ /
  Last update: 2022-05-14 00:43    [W:0.098 / U:0.024 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site