linux-kernel - Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20201014163919.4bb6f8c2@coco.lan>
Date:   Wed, 14 Oct 2020 16:39:19 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Akira Yokosawa <akiyks@...il.com>
Cc:     "Paul E. McKenney" <paulmck@...nel.org>,
        Alan Stern <stern@...land.harvard.edu>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>,
        Andrea Parri <parri.andrea@...il.com>,
        Boqun Feng <boqun.feng@...il.com>,
        Daniel Lustig <dlustig@...dia.com>,
        David Howells <dhowells@...hat.com>,
        Jade Alglave <j.alglave@....ac.uk>,
        Joel Fernandes <joel@...lfernandes.org>,
        Luc Maranget <luc.maranget@...ia.fr>,
        Nicholas Piggin <npiggin@...il.com>,
        Peter Zijlstra <peterz@...radead.org>,
        Will Deacon <will@...nel.org>, linux-arch@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for
 some files

Em Wed, 14 Oct 2020 23:14:00 +0900
Akira Yokosawa <akiyks@...il.com> escreveu:

> On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote:
> > Em Tue, 13 Oct 2020 18:58:40 -0700
> > "Paul E. McKenney" <paulmck@...nel.org> escreveu:
> >   
> >> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:  
> >>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:    
> >>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:    
> >>>>> - The sysfs.txt file was converted to ReST and renamed;
> >>>>> - The control-dependencies.txt is not at
> >>>>>   Documentation/control-dependencies.txt. As it is at the
> >>>>>   same dir as the README file, which mentions it, just
> >>>>>   remove Documentation/.
> >>>>>
> >>>>> With that, ./scripts/documentation-file-ref-check script
> >>>>> is now happy again for files under tools/.
> >>>>>
> >>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>    
> >>>>
> >>>> Queued for review and testing, likely target v5.11.    
> >>>
> >>> Instead of changing the path in the README reference, shouldn't 
> >>> tools/memory-model/control-dependencies.txt be moved to its proper 
> >>> position in .../Documentation?    
> >>
> >> You are of course quite right.  My thought is to let Mauro go ahead,
> >> given his short deadline.  We can then make this "git mv" change once
> >> v5.10-rc1 comes out, given that it should have Mauro's patches.  I have
> >> added a reminder to my calendar.  
> > 
> > Sounds like a plan to me.
> > 
> > 
> > If it helps on 5.11 plans, converting this file to ReST format is quite
> > trivial: it just needs to use "::" for C/asm code literal blocks, and 
> > to replace "(*) " by something that matches ReST syntax for lists,
> > like "(#) " or just "* ":
> > 
> > 	https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
> > 
> > See enclosed.  
> 
> I'm afraid conversion of LKMM documents to ReST is unlikely to happen
> any time soon.
> It should wait until such time comes when the auto markup tools become
> clever enough and .rst files looks exactly the same as plain .txt files.
> 
> Am I asking too much? :-)
> 
>         Thanks, Akira

Yes :-)

	$ git log --author akiyks@...il.com Documentation/sphinx
	$

The auto markup tools don't write themselves alone. Someone needs 
to write them and test if no regressions will happen with the existing
documents.

-

That's said, I suspect that one of the hardest things for something
like that to be possible is to be able to distinguish something
like:

	(some text)

From something like:

	/* some C code snippet or bash script, or other literal block */

So, at least "::" (or some other markup replacing it) is needed.

If you have some bright idea about how to implement it, feel free
to contribute with patches.

Thanks,
Mauro