On Fri, Jul 26, 2019 at 02:00:28PM -0300, Mauro Carvalho Chehab wrote: > Hi Joel, > > Em Fri, 26 Jul 2019 12:20:02 -0400 > Joel Fernandes <joel@xxxxxxxxxxxxxxxxx> escreveu: > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote: > > > There are 4 RCU articles that are written on html format. > > > > > > The way they are, they can't be part of the Linux Kernel > > > documentation body nor share the styles and pdf output. > > > > > > So, convert them to ReST format. > > > > > > This way, make htmldocs and make pdfdocs will produce a > > > documentation output that will be like the original ones, but > > > will be part of the Linux Kernel documentation body. > > > > > > Part of the conversion was done with the help of pandoc, but > > > the result had some broken things that had to be manually > > > fixed. > > > > This looks Ok to me, but I also nervous something could have been done > > incorrectly during the conversion. > > > > Could you list what were the "some broken things" that you had to manually > > fix to make reviewing easier? > > There are a couple of things. > > At least the pandoc's version I used here has a bug: its conversion > from html to ReST on those files only start after a <body> tag - or > when the first quiz table starts. I only discovered that adding a > <body> at the beginning of the file solve this book at the last > conversions. > > So, for most html->ReST conversions, I manually converted the first > part of the document, basically stripping html paragraph tags and > by replacing highlights by the ReST syntax. > > Also, all the quiz tables seem to assume some javascript macro or > css style that would be hiding the answer part until the mouse moves > to it. Such macro/css was not there at the kernel tree. So, the quiz > answers have the same color as the background, making them invisible. > Even if we had such macro/css, this is not portable for pdf/LaTeX output > (and I'm not sure if this would work with ePub). > > So, I ended by manually doing the table conversion. > > Finally, I double-checked if the conversions ended ok, addressing any > issues that might have heppened. > > So, after both automatic conversion and manual fixes, I opened both the > html files produced by Sphinx and the original ones and compared them > line per line (except for the indexes, as Sphinx produces them > automatically), in order to see if all information from the original > files will be there on a format close to what we have on other ReST > files, fixing any pending issues if any. Thanks, I am in the process of going through these docs today and will let you know anything I find. It would be nice to include the above challenges in the changelog as well. Some reason 'make htmldocs' needed me to install a whole bunch of dependencies this time around. By the way, that tools/memory-model/Documentation/explanation.txt is a useful little document. Well not really little with over 1000 lines ;-). But it would certainly benefit from ReST's / htmldocs ability to jump to labels and search, etc since it is so long.. thanks, - Joel
