Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Tue, 23 Apr 2019 12:07:38 -0300
From: Mauro Carvalho Chehab <mchehab+samsung@...nel.org>
To: Mike Snitzer <snitzer@...hat.com>
Cc: Peter Zijlstra <peterz@...radead.org>, Linux Doc Mailing List
 <linux-doc@...r.kernel.org>, Mauro Carvalho Chehab <mchehab@...radead.org>,
 linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>, 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>, Borislav Petkov <bp@...en8.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
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST
 files to *.rst

Em Tue, 23 Apr 2019 09:21:00 -0400
Mike Snitzer <snitzer@...hat.com> escreveu:

> On Tue, Apr 23 2019 at  9:01am -0400,
> Peter Zijlstra <peterz@...radead.org> wrote:
> 
> > On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote:  
> > > On Tue, Apr 23 2019 at  4:31am -0400,
> > > Peter Zijlstra <peterz@...radead.org> wrote:
> > >   
> > > > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> > > >   
> > > > >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +  
> > > > 
> > > > What's happend to atomic_t.txt, also NAK, I still occationally touch
> > > > these files.  
> > > 
> > > Seems Mauro's point is in the future we need to touch these .rst files
> > > in terms of ReST compatible changes.
> > > 
> > > I'm dreading DM documentation changes in the future.. despite Mauro and
> > > Jon Corbet informing me that ReST is simple, etc.  

ReST is simple[1], and neither Jon or me wants to burden developers to
use complex documents all over the Kernel tree. ReST is just a way to 
make the documents with similar visual. The main advantage of ReST is
that documents can be better organized, as they will be inside some
index.rst file.

[1] Ok, as any document, you could write an easy or hard to read stuff.
The way we're using on most places is to be just a coding style with
benefits. I wrote a quick 101 guide to ReST at the end, with all you
probably need to know about it.

So, for example, in the specific case of atomic_bitops, all it takes for
it to be parsed by Sphinx is to rename it to .rst. With that, it can be
added into an index.rst file, like at Documentation/driver-api/index.rst.

The document, as is, will be displayed like this:

	https://www.infradead.org/~mchehab/rst_conversion/driver-api/atomic_bitops.html?highlight=atomic_t

And the original text file can also be seen from the output data:

	https://www.infradead.org/~mchehab/rst_conversion/_sources/driver-api/atomic_bitops.rst.txt

> > 
> > Well, it _can_ be simple, I've seen examples of rst that were not far
> > from generated HTML contents. And I must give Jon credit for not
> > accepting that atrocious crap.
> > 
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/  
> 
> Right, but these changes aren't meant for our benefit.  They are for
> users who get cleaner web accessible Linux kernel docs.  Seems the
> decision has been made that the users' benefit, and broader
> modernization of Linux docs, outweighs the inconvenience for engineers
> who maintain the content of said documentation.

> This kind of thing happens a lot these days: pile on engineers, they can
> take it :/

Yes, that's the main goal: ensure that more people will see the
documents and write less crappy code. So, overall, reducing the
time we spent with reviews of bad code.


----

=================================
My 101 ReST quick reference guide
=================================

Basically, a "quick" ReST guide for those that don't want to learn it
and like to have an easy to read text document would be

1) to format documents like:

	=========
	Doc Title
	=========

	foo chapter
	===========

	bar section
	-----------

	foobar sub-section
	^^^^^^^^^^^^^^^^^^

	foobarzeta sub-sub-section
	..........................

(the actual character used to mark the titles can be different,
provided that you use the same character for the same title
level - the above is just the way *I* use, as it makes easier for
me to remember the title level).

2) remember that ReST considers new lines with same indentation as
   belonging to the same paragraph. So,

	foo
	bar

is identical to:

	foo bar

while
	foo
	   bar

will make "foo" bold, and write bar on the next line. So, if you
want to have them on two separate lines on its output, it should
be either write it as:

	foo

	bar

or you could use a list:

	- foo
	- bar

Btw, *a lot* of Kernel documents already have the above format.

3) literal values should be either inside ``foo``, `foo` or on an
   indented line after a ::, like:

	example::

		# some_command_to_be_typed

If you follow those three simple rules, your document will be properly
parsed. The above covers 90% of what we normally use.

Tables are also easy to write there, as it recognizes two ways to write
ascii tables, with are already popular ways to write them.

So, those are valid tables:

Without a title:

	===   ===============
	foo   foo description
	bar   bar description
	===   ===============


	+-------+-----------------+
	| foo   | foo description |
	+-------+-----------------+
	| bar   | bar description |
	+-------+-----------------+

(both will produce exactly the same output)

With a title:

	===== ===============
	field description
	===== ===============
	foo   foo description
	bar   bar description
	===   ===============

	+-------+-----------------+
	| field | description     |
	+=======+=================+
	| foo   | foo description |
	+-------+-----------------+
	| bar   | bar description |
	+-------+-----------------+

(both will produce exactly the same output)

This is not too different on what we usually do on documents - except that
some documents sometimes use UTF8, or a different character set to mark the
table lines. So the "conversion" is simply to follow one of the above
styles.

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.