mbox series

[v4,0/9] docs: Convert VFS doc to RST

Message ID 20190515002913.12586-1-tobin@kernel.org (mailing list archive)
Headers show
Series docs: Convert VFS doc to RST | expand

Message

Tobin C. Harding May 15, 2019, 12:29 a.m. UTC 
Hi Jon,

Here is an updated version of the VFS doc conversion.  This series in no
way represents a final point for the VFS documentation rather it is a
small step towards getting VFS docs updated.  This series does not
update the content of vfs.txt, only does formatting.

Testing: the following produces no new build warnings

	make cleandocs
	make htmldocs 2> pre.stderr

	# apply this patch series

	make cleandocs
	make htmldocs 2> post.stderr
	diff pre.stderr post.stderr
	

thanks,
Tobin.


Tobin C. Harding (9):
  docs: filesystems: vfs: Remove space before tab
  docs: filesystems: vfs: Use uniform space after period.
  docs: filesystems: vfs: Use 72 character column width
  docs: filesystems: vfs: Use uniform spacing around headings
  docs: filesystems: vfs: Use correct initial heading
  docs: filesystems: vfs: Use SPDX identifier
  docs: filesystems: vfs: Fix pre-amble indentation
  docs: filesystems: vfs: Convert spaces to tabs
  docs: filesystems: vfs: Convert vfs.txt to RST

 Documentation/filesystems/index.rst |    1 +
 Documentation/filesystems/vfs.rst   | 1286 +++++++++++++++++++++++++++
 Documentation/filesystems/vfs.txt   | 1264 --------------------------
 3 files changed, 1287 insertions(+), 1264 deletions(-)
 create mode 100644 Documentation/filesystems/vfs.rst
 delete mode 100644 Documentation/filesystems/vfs.txt

Comments

Jonathan Corbet May 29, 2019, 10:30 p.m. UTC | #1 
On Wed, 15 May 2019 10:29:04 +1000
"Tobin C. Harding" <tobin@kernel.org> wrote:

> Here is an updated version of the VFS doc conversion.  This series in no
> way represents a final point for the VFS documentation rather it is a
> small step towards getting VFS docs updated.  This series does not
> update the content of vfs.txt, only does formatting.

I've finally gotten to this, sorry for taking so long.  Applying it to
docs-next turned out to be a bit of a chore; there have been intervening
changes to vfs.txt that we didn't want to lose.  But I did it.

Unfortunately, there's still a remaining issue.  You did a lot of list
conversions like this:

> -  struct file_system_type *fs_type: describes the filesystem, partly initialized
> +``struct file_system_type *fs_type``: describes the filesystem, partly initialized
>  	by the specific filesystem code

but that does not render the way you would like, trust me.  You really
want to use the list format, something like:

    ``struct file_system_type *fs_type``
	 describes the filesystem, partly initialized by the specific
	 filesystem code

There are, unfortunately, a lot of these to fix...  I bet it could be done
with an elisp function, but I don't have time to beat my head against that
wall right now.

Any chance you would have time to send me a followup patch fixing these
up?  I'll keep my branch with this set for now so there's no need to
rebase those.

Thanks,

jon
Tobin Harding May 30, 2019, 6:01 a.m. UTC | #2 
On Wed, May 29, 2019 at 04:30:52PM -0600, Jonathan Corbet wrote:
> On Wed, 15 May 2019 10:29:04 +1000
> "Tobin C. Harding" <tobin@kernel.org> wrote:
> 
> > Here is an updated version of the VFS doc conversion.  This series in no
> > way represents a final point for the VFS documentation rather it is a
> > small step towards getting VFS docs updated.  This series does not
> > update the content of vfs.txt, only does formatting.
> 
> I've finally gotten to this, sorry for taking so long.  Applying it to
> docs-next turned out to be a bit of a chore; there have been intervening
> changes to vfs.txt that we didn't want to lose.  But I did it.
> 
> Unfortunately, there's still a remaining issue.  You did a lot of list
> conversions like this:
> 
> > -  struct file_system_type *fs_type: describes the filesystem, partly initialized
> > +``struct file_system_type *fs_type``: describes the filesystem, partly initialized
> >  	by the specific filesystem code
> 
> but that does not render the way you would like, trust me.  You really
> want to use the list format, something like:
> 
>     ``struct file_system_type *fs_type``
> 	 describes the filesystem, partly initialized by the specific
> 	 filesystem code

Ouch!  Yes I knew this was sub-optimal, I thought the HTML looked ok.
I'll fix them up as suggested.

> There are, unfortunately, a lot of these to fix...  I bet it could be done
> with an elisp function, but I don't have time to beat my head against that
> wall right now.

oh really?  That would actually make doing this much more enticing, I've
already done all these multiple times manually - learning nothing, some
elisp games would actually teach me something.  Cheers.

> Any chance you would have time to send me a followup patch fixing these
> up?  I'll keep my branch with this set for now so there's no need to
> rebase those.

Sure thing, patches to come.

Cheers,
Tobin.
Tobin Harding June 3, 2019, 11:48 p.m. UTC | #3 
On Wed, May 29, 2019 at 04:30:52PM -0600, Jonathan Corbet wrote:
> On Wed, 15 May 2019 10:29:04 +1000
> "Tobin C. Harding" <tobin@kernel.org> wrote:
> 
> > Here is an updated version of the VFS doc conversion.  This series in no
> > way represents a final point for the VFS documentation rather it is a
> > small step towards getting VFS docs updated.  This series does not
> > update the content of vfs.txt, only does formatting.
> 
> I've finally gotten to this, sorry for taking so long.  Applying it to
> docs-next turned out to be a bit of a chore; there have been intervening
> changes to vfs.txt that we didn't want to lose.  But I did it.
> 
> Unfortunately, there's still a remaining issue.  You did a lot of list
> conversions like this:
> 
> > -  struct file_system_type *fs_type: describes the filesystem, partly initialized
> > +``struct file_system_type *fs_type``: describes the filesystem, partly initialized
> >  	by the specific filesystem code
> 
> but that does not render the way you would like, trust me.  You really
> want to use the list format, something like:
> 
>     ``struct file_system_type *fs_type``
> 	 describes the filesystem, partly initialized by the specific
> 	 filesystem code
> 
> There are, unfortunately, a lot of these to fix...  I bet it could be done
> with an elisp function, but I don't have time to beat my head against that
> wall right now.
> 
> Any chance you would have time to send me a followup patch fixing these
> up?  I'll keep my branch with this set for now so there's no need to
> rebase those.

Is this branch public Jon?  I'll work on top of this series but if the
branch is public then I can check it applies, save you having problems.

Cheers,
Tobin.
Tobin Harding June 4, 2019, 12:06 a.m. UTC | #4 
On Wed, May 29, 2019 at 04:30:52PM -0600, Jonathan Corbet wrote:
> On Wed, 15 May 2019 10:29:04 +1000
> "Tobin C. Harding" <tobin@kernel.org> wrote:
> 
> > Here is an updated version of the VFS doc conversion.  This series in no
> > way represents a final point for the VFS documentation rather it is a
> > small step towards getting VFS docs updated.  This series does not
> > update the content of vfs.txt, only does formatting.
> 
> I've finally gotten to this, sorry for taking so long.  Applying it to
> docs-next turned out to be a bit of a chore; there have been intervening
> changes to vfs.txt that we didn't want to lose.  But I did it.
> 
> Unfortunately, there's still a remaining issue.  You did a lot of list
> conversions like this:
> 
> > -  struct file_system_type *fs_type: describes the filesystem, partly initialized
> > +``struct file_system_type *fs_type``: describes the filesystem, partly initialized
> >  	by the specific filesystem code
> 
> but that does not render the way you would like, trust me.  You really
> want to use the list format, something like:
> 
>     ``struct file_system_type *fs_type``
> 	 describes the filesystem, partly initialized by the specific
> 	 filesystem code

I was doubting you at first, this renders **way** better :)


	Tobin