Em Tue, 23 Apr 2019 23:38:16 +0200 Borislav Petkov <bp@xxxxxxxxx> 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 -- dm-devel mailing list dm-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/dm-devel
