Re: [PATCH 0/4] vfs: update ->get_link() related documentation

["Tobin C. Harding" <me@tobin.cc>]

On Wed, May 01, 2019 at 03:14:23AM +0100, Al Viro wrote:
> On Tue, Apr 30, 2019 at 07:49:43PM -0600, Jonathan Corbet wrote:
> > On Wed, 1 May 2019 02:36:49 +0100
> > Al Viro <viro@zeniv.linux.org.uk> wrote:
> > 
> > > Thought I'd replied; apparently not...  Anyway, the problem with those
> > > is that there'd been a series of patches converting vfs.txt to new
> > > format; I'm not sure what Jon is going to do with it, but these are
> > > certain to conflict.  I've no objections to the contents of changes,
> > > but if that stuff is getting massive reformatting the first two
> > > probably ought to go through Jon's tree.  I can take the last two
> > > at any point.
> > > 
> > > Jon, what's the status of the format conversion?
> > 
> > Last I saw, it seemed that you wanted changes in how things were done and
> > that Tobin (added to CC) had stepped back.  Tobin, are your thoughts on
> > the matter different?  I could try to shoehorn them in for 5.2 still, I
> > guess, but perhaps the best thing to do is to just take Eric's patch, and
> > the reformatting can work around it if need be.
> 
> I can certainly apply Eric's series (or ACK it if we end up deciding to
> feed it through your tree).
> 
> Rereading my replies in that thread, I hadn't been clear back then and
> I can see how that could've been created the wronng impression. 

Yes, I had stepped back.  I thought from Al's comments that he didn't like
the current content of vfs.txt

Since the conversion set I did did not fundamentally change the content
but just moved it to the source files it seemed like this set was a dead
end.

FWIW I don't think that a _simple_ conversion for vfs.txt to vfs.rst is
useful if the VFS is to be re-documented.  It isn't trivial to do if we
want to make any use of RST features and if we do not want to then why
bother converting it?

> I do have problems with vfs.txt approach in general and I hope we end up
> with per object type documents; however, that's completely orthogonal to
> format conversion.  IOW, I have no objections whatsoever to format switch
> done first; any migration of e.g. dentry-related parts into a separate
> document, with lifecycle explicitly documented and descriptions of
> methods tied to that can just as well go on top of that.

I'd like to work on this but considering I don't know what I'm talking
about and have to learn as I go this is a long project ...

> I don't think that vfs.txt will survive in recognizable form in the long
> run, but by all means, let's get the format conversion out of the way
> first.  And bits and pieces of contents will survive in the replacement
> files when those appear.

IMO vfs.txt is so outdated the conversion really needs to be done by
someone that knows the VFS inside out.

I am more than happy to take directions on this if there is something
useful I can do.

Cheers,
Tobin.