Re: [PATCH v2 08/29] docs: filesystems: convert configfs.txt to ReST

[Mauro Carvalho Chehab]

Em Fri, 24 Apr 2020 18:34:17 +0100
Peter Lister <peter@xxxxxxxxxxxxxxxxxxxxxxxx> escreveu:

> > -configfs - Userspace-driven kernel object configuration.
> > +=======================================================
> > +Configfs - Userspace-driven Kernel oOject Configuration
> > +=======================================================  
> 
> Typo, presumably intended to be Object, not oOject?

Yeah, sorry for the typo.

> Why amend capitalisation as part of converting to REST? Normal 
> Linux/Unix convention is lower case for things like filesystems.

This is to make things more uniform. The thing is: before the
ReST conversion, there were a mess of capitalization on titles.
Some documents all caps, others just the first letter, others
camel case and there were even some documents whose titles
were all lower case. Now, almost all documents are using the
same capitalization for titles.

> 
> > -IMPORTANT: drop_item() is void, and as such cannot fail.  When rmdir(2)
> > -is called, configfs WILL remove the item from the filesystem tree
> > -(assuming that it has no children to keep it busy).  The subsystem is
> > -responsible for responding to this.  If the subsystem has references to
> > -the item in other threads, the memory is safe.  It may take some time
> > -for the item to actually disappear from the subsystem's usage.  But it
> > -is gone from configfs.
> > +.. Important::
> > +
> > +   drop_item() is void, and as such cannot fail.  When rmdir(2)
> > +   is called, configfs WILL remove the item from the filesystem tree
> > +   (assuming that it has no children to keep it busy).  The subsystem is
> > +   responsible for responding to this.  If the subsystem has references to
> > +   the item in other threads, the memory is safe.  It may take some time
> > +   for the item to actually disappear from the subsystem's usage.  But it
> > +   is gone from configfs.  
> 
> Using a  REST admonition is probably OK but, again, why change case?
> 
> The original author used shouting caps for IMPORTANT. A change can be 
> argued for consistency or if there is an established preference for 
> style. But, if so, that's a style patch, not a conversion.

It is for consistency reasons. On all converted docs I touched, I used
the same convention for such markups: "Notes", "Important", "Warning"...

Thanks,
Mauro