From: Joel Fernandes <joel@joelfernandes.org>
To: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Cc: "Paul E. McKenney" <paulmck@linux.ibm.com>,
Josh Triplett <josh@joshtriplett.org>,
Steven Rostedt <rostedt@goodmis.org>,
Mathieu Desnoyers <mathieu.desnoyers@efficios.com>,
Lai Jiangshan <jiangshanlai@gmail.com>,
Jonathan Corbet <corbet@lwn.net>,
rcu@vger.kernel.org, linux-doc@vger.kernel.org
Subject: Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
Date: Fri, 26 Jul 2019 13:55:27 -0400 [thread overview]
Message-ID: <20190726175527.GD146401@google.com> (raw)
In-Reply-To: <20190726140028.38abb5fa@coco.lan>
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@joelfernandes.org> 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
next prev parent reply other threads:[~2019-07-26 17:55 UTC|newest]
Thread overview: 57+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-07-26 12:51 [PATCH v2 00/26] ReST conversion of text files without .txt extension Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 01/26] docs: power: add it to to the main documentation index Mauro Carvalho Chehab
2019-07-31 19:03 ` Jonathan Corbet
2019-07-31 19:16 ` Mauro Carvalho Chehab
2019-07-31 19:34 ` Jonathan Corbet
2019-07-31 19:58 ` Mauro Carvalho Chehab
2019-07-31 20:02 ` Jonathan Corbet
2019-07-26 12:51 ` [PATCH v2 02/26] docs: thermal: add it to the driver API Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 04/26] docs: ubifs-authentication.md: convert to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 05/26] docs: writing-schema.md: convert from markdown " Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of docs Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 09/26] docs: ipmb: place it at driver-api and convert to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 10/26] docs: packing: move it to core-api book and adjust markups Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 11/26] docs: admin-guide: add auxdisplay files to it after conversion to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 12/26] docs: README.buddha: convert to ReST and add to m68k book Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 13/26] docs: parisc: convert to ReST and add to documentation body Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 14/26] docs: openrisc: " Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 15/26] docs: isdn: convert to ReST and add to kAPI bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide book Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 17/26] docs: fs: convert docs without extension to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 18/26] docs: fs: convert porting " Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 19/26] docs: index.rst: don't use genindex for pdf output Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 20/26] docs: wimax: convert to ReST and add to admin-guide Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 21/26] docs: mips: add to the documentation body as ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 22/26] docs: hwmon: pxe1610: convert to ReST format and add to the index Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 23/26] docs: nios2: add it to the main Documentation body Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 24/26] docs: net: convert two README files to ReST format Mauro Carvalho Chehab
2019-07-26 13:05 ` [PATCH v2 00/26] ReST conversion of text files without .txt extension Mauro Carvalho Chehab
[not found] ` <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
[not found] ` <20190726162002.GA146401@google.com>
[not found] ` <20190726140028.38abb5fa@coco.lan>
2019-07-26 17:55 ` Joel Fernandes [this message]
2019-07-26 18:45 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
2019-07-26 18:02 ` Joel Fernandes
2019-07-26 19:01 ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
2019-07-27 14:14 ` Joel Fernandes
2019-07-27 15:37 ` Mauro Carvalho Chehab
2019-07-30 22:17 ` Joel Fernandes
2019-07-30 22:57 ` Mauro Carvalho Chehab
2019-07-31 13:52 ` Alan Stern
2019-07-31 15:19 ` Akira Yokosawa
2019-07-31 20:25 ` Paul E. McKenney
2019-08-30 11:32 ` Peter Zijlstra
2019-09-01 13:35 ` Paul E. McKenney
2019-07-26 19:14 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
2019-07-30 22:06 ` Joel Fernandes
2019-07-30 21:22 ` Paul E. McKenney
2019-07-30 21:50 ` Joel Fernandes
2019-07-30 22:00 ` Mauro Carvalho Chehab
2019-07-30 22:21 ` Joel Fernandes
2019-07-30 23:00 ` Mauro Carvalho Chehab
2019-07-30 23:15 ` Joel Fernandes
2019-07-30 21:50 ` Mauro Carvalho Chehab
2019-07-30 23:37 ` Paul E. McKenney
2019-07-31 0:04 ` Paul E. McKenney
2019-07-31 0:47 ` Mauro Carvalho Chehab
2019-07-31 1:06 ` Paul E. McKenney
2019-07-31 1:33 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190726175527.GD146401@google.com \
--to=joel@joelfernandes.org \
--cc=corbet@lwn.net \
--cc=jiangshanlai@gmail.com \
--cc=josh@joshtriplett.org \
--cc=linux-doc@vger.kernel.org \
--cc=mathieu.desnoyers@efficios.com \
--cc=mchehab+samsung@kernel.org \
--cc=paulmck@linux.ibm.com \
--cc=rcu@vger.kernel.org \
--cc=rostedt@goodmis.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).