[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20190423232325.679c100b@coco.lan>
Date: Wed, 24 Apr 2019 07:40:07 -0300
From: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To: Borislav Petkov <bp@...en8.de>
Cc: Peter Zijlstra <peterz@...radead.org>, Jonathan Corbet <corbet@....net>,
Mike Snitzer <snitzer@...hat.com>, Linux Doc Mailing List
<linux-doc@...r.kernel.org>, Mauro Carvalho Chehab <mchehab@...radead.org>,
linux-kernel@...r.kernel.org, Johannes Berg <johannes@...solutions.net>,
Kurt Schwemmer <kurt.schwemmer@...rosemi.com>, Logan Gunthorpe
<logang@...tatee.com>, Bjorn Helgaas <bhelgaas@...gle.com>, Alasdair Kergon
<agk@...hat.com>, dm-devel@...hat.com, Kishon Vijay Abraham I
<kishon@...com>, Rob Herring <robh+dt@...nel.org>, Mark Rutland
<mark.rutland@....com>, Bartlomiej Zolnierkiewicz
<b.zolnierkie@...sung.com>, David Airlie <airlied@...ux.ie>, Daniel Vetter
<daniel@...ll.ch>, Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
Maxime Ripard <maxime.ripard@...tlin.com>, Sean Paul <sean@...rly.run>,
Ning Sun <ning.sun@...el.com>, Ingo Molnar <mingo@...hat.com>, Will Deacon
<will.deacon@....com>, Alan Stern <stern@...land.harvard.edu>, Andrea Parri
<andrea.parri@...rulasolutions.com>, Boqun Feng <boqun.feng@...il.com>,
Nicholas Piggin <npiggin@...il.com>, David Howells <dhowells@...hat.com>,
Jade Alglave <j.alglave@....ac.uk>, Luc Maranget <luc.maranget@...ia.fr>,
"Paul E. McKenney" <paulmck@...ux.ibm.com>, Akira Yokosawa
<akiyks@...il.com>, Daniel Lustig <dlustig@...dia.com>, "David S. Miller"
<davem@...emloft.net>, Andreas Färber <afaerber@...e.de>,
Manivannan Sadhasivam <manivannan.sadhasivam@...aro.org>, Cornelia Huck
<cohuck@...hat.com>, Farhan Ali <alifm@...ux.ibm.com>, Eric Farman
<farman@...ux.ibm.com>, Halil Pasic <pasic@...ux.ibm.com>, Martin
Schwidefsky <schwidefsky@...ibm.com>, Heiko Carstens
<heiko.carstens@...ibm.com>, Harry Wei <harryxiyou@...il.com>, Alex Shi
<alex.shi@...ux.alibaba.com>, Jerry Hoemann <jerry.hoemann@....com>, Wim
Van Sebroeck <wim@...ux-watchdog.org>, Guenter Roeck <linux@...ck-us.net>,
Thomas Gleixner <tglx@...utronix.de>, "H. Peter Anvin" <hpa@...or.com>,
x86@...nel.org, Russell King <linux@...linux.org.uk>, Tony Luck
<tony.luck@...el.com>, Fenghua Yu <fenghua.yu@...el.com>, "James E.J.
Bottomley" <James.Bottomley@...senPartnership.com>, Helge Deller
<deller@....de>, Yoshinori Sato <ysato@...rs.sourceforge.jp>, Rich Felker
<dalias@...c.org>, Guan Xuetao <gxt@....edu.cn>, Jens Axboe
<axboe@...nel.dk>, Greg Kroah-Hartman <gregkh@...uxfoundation.org>, "Rafael
J. Wysocki" <rafael@...nel.org>, Arnd Bergmann <arnd@...db.de>, Matt
Mackall <mpm@...enic.com>, Herbert Xu <herbert@...dor.apana.org.au>, Corey
Minyard <minyard@....org>, Sumit Semwal <sumit.semwal@...aro.org>, Linus
Walleij <linus.walleij@...aro.org>, Bartosz Golaszewski
<bgolaszewski@...libre.com>, Darren Hart <dvhart@...radead.org>, Andy
Shevchenko <andy@...radead.org>, Stuart Hayes <stuart.w.hayes@...il.com>,
Jaroslav Kysela <perex@...ex.cz>, Alex Williamson
<alex.williamson@...hat.com>, Kirti Wankhede <kwankhede@...dia.com>,
Christoph Hellwig <hch@....de>, Marek Szyprowski
<m.szyprowski@...sung.com>, Robin Murphy <robin.murphy@....com>, Steffen
Klassert <steffen.klassert@...unet.com>, Kees Cook <keescook@...omium.org>,
Emese Revfy <re.emese@...il.com>, James Morris <jmorris@...ei.org>, "Serge
E. Hallyn" <serge@...lyn.com>, linux-wireless@...r.kernel.org,
linux-pci@...r.kernel.org, devicetree@...r.kernel.org,
dri-devel@...ts.freedesktop.org, linux-fbdev@...r.kernel.org,
tboot-devel@...ts.sourceforge.net, linux-arch@...r.kernel.org,
netdev@...r.kernel.org, linux-arm-kernel@...ts.infradead.org,
linux-s390@...r.kernel.org, kvm@...r.kernel.org,
linux-watchdog@...r.kernel.org, linux-ia64@...r.kernel.org,
linux-parisc@...r.kernel.org, linux-sh@...r.kernel.org,
sparclinux@...r.kernel.org, linux-block@...r.kernel.org,
linux-crypto@...r.kernel.org, openipmi-developer@...ts.sourceforge.net,
linaro-mm-sig@...ts.linaro.org, linux-gpio@...r.kernel.org,
platform-driver-x86@...r.kernel.org, iommu@...ts.linux-foundation.org,
linux-mm@...ck.org, kernel-hardening@...ts.openwall.com,
linux-security-module@...r.kernel.org, Changbin Du <changbin.du@...il.com>
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST
files to *.rst
Em Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <bp@...en8.de> 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
Powered by blists - more mailing lists
Confused about mailing lists and their use?
Read about mailing lists on Wikipedia
and check out these
guidelines on proper formatting of your messages.
