Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Thu, 10 Oct 2019, Lars Kurth wrote:
> * Would we ever include API docs generated from GPLv2 code? E.g. for safety 
> use-cases?
> @Stefano, @Artem: I guess this one is for you. 
> I suppose if we would have a similar issue for a safety manual
> I am also assuming we would want to use sphinx docs and rst to generate a 
> future safety manual

Hi Lars,

Thanks for putting this email together.

In terms of formats, I don't have a preference between rst and pandoc,
but if we are going to use rst going forward, I'd say to try to use rst
for everything, including converting all the old stuff. The fewer
different formats, the better.

As I mentioned during the FuSa call, I agree with you, Andrew, and
others that it would be best to have the docs under a CC license. I do
expect that we'll end up copy/pasting snippets of in-code comments into
the docs, so I think it is important that we are allowed to do that from
a license perspective. It is great that GPLv2 allows it (we need to be
sure about this).

Yes, I expect that some docs might be automatically generated, but from
header files, not from source code. Especailly public/ header files,
which are typically BSD, not GPLv2. I cannot come up with examples of
docs we need to generated from GPLv2-only code at the moment, hopefully
there won't be any.


     
>     I wasn't planning on reusing any of the markup, and wasn't expecting to
>     use much of the text either.  I'm still considering the option of
>     defining that xen/public/* isn't the canonical description of the ABI,
>     because C is the wrong tool for the job.
>     
>     Its fine to provide a C set of headers implementing an ABI, but there is
>     a very deliberate reason why the canonical migration v2 spec is in a
>     text document.
> 
> @Stefano: as you and I believe Brian will be spending time on improving the
> ABI docs, I think we need to build some agreement here on what/how
> to do it. I was assuming that generally the consensus was to have
> docs close to the code in source, but this does not seem to be the case.
> 
> But if we do have stuff separately, ideally we would have a tool that helps
> point people editing headers to also look at the relevant docs. Otherwise it 
> will
> be hard to keep them in sync.

In general, it is a good idea to keep the docs close to the code to make
it easier to keep them up to date. But there is no one-size-fits-all
here. For public ABI descriptions, I agree with Andrew that ideally they
should not be defined as C header files.

But it is not an issue: any work that we do here won't be wasted. For
instance, we could start by adding more comments to the current header
files. Then, as a second step, take all the comments and turn them into
a proper ABI description document without any C function declarations.
It is easy to move English text around, as long as the license allows it
-- that is the only potential blocker I can see.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel