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

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]

Message-ID: <20180721181954.GJ4800@magnolia>
Date:   Sat, 21 Jul 2018 11:19:54 -0700
From:   "Darrick J. Wong" <darrick.wong@...cle.com>
To:     "Theodore Y. Ts'o" <tytso@....edu>
Cc:     linux-ext4@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [RFC PATCH 00/13] ext4: major documentation surgery

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
>