Re: [PATCH tip/core/rcu 1/8] documentation: Record RCU requirements

From: Josh Triplett
Date: Fri Dec 04 2015 - 19:38:54 EST


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@xxxxxxxxxxxxxxxxxx>
> > > ---
> > > .../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.)

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