Linux-arch Archive on lore.kernel.org
 help / color / Atom feed
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Akira Yokosawa <akiyks@gmail.com>
Cc: "Paul E. McKenney" <paulmck@kernel.org>,
	Alan Stern <stern@rowland.harvard.edu>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Andrea Parri <parri.andrea@gmail.com>,
	Boqun Feng <boqun.feng@gmail.com>,
	Daniel Lustig <dlustig@nvidia.com>,
	David Howells <dhowells@redhat.com>,
	Jade Alglave <j.alglave@ucl.ac.uk>,
	Joel Fernandes <joel@joelfernandes.org>,
	Luc Maranget <luc.maranget@inria.fr>,
	Nicholas Piggin <npiggin@gmail.com>,
	Peter Zijlstra <peterz@infradead.org>,
	Will Deacon <will@kernel.org>,
	linux-arch@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 02/24] tools: docs: memory-model: fix references for some files
Date: Wed, 14 Oct 2020 16:39:19 +0200
Message-ID: <20201014163919.4bb6f8c2@coco.lan> (raw)
In-Reply-To: <aaeeba66-48be-0354-8f1c-261b361ae17f@gmail.com>

Em Wed, 14 Oct 2020 23:14:00 +0900
Akira Yokosawa <akiyks@gmail.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@kernel.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@kernel.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@gmail.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

  reply index

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <cover.1602590106.git.mchehab+huawei@kernel.org>
2020-10-13 12:14 ` Mauro Carvalho Chehab
2020-10-13 16:33   ` Paul E. McKenney
2020-10-13 16:38     ` Alan Stern
2020-10-14  1:58       ` Paul E. McKenney
2020-10-14  7:56         ` Mauro Carvalho Chehab
2020-10-14 14:14           ` Akira Yokosawa
2020-10-14 14:39             ` Mauro Carvalho Chehab [this message]
2020-10-14 18:57         ` Paul E. McKenney
2020-10-15  5:15           ` Mauro Carvalho Chehab
2020-10-15 10:30             ` Peter Zijlstra

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20201014163919.4bb6f8c2@coco.lan \
    --to=mchehab+huawei@kernel.org \
    --cc=akiyks@gmail.com \
    --cc=boqun.feng@gmail.com \
    --cc=corbet@lwn.net \
    --cc=dhowells@redhat.com \
    --cc=dlustig@nvidia.com \
    --cc=j.alglave@ucl.ac.uk \
    --cc=joel@joelfernandes.org \
    --cc=linux-arch@vger.kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=luc.maranget@inria.fr \
    --cc=npiggin@gmail.com \
    --cc=parri.andrea@gmail.com \
    --cc=paulmck@kernel.org \
    --cc=peterz@infradead.org \
    --cc=stern@rowland.harvard.edu \
    --cc=will@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-arch Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-arch/0 linux-arch/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-arch linux-arch/ https://lore.kernel.org/linux-arch \
		linux-arch@vger.kernel.org
	public-inbox-index linux-arch

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-arch


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git