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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 27 Apr 2020 23:02:58 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Peter Lister <peter@...eshed.quignogs.org.uk>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Joel Becker <jlbec@...lplan.org>,
        Christoph Hellwig <hch@....de>, linux-usb@...r.kernel.org
Subject: Re: [PATCH v2 08/29] docs: filesystems: convert configfs.txt to
 ReST

Em Fri, 24 Apr 2020 18:34:17 +0100
Peter Lister <peter@...eshed.quignogs.org.uk> 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