Date: Fri, 4 Dec 2015 17:56:01 -0800
From: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
To: Josh Triplett <josh@joshtriplett.org>
Cc: linux-kernel@vger.kernel.org, mingo@kernel.org, jiangshanlai@gmail.com,
        dipankar@in.ibm.com, akpm@linux-foundation.org,
        mathieu.desnoyers@efficios.com, tglx@linutronix.de,
        peterz@infradead.org, rostedt@goodmis.org, dhowells@redhat.com,
        edumazet@google.com, dvhart@linux.intel.com, fweisbec@gmail.com,
        oleg@redhat.com, bobby.prani@gmail.com
Subject: Re: [PATCH tip/core/rcu 1/8] documentation: Record RCU requirements
Message-ID: <20151205015601.GI28602@linux.vnet.ibm.com>
Reply-To: paulmck@linux.vnet.ibm.com
References: <20151204234952.GA22805@linux.vnet.ibm.com>
 <1449273026-23633-1-git-send-email-paulmck@linux.vnet.ibm.com>
 <20151205000719.GB26663@cloud>
 <20151205003332.GG28602@linux.vnet.ibm.com>
 <20151205003842.GD26663@cloud>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20151205003842.GD26663@cloud>
User-Agent: Mutt/1.5.21 (2010-09-15)
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 3713
Lines: 68

On Fri, Dec 04, 2015 at 04:38:42PM -0800, Josh Triplett wrote:
> On Fri, Dec 04, 2015 at 04:33:32PM -0800, Paul E. McKenney wrote:
> > On Fri, Dec 04, 2015 at 04:07:19PM -0800, Josh Triplett wrote:
> > > On Fri, Dec 04, 2015 at 03:50:19PM -0800, Paul E. McKenney wrote:
> > > > This commit adds RCU requirements as published in a 2015 LWN series.
> > > > Bringing these requirements in-tree allows them to be updated as changes
> > > > are discovered.
> > > > 
> > > > Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> > > > ---
> > > >  .../RCU/Design/Requirements/2013-08-is-it-dead.png |  Bin 0 -> 100825 bytes
> > > >  .../Design/Requirements/GPpartitionReaders1.svg    |  374 +++
> > > >  .../RCU/Design/Requirements/RCUApplicability.svg   |  237 ++
> > > >  .../Design/Requirements/ReadersPartitionGP1.svg    |  639 +++++
> > > >  .../RCU/Design/Requirements/Requirements.html      | 2799 ++++++++++++++++++++
> > > >  .../RCU/Design/Requirements/Requirements.htmlx     | 2643 ++++++++++++++++++
> > > >  Documentation/RCU/Design/htmlqqz.sh                |  108 +
> > > >  7 files changed, 6800 insertions(+)
> > > >  create mode 100644 Documentation/RCU/Design/Requirements/2013-08-is-it-dead.png
> > > >  create mode 100644 Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg
> > > >  create mode 100644 Documentation/RCU/Design/Requirements/RCUApplicability.svg
> > > >  create mode 100644 Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg
> > > >  create mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
> > > >  create mode 100644 Documentation/RCU/Design/Requirements/Requirements.htmlx
> > > 
> > > If Requirements.html is machine-generated and shouldn't be hand-edited,
> > > and it can be generated without any special tools, then I don't think it
> > > should be committed in the tree; I'd suggest putting it in .gitignore
> > > and generating it from one of the various "make docs" invocations.
> > 
> > I considered doing that, but then decided that it is nice for people to
> > be able train their browser directly on the file without having to know
> > what scripts to run.
> > 
> > Hmmm...  I suppose I could construct a Makefile that dealt with that
> > though...  I will give this some thought, and if it looks good, I will
> > add the Makefiles and "git rm" the .htmlx files.
> > 
> > > Alternatively, if you want to make sure a usable version is in-tree, you
> > > could make the script reversible (easy enough to do if the compiled
> > > version includes some marker comments or similar), and then tell people
> > > to run it in reverse mode, edit, and run it in forward mode.  Then you
> > > don't need the .htmlx file at all. :)
> > 
> > Decades ago, back when I (against all evidence) believed I could
> > consistently avoid making stupid mistakes, you might have been able to
> > convince me that this was a good idea.  ;-)
> 
> Because you don't want to complicate the script, or because you don't
> want to accidentally edit the wrong version?  (Note that a carefully
> written script would mean it doesn't matter which version you edit.)

I prefer the simpler script.

> A third alternative would be to include the answers inline right after
> the questions, and optionally add a tiny bit of JavaScript that hides
> them by default and lets you click to show the answer. :)

That does have some advantages.  I would welcome a patch that added
the JavaScript.

							Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/