[dm-devel] [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Wed, 24 Apr 2019 16:54:10 +0200
Borislav Petkov <bp at alien8.de> escreveu:

> On Wed, Apr 24, 2019 at 07:40:07AM -0300, Mauro Carvalho Chehab wrote:
> > 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.  
> 
> Goes to show why kernel people wouldn't want to look at that in
> the browser. Long hex numbers are hard to read as it is - that's
> why there's even the 4-digit separator in some docs, for example:
> 0xffff_ffff_8100_0000.

IMHO, even the 0x and _ would make it harder to read. This is a way
more easy for my eyes:

	ffff ffff 8100 0000

> Not having it monospaced makes the whole thing even less readable.

Yeah, I see your point and agree with it.

Just saying that, if all I want is to check if addresses that start
with ffff80 belongs to the guard hole, or just to copy a value from 
a table into some C code, the font doesn't matter much, and, if
I care, a simple click would show it in monospaced fonts.

Looking from your PoV, something like:


|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |


is very hard to be parsed by a human eye, even with monospaced fonts.
In order to make it easier, I would replace it by:

|ffff ffff 8000 0000 |   -2    GB | ffff ffff 9fff ffff |  512 MB | kernel text mapping, mapped to physical address 0         |


> 
> That's why it is important for the markup not to get in the way of
> people looking at those files in an editor.

Fully agreed. the markups should make things easier and not
harder for people to read its contents.

Thanks,
Mauro