[v2,00/22] xfs-4.20: major documentation surgery
mbox series

Message ID 153862669110.26427.16504658853992750743.stgit@magnolia
Headers show
Series
  • xfs-4.20: major documentation surgery
Related show

Message

Darrick J. Wong Oct. 4, 2018, 4:18 a.m. UTC
Hi all,

This series converts the existing in-kernel xfs 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 Data Structures & Algorithms
book from the xfs-documentation git tree.  No changes are made to the
text during the import process except to fix things that the conversion
process (asciidoctor + pandoc) didn't do correctly.  The goal of this
series is to tie together the XFS code with the on-disk format
documentation for the features supported by the code.

I've built the docs and put them here, in case you hate reading rst:
https://djwong.org/docs/kdoc/admin-guide/xfs.html
https://djwong.org/docs/kdoc/filesystems/xfs-data-structures/index.html

I've posted a branch here because the png import patch is huge:
https://git.kernel.org/pub/scm/linux/kernel/git/djwong/xfs-linux.git/log/?h=docs-4.20-merge

The patchset should apply cleanly against 4.19-rc6.  Comments and
questions are, as always, welcome.

--D

Comments

Dave Chinner Oct. 6, 2018, 12:51 a.m. UTC | #1
On Wed, Oct 03, 2018 at 09:18:11PM -0700, Darrick J. Wong wrote:
> Hi all,
> 
> This series converts the existing in-kernel xfs 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 Data Structures & Algorithms
> book from the xfs-documentation git tree.  No changes are made to the
> text during the import process except to fix things that the conversion
> process (asciidoctor + pandoc) didn't do correctly.  The goal of this
> series is to tie together the XFS code with the on-disk format
> documentation for the features supported by the code.
> 
> I've built the docs and put them here, in case you hate reading rst:
> https://djwong.org/docs/kdoc/admin-guide/xfs.html
> https://djwong.org/docs/kdoc/filesystems/xfs-data-structures/index.html
> 
> I've posted a branch here because the png import patch is huge:
> https://git.kernel.org/pub/scm/linux/kernel/git/djwong/xfs-linux.git/log/?h=docs-4.20-merge
> 
> The patchset should apply cleanly against 4.19-rc6.  Comments and
> questions are, as always, welcome.

Jon,

Can you let us know whether the CC-by-SA 4.0 license is acceptible
or not? That's really the only thing that we need clarified at this
point - if it's OK I'll to pull this into the XFS tree for the 4.20
merge window. If not, we'll go back to the drawing board....

Cheers,

Dave.
Jonathan Corbet Oct. 6, 2018, 1:01 a.m. UTC | #2
On Sat, 6 Oct 2018 10:51:54 +1000
Dave Chinner <david@fromorbit.com> wrote:

> Can you let us know whether the CC-by-SA 4.0 license is acceptible
> or not? That's really the only thing that we need clarified at this
> point - if it's OK I'll to pull this into the XFS tree for the 4.20
> merge window. If not, we'll go back to the drawing board....

I remain pretty concerned about it, to tell the truth.  Rather than
continue to guess, though, I've called for help, and will be talking with
the LF lawyer about this next Thursday.  Before then, I can't say anything
except "I don't think this works..."

Will let you know what I hear.

jon
Dave Chinner Oct. 6, 2018, 1:09 a.m. UTC | #3
On Fri, Oct 05, 2018 at 07:01:20PM -0600, Jonathan Corbet wrote:
> On Sat, 6 Oct 2018 10:51:54 +1000
> Dave Chinner <david@fromorbit.com> wrote:
> 
> > Can you let us know whether the CC-by-SA 4.0 license is acceptible
> > or not? That's really the only thing that we need clarified at this
> > point - if it's OK I'll to pull this into the XFS tree for the 4.20
> > merge window. If not, we'll go back to the drawing board....
> 
> I remain pretty concerned about it, to tell the truth.  Rather than
> continue to guess, though, I've called for help, and will be talking with
> the LF lawyer about this next Thursday.  Before then, I can't say anything
> except "I don't think this works..."
> 
> Will let you know what I hear.

Thanks for the update, Jon. I'll put this on the backburner until I
hear back from you.

Cheers,

Dave.
Matthew Wilcox Oct. 6, 2018, 1:29 p.m. UTC | #4
On Sat, Oct 06, 2018 at 10:51:54AM +1000, Dave Chinner wrote:
> On Wed, Oct 03, 2018 at 09:18:11PM -0700, Darrick J. Wong wrote:
> > Hi all,
> > 
> > This series converts the existing in-kernel xfs 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 Data Structures & Algorithms
> > book from the xfs-documentation git tree.  No changes are made to the
> > text during the import process except to fix things that the conversion
> > process (asciidoctor + pandoc) didn't do correctly.  The goal of this
> > series is to tie together the XFS code with the on-disk format
> > documentation for the features supported by the code.
> > 
> > I've built the docs and put them here, in case you hate reading rst:
> > https://djwong.org/docs/kdoc/admin-guide/xfs.html
> > https://djwong.org/docs/kdoc/filesystems/xfs-data-structures/index.html
> > 
> > I've posted a branch here because the png import patch is huge:
> > https://git.kernel.org/pub/scm/linux/kernel/git/djwong/xfs-linux.git/log/?h=docs-4.20-merge
> > 
> > The patchset should apply cleanly against 4.19-rc6.  Comments and
> > questions are, as always, welcome.
> 
> Jon,
> 
> Can you let us know whether the CC-by-SA 4.0 license is acceptible
> or not? That's really the only thing that we need clarified at this
> point - if it's OK I'll to pull this into the XFS tree for the 4.20
> merge window. If not, we'll go back to the drawing board....

This is (obviously) not legal advice.

I had an informal chat with Bradley Kuhn at LinuxCon Japan about using
CC-BY-SA-4.0 and he indicated that I was probably better off using the
GPL-2(+) for documentation.  I've changed the XArray documentation from
CC-BY-SA-4.0 to GPL-2+.

YMMV, defer to the LF lawyer, but I thought it worth providing a data
point.
Jonathan Corbet Oct. 6, 2018, 2:10 p.m. UTC | #5
On Sat, 6 Oct 2018 06:29:51 -0700
Matthew Wilcox <willy@infradead.org> wrote:

> I had an informal chat with Bradley Kuhn at LinuxCon Japan about using
> CC-BY-SA-4.0 and he indicated that I was probably better off using the
> GPL-2(+) for documentation.  I've changed the XArray documentation from
> CC-BY-SA-4.0 to GPL-2+.

Would you consider doing the same for Documentation/core-api/idr.rst?
That's the only CC-SA SPDX tag in the kernel now, and it's a clear
example of just what I'm worried about: it pulls in a nice DOC section
from the code when you run Sphinx on it, so we're not just talking
function prototypes here.  I was likely to come knocking on your door
after my upcoming conversation anyway...:)

Thanks,

jon
Jonathan Corbet Oct. 11, 2018, 5:27 p.m. UTC | #6
On Sat, 6 Oct 2018 10:51:54 +1000
Dave Chinner <david@fromorbit.com> wrote:

> Can you let us know whether the CC-by-SA 4.0 license is acceptible
> or not? That's really the only thing that we need clarified at this
> point - if it's OK I'll to pull this into the XFS tree for the 4.20
> merge window. If not, we'll go back to the drawing board....

OK, I've had a long conversation with the LF lawyer, and she said clearly
that we really should not be introducing CC-SA material into the kernel
source tree.  It's a pain; I really do like CC-SA better for
documentation, but it's not GPL-compatible, and that creates a problem for
the processed docs.

Sorry,

jon
Dave Chinner Oct. 12, 2018, 1:33 a.m. UTC | #7
On Thu, Oct 11, 2018 at 11:27:35AM -0600, Jonathan Corbet wrote:
> On Sat, 6 Oct 2018 10:51:54 +1000 Dave Chinner
> <david@fromorbit.com> wrote:
> 
> > Can you let us know whether the CC-by-SA 4.0 license is
> > acceptible or not? That's really the only thing that we need
> > clarified at this point - if it's OK I'll to pull this into the
> > XFS tree for the 4.20 merge window. If not, we'll go back to the
> > drawing board....
> 
> OK, I've had a long conversation with the LF lawyer, and she said
> clearly that we really should not be introducing CC-SA material
> into the kernel source tree.  It's a pain; I really do like CC-SA
> better for documentation, but it's not GPL-compatible, and that
> creates a problem for the processed docs.

Ok, thanks for following upon this, Jon. We'll just keep it all in
the existing external repo and work out what to do from there.

Cheers,

Dave.
Christoph Hellwig Oct. 15, 2018, 9:55 a.m. UTC | #8
On Thu, Oct 11, 2018 at 11:27:35AM -0600, Jonathan Corbet wrote:
> On Sat, 6 Oct 2018 10:51:54 +1000
> Dave Chinner <david@fromorbit.com> wrote:
> 
> > Can you let us know whether the CC-by-SA 4.0 license is acceptible
> > or not? That's really the only thing that we need clarified at this
> > point - if it's OK I'll to pull this into the XFS tree for the 4.20
> > merge window. If not, we'll go back to the drawing board....
> 
> OK, I've had a long conversation with the LF lawyer, and she said clearly
> that we really should not be introducing CC-SA material into the kernel
> source tree.  It's a pain; I really do like CC-SA better for
> documentation, but it's not GPL-compatible, and that creates a problem for
> the processed docs.

That was exactly my concern with this patchset.

Btw, I think we have the same issue with idr.rst, and unless we can
relicense it we should drop it from the tree, as it actually includes
kernel source files.
Jonathan Corbet Oct. 15, 2018, 2:28 p.m. UTC | #9
On Mon, 15 Oct 2018 02:55:49 -0700
Christoph Hellwig <hch@infradead.org> wrote:

> > OK, I've had a long conversation with the LF lawyer, and she said clearly
> > that we really should not be introducing CC-SA material into the kernel
> > source tree.  It's a pain; I really do like CC-SA better for
> > documentation, but it's not GPL-compatible, and that creates a problem for
> > the processed docs.  
> 
> That was exactly my concern with this patchset.
> 
> Btw, I think we have the same issue with idr.rst, and unless we can
> relicense it we should drop it from the tree, as it actually includes
> kernel source files.

...and a significant DOC section at that, not just function prototypes.

I'd already asked Willy [CC'd] about this once, haven't gotten an answer
yet.  Hopefully we can address this once he comes back around.

Thanks,

jon