From: Mauro Carvalho Chehab <mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
To: Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org>
Cc: Mike Snitzer <snitzer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>,
"Rafael J. Wysocki"
<rafael-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>,
Linus Walleij
<linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>,
Farhan Ali <alifm-tEXmvtCZX7AybS5Ee8rs3A@public.gmane.org>,
Will Deacon <will.deacon-5wv7dgnIgG8@public.gmane.org>,
dri-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW@public.gmane.org,
Jaroslav Kysela <perex-/Fr2/VpizcU@public.gmane.org>,
kernel-hardening-ZwoEplunGu1jrUoiu81ncdBPR1lH4CV8@public.gmane.org,
Christoph Hellwig <hch-jcswGhMUV9g@public.gmane.org>,
linux-arch-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-sh-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
James Morris <jmorris-gx6/JNMH7DfYtjvyW6yDsg@public.gmane.org>,
Halil Pasic <pasic-tEXmvtCZX7AybS5Ee8rs3A@public.gmane.org>,
tboot-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org,
Alan Stern
<stern-nwvwT67g6+6dFdvTe/nMLpVzexx5G7lz@public.gmane.org>,
openipmi-developer-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org,
Guenter Roeck <linux-0h96xk9xTtrk1uMJSBkQmQ@public.gmane.org>,
Boqun Feng <boqun.feng-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>,
Nicholas Piggin <npiggin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>,
Alex Williamson
<alex.williamson-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>,
Matt Mackall <mpm-VDJrAJ4Gl5ZBDgjK7y7TUQ@public.gmane.org>,
Thomas Gleixner <tglx-hfZtesqFncYOwBW4kG4KsQ@public.gmane.org>,
Sean Paul <sean-p7yTbzM4H96eqtR555YLDQ@public.gmane.org>,
Greg Kroah-Hartman
<gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org>,
linux-wireless@v
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst
Date: Wed, 24 Apr 2019 07:40:07 -0300 [thread overview]
Message-ID: <20190423232325.679c100b@coco.lan> (raw)
In-Reply-To: <20190423213816.GE16353-Jj63ApZU6fQ@public.gmane.org>
Em Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> escreveu:
> On Tue, Apr 23, 2019 at 05:05:02PM -0300, Mauro Carvalho Chehab wrote:
> > That's my view about how that specific file would be after
> > converted to ReST:
> >
> > https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames
> >
> > I don't have any troubles reading/understanding it as a plain text
> > file,
>
> If that is all the changes it would need, then I guess that's ok. Btw,
> those rst-conversion patches don't really show what got changed. Dunno
> if git can even show that properly. I diffed the two files by hand to
> see what got changed, see end of mail.
Well, you can use git show -M01 and it will likely show what
changed. The thing is that plain diff is not very good showing
diffs on text files. I suspect that using some tool like wdiff
would give a better view of such changes.
> So I guess if table in rst means, one needs to draw rows and columns, I
> guess that's ok. It's not like I have to do it every day.
Yes, for complex tables, one needs to draw rows/columns. For simple
tables, all you need to do is something like:
====== ======== ==== ======== ===
- CONT PTE PMD CONT PMD PUD
====== ======== ==== ======== ===
4K: 64K 2M 32M 1G
16K: 2M 32M 1G
64K: 2M 512M 16G
====== ======== ==== ======== ===
in order to teach Sphinx where each column starts/stops, and
(optionally) show the table titles in bold.
(that's from Documentation/arm64/hugetlbpage.rst conversion)
> But exactly this - *having* to do rst formatting would mean a lot of
> getting used to and people writing something which is not necessarily
> correct rst and someone else fixing up after them.
Yeah, one has to take the conversion effort, but once done, it should be
easy to keep it updated.
> > and its html output is also nice (although Sphinx 1.7.8 seems to
> > have some issues when parsing some cells - probably due to some bug):
> >
> > https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html
>
> I don't know how that looks in your browser but in mine those addresses
> are not in monospaced font and there's no properly reading them.
>
> And yap, the cells parsing fun I see too.
Font selection is one of the things would require some markup, as a
plain text file doesn't have font changes.
There are several ways to make it use a monospaced font.
The straight forward way would be to place everything that it is
monospaced inside ``double quotes``, with is the ReST way to mark
a literal block inside a text. IMHO, that would add too much
"noise" at the tables.
Another possibility would be to do:
.. raw:: html
<head><style>td { font-family: monospace, monospace; }</style></head>
(the double monospace here is not a mistake - it is due to a known
bug^H^H^Hfeature on some browsers[1])
[1] https://stackoverflow.com/questions/38781089/font-family-monospace-monospace
IMO, the best alternative would be to add a new class to the css file,
and use it whenever we need a table with monospaced font, e. g.:
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index e21e36cd6761..0948de6651f8 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -125,3 +125,7 @@ div[class^="highlight"] pre {
color: inherit;
}
}
+
+table.monospaced {
+ font-family: monospace, monospace;
+}
diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst
index e8a92fa0f9b2..704bad5c5130 100644
--- a/Documentation/x86/x86_64/mm.rst
+++ b/Documentation/x86/x86_64/mm.rst
@@ -18,6 +18,8 @@ Notes:
notation than "16 EB", which few will recognize at first sight as 16 exabytes.
It also shows it nicely how incredibly large 64-bit address space is.
+.. cssclass:: monospaced
+
+-----------------+------------+------------------+---------+-----------------------------------------------------------+
| Start addr | Offset | End addr | Size | VM area description |
+=================+============+==================+=========+===========================================================+
(patch on the top of this tree
https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames)
The ..cssclass:: markup on the above example will be applied just to
the table below it. So, with that, it is possible to have normal and
monospaced tables mixed (if you apply the above patch, you'll see
that just the first table will use monospaced fonts).
-
Personally, I don't care much with monospaced fonts on this table. After
all, if I want to see it monospaced, I can simply click at the
"View page source" at the browser, and it will display the file as a
plain old monospaced text file.
Thanks,
Mauro
next prev parent reply other threads:[~2019-04-24 10:40 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <cover.1555938375.git.mchehab+samsung@kernel.org>
2019-04-22 13:27 ` [PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-04-23 11:23 ` Linus Walleij
2019-04-23 12:36 ` Mauro Carvalho Chehab
2019-04-23 21:30 ` Linus Walleij
2019-04-22 13:27 ` [PATCH v2 48/79] docs: driver-model: " Mauro Carvalho Chehab
2019-04-22 14:47 ` Julia Lawall
2019-04-22 22:30 ` Guenter Roeck
[not found] ` <cover.1555938375.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
2019-04-22 13:27 ` [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files " Mauro Carvalho Chehab
[not found] ` <cda57849a6462ccc72dcd360b30068ab6a1021c4.1555938376.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
2019-04-22 16:37 ` Logan Gunthorpe
2019-04-23 8:31 ` Peter Zijlstra
[not found] ` <20190423083135.GA11158-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org>
2019-04-23 12:55 ` Mike Snitzer
[not found] ` <20190423125519.GA7104-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
2019-04-23 13:01 ` Peter Zijlstra
[not found] ` <20190423130132.GT4038-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org>
2019-04-23 13:21 ` Mike Snitzer
[not found] ` <20190423132100.GB7132-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
2019-04-23 15:07 ` Mauro Carvalho Chehab
2019-04-23 16:30 ` Jonathan Corbet
[not found] ` <20190423103053.07cf2149-T1hC0tSOHrs@public.gmane.org>
2019-04-23 17:11 ` Peter Zijlstra
[not found] ` <20190423171158.GG12232-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org>
2019-04-23 17:20 ` Borislav Petkov
[not found] ` <20190423172006.GD16353-Jj63ApZU6fQ@public.gmane.org>
2019-04-23 20:05 ` Mauro Carvalho Chehab
[not found] ` <20190423170409.7b1370ac-qA1ZUp+OV9c@public.gmane.org>
2019-04-23 21:38 ` Borislav Petkov
[not found] ` <20190423213816.GE16353-Jj63ApZU6fQ@public.gmane.org>
2019-04-23 22:06 ` Jonathan Corbet
[not found] ` <20190423160640.70c9703f-T1hC0tSOHrs@public.gmane.org>
2019-04-24 9:19 ` Borislav Petkov
2019-04-24 6:52 ` Peter Zijlstra
[not found] ` <20190424065209.GC4038-Nxj+rRp3nVydTX5a5knrm8zTDFooKrT+cvkQGrU6aU0@public.gmane.org>
2019-05-06 19:50 ` Mauro Carvalho Chehab
2019-04-24 10:40 ` Mauro Carvalho Chehab [this message]
[not found] ` <20190423232325.679c100b-qA1ZUp+OV9c@public.gmane.org>
2019-04-24 14:54 ` Borislav Petkov
[not found] ` <20190424145410.GE30142-Jj63ApZU6fQ@public.gmane.org>
2019-04-24 16:36 ` Mauro Carvalho Chehab
2019-04-23 17:53 ` Jonathan Corbet
[not found] ` <20190423115349.589c3d50-T1hC0tSOHrs@public.gmane.org>
2019-04-23 18:21 ` Peter Zijlstra
2019-04-23 20:19 ` Mauro Carvalho Chehab
[not found] ` <20190423171944.7ac6db54-qA1ZUp+OV9c@public.gmane.org>
2019-04-23 20:34 ` Jonathan Corbet
2019-04-23 17:13 ` Wes Turner
[not found] ` <CACfEFw-viqBH7tDJ8t_um5erPFnRmzuztux86+3XR0+e=YcYYA-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org>
2019-04-23 17:41 ` Peter Zijlstra
2019-04-23 17:28 ` Wes Turner
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=20190423232325.679c100b@coco.lan \
--to=mchehab+samsung-dgejt+ai2ygdnm+yrofe0a@public.gmane.org \
--cc=alex.williamson-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org \
--cc=alifm-tEXmvtCZX7AybS5Ee8rs3A@public.gmane.org \
--cc=boqun.feng-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org \
--cc=bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org \
--cc=dri-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW@public.gmane.org \
--cc=gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r@public.gmane.org \
--cc=hch-jcswGhMUV9g@public.gmane.org \
--cc=jmorris-gx6/JNMH7DfYtjvyW6yDsg@public.gmane.org \
--cc=kernel-hardening-ZwoEplunGu1jrUoiu81ncdBPR1lH4CV8@public.gmane.org \
--cc=linus.walleij-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org \
--cc=linux-0h96xk9xTtrk1uMJSBkQmQ@public.gmane.org \
--cc=linux-arch-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
--cc=linux-sh-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
--cc=linux-wireless@v \
--cc=mpm-VDJrAJ4Gl5ZBDgjK7y7TUQ@public.gmane.org \
--cc=npiggin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org \
--cc=openipmi-developer-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org \
--cc=pasic-tEXmvtCZX7AybS5Ee8rs3A@public.gmane.org \
--cc=perex-/Fr2/VpizcU@public.gmane.org \
--cc=rafael-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org \
--cc=sean-p7yTbzM4H96eqtR555YLDQ@public.gmane.org \
--cc=snitzer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org \
--cc=stern-nwvwT67g6+6dFdvTe/nMLpVzexx5G7lz@public.gmane.org \
--cc=tboot-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org \
--cc=tglx-hfZtesqFncYOwBW4kG4KsQ@public.gmane.org \
--cc=will.deacon-5wv7dgnIgG8@public.gmane.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).