Re: [RFC PATCH 00/13] ext4: major documentation surgery

Re: [RFC PATCH 00/13] ext4: major documentation surgery

[Theodore Y. Ts'o]

On Tue, Jul 10, 2018 at 10:16:42AM -0700, Darrick J. Wong wrote:
> Hi all,
> 
> This series converts the existing in-kernel ext4 documentation to rst
> format, links it in with the rest of the kernel's rst documetation, and
> then begins pulling in the contents of the on-disk layout page in the
> wiki.  No changes are made to the text during the import process except
> to flatten the nested tables in the old wiki page, which were very
> difficult to maintain.
> 
> I've built the docs and put them here, in case you hate reading rst:
> https://djwong.org/docs/kdoc/filesystems/ext4/index.html

I've applied these patches, but I think we still need to do some work
figuring out how to integrate the ext4 documentation into the
Linux-doc tree as a whole.

At the moment they are dropped in the middle of the "Kernel API
Documentation", by virtue of where the files are located.  Most of the
ext4.rst file probably should be moved into the user's and
administrator's guide.

I'm not sure where the best place to put the ondisk documentation.
It's probably not the user's and administrator's guide, but the Kernel
API Documentation doesn't seem like the right place.

But it should also make sense when people are browing the
Documentation source directories, too.

I'm not sure what the best way to do that might be, but maybe some of
the folks on the linux-doc list will have some suggestions.

Cheers,

					- Ted

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 00/13] ext4: major documentation surgery

[Darrick J. Wong]

On Sat, Jul 21, 2018 at 10:19:46AM -0400, Theodore Y. Ts'o wrote:
> On Tue, Jul 10, 2018 at 10:16:42AM -0700, Darrick J. Wong wrote:
> > Hi all,
> > 
> > This series converts the existing in-kernel ext4 documentation to rst
> > format, links it in with the rest of the kernel's rst documetation, and
> > then begins pulling in the contents of the on-disk layout page in the
> > wiki.  No changes are made to the text during the import process except
> > to flatten the nested tables in the old wiki page, which were very
> > difficult to maintain.
> > 
> > I've built the docs and put them here, in case you hate reading rst:
> > https://djwong.org/docs/kdoc/filesystems/ext4/index.html
> 
> I've applied these patches, but I think we still need to do some work
> figuring out how to integrate the ext4 documentation into the
> Linux-doc tree as a whole.
> 
> At the moment they are dropped in the middle of the "Kernel API
> Documentation", by virtue of where the files are located.  Most of the
> ext4.rst file probably should be moved into the user's and
> administrator's guide.

I pondered that -- maybe leave all the ext4 stuff clustered together,
but link to it from the actual user/admin guide section?

> I'm not sure where the best place to put the ondisk documentation.
> It's probably not the user's and administrator's guide, but the Kernel
> API Documentation doesn't seem like the right place.
> 
> But it should also make sense when people are browing the
> Documentation source directories, too.
> 
> I'm not sure what the best way to do that might be, but maybe some of
> the folks on the linux-doc list will have some suggestions.

I was thinking about having a separate top-level Filesystems section
where we could put user/admin guides, on-disk documentation, etc. and
leave the FS API section alone.

--D

> Cheers,
> 
> 					- Ted
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 00/13] ext4: major documentation surgery

[Theodore Y. Ts'o]

On Sat, Jul 21, 2018 at 11:19:54AM -0700, Darrick J. Wong wrote:
> 
> I pondered that -- maybe leave all the ext4 stuff clustered together,
> but link to it from the actual user/admin guide section?
>

Yeah, I think it makes keep the ext4 (and in the future, xfs, btrfs,
f2fs, etc.) files clustered together.  Is it considered OK for
individual .rst files to be linked from multiple places?

I could also see us wanting to change up the pdf boundaries.  I doubt
someone would want a single pdf with details of the VFS layer, ext4
mount options, ext4 on-disk format, xfs mount options, xfs on-disk
format, btrfs mount options, etc., all in a single "book".

> > I'm not sure what the best way to do that might be, but maybe some of
> > the folks on the linux-doc list will have some suggestions.
> 
> I was thinking about having a separate top-level Filesystems section
> where we could put user/admin guides, on-disk documentation, etc. and
> leave the FS API section alone.

I wonder if part of the problem is calling it "the API section".
Maybe we should be calling it Kernel Internals, or something like
that?

					- Ted

P.S.  Oh, and we probably want to move "The Linux Journalling API" out
of index.rst, and into a separate jbd2.rst file, and give some context
that it is the journalling layer used by ext4 and ocfs2, but it's
certainly not the only Journalling API in the kernel.

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html