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: 74+ 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 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [OpenRISC] " Mauro Carvalho Chehab
2019-07-26 12:51 ` 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 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` 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 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` 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 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 06/26] docs: i2c: convert to ReST and add to driver-api bookset 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 ` [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 ` 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
2019-07-26 13:05 ` Mauro Carvalho Chehab
2019-07-26 13:05 ` Mauro Carvalho Chehab
2019-07-26 13:05 ` [OpenRISC] " 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 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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.