GNOME Bugzilla – Bug 742580
Add an easy way to license documentation
Last modified: 2018-05-22 13:09:02 UTC
People very rarely make it obvious what license their gtk-doc documentation is under. Typically, it’s under the same license as the code it was generated from (otherwise you raise some interesting questions about whether the documentation comments in the source code are dual licenced). This should be made a bit more obvious in the generated documentation, especially in the HTML documentation which is often copied to multiple sites. How about adding a DOC_LICENSE variable to gtk-doc.make which passes some magic flags into the various gtkdoc-* utilities to: 1. Add schema.org metadata to the HTML output: http://schema.org/license 2. Add rel="license" microformat to the HTML output: http://microformats.org/wiki/rel-license 3. Add itemref="licenses" microdata to the HTML output: http://www.w3.org/TR/microdata/#attr-itemref 4. Add CC RDF metadata to the HTML output: https://wiki.creativecommons.org/Metadata 5. Add CC RDF metadata to the DocBook output: https://wiki.creativecommons.org/Metadata 6. Add a <copyright> element to the DocBook output: http://www.docbook.org/tdg/en/html/copyright.html 7. Add CC XMP metadata to the PDF output: https://wiki.creativecommons.org/XMP 8. Add a brief bit of licence text to the bottom of the index page of each output format stating the licence name and a link to the licence text. Might also want to include the full licence text somewhere, to handle the common case where the documentation is copied separately from the source code tarball? DOCBOOK_LICENSE would accept various well-defined values, e.g. the ‘Short Name’ values from https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Good_Licenses_2.
(In reply to comment #0) > People very rarely make it obvious what license their gtk-doc documentation is > under. Typically, it’s under the same license as the code it was generated from > (otherwise you raise some interesting questions about whether the documentation > comments in the source code are dual licenced). This should be made a bit more > obvious in the generated documentation, especially in the HTML documentation > which is often copied to multiple sites. It is a good idea. Thanks for the research. > > How about adding a DOC_LICENSE variable to gtk-doc.make which passes some magic > flags into the various gtkdoc-* utilities to: > 1. Add schema.org metadata to the HTML output: http://schema.org/license > 2. Add rel="license" microformat to the HTML output: > http://microformats.org/wiki/rel-license > 3. Add itemref="licenses" microdata to the HTML output: > http://www.w3.org/TR/microdata/#attr-itemref > 4. Add CC RDF metadata to the HTML output: > https://wiki.creativecommons.org/Metadata > 5. Add CC RDF metadata to the DocBook output: > https://wiki.creativecommons.org/Metadata > 6. Add a <copyright> element to the DocBook output: > http://www.docbook.org/tdg/en/html/copyright.html I think this should be <legalnotice> http://www.docbook.org/tdg/en/html/legalnotice.html > 7. Add CC XMP metadata to the PDF output: https://wiki.creativecommons.org/XMP > 8. Add a brief bit of licence text to the bottom of the index page of each > output format stating the licence name and a link to the licence text. Might > also want to include the full licence text somewhere, to handle the common case > where the documentation is copied separately from the source code tarball? > > DOCBOOK_LICENSE would accept various well-defined values, e.g. the ‘Short Name’ > values from > https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Good_Licenses_2. Let me reorder that a bit: 1. support a DOCBOOK_LICENSE var that will be passed to gtkdoc-mkdb as --license=$DOCBOOK_LICENSE 2. emit the legalnotice tag into the master doc 3. expand gtkdoc.xsl to: 1. Add schema.org metadata to the HTML output: http://schema.org/license 2. Add rel="license" microformat to the HTML output: http://microformats.org/wiki/rel-license 3. Add itemref="licenses" microdata to the HTML output: http://www.w3.org/TR/microdata/#attr-itemref 4. the rdf tags in case of CC Now 1) sounds easy. For 2) we have the problem that the master-doc is manually written (only generated on first run) and opens the question why people could not manually add the license there? For 3) we can leave the short canonical license name as a 'role' attribute in the <legalnotice>. That'd allow to do something clever on the html side. Maybe we can start from adding a license to the main-doc manually with the role attribute and patch the gtkdoc.xsl to make use of it? Can you give it a shot?
Created attachment 294875 [details] [review] xsl: Support a legalnotice/@role attribute for generating licence text To simplify adding a licence to documentation, expand the XSL file to support snippets like: <legalnotice role="CC-BY-SA"/> which will automatically add a paragraph to the title page saying the document is licenced under CC-BY-SA, and will also add a snippet to the footer of each page. If the <legalnotice> element contains content already (such as a custom legal notice paragraph), that will be used in preference to the @role attribute. But the @role attribute will always be used for the footer text. Currently supported licences are the good documentation licences from: https://fedoraproject.org/wiki/Licensing:Main#Good_Licenses_2 xsl: Split license handling out into a reusable XSL file
Created attachment 294876 [details] [review] xsl: Add basic schema.org support Mark all generated HTML pages as instances of a CreativeWork (http://schema.org/CreativeWork), and add a license property (http://schema.org/license) based on the legalnotice element. This does not add any other CreativeWork properties, although we could (and probably should) support them. That can be done later.
Created attachment 294877 [details] [review] xsl: Add license microformat to the HTML output Modify the HTML output to use the license microformat (http://microformats.org/wiki/rel-license) when linking to the license.
Created attachment 294878 [details] [review] xsl: Add HTML microdata licensing metadata to the HTML output Add a reference from the top-level item to the licence footer: http://www.w3.org/TR/microdata/#attr-itemref.
Created attachment 294879 [details] [review] xsl: Add support for Creative Commons RDF licencing metadata Add it for the title, author and corpauthor elements: https://wiki.creativecommons.org/Metadata.
Created attachment 294880 [details] [review] xsl: Add XMP Rights support to generated PDFs Use the role attribute from the legalnotice element to set the XMP Rights metadata in generated PDF files.
Created attachment 294881 [details] [review] gtkdoc-mkpdf: Always error if no tools are available If neither fop nor dblatex are installed, exit unsuccessfully rather than silently failing.
Created attachment 294882 [details] [review] gtkdoc-mkdb: Add a --license argument and DOC_LICENSE variable Support automatically including a legalnotice in the initially generated docs.xml page, with a license specified in the user’s Makefile.am as DOC_LICENSE. This should simplify bootstrapping of a reference manual with a chosen license.
Review of attachment 294881 [details] [review]: Thanks! Please remove the "https://bugzilla.gnome.org/show_bug.cgi?id=742580" bug reference as this is unrelated.
Comment on attachment 294881 [details] [review] gtkdoc-mkpdf: Always error if no tools are available Attachment 294881 [details] pushed as 71062c1 - gtkdoc-mkpdf: Always error if no tools are available
I’ve realised that this doesn’t guarantee conformance with the selected licence. For example, the GFDL requires the full licence text to be included in the manual. Do we want to go that far? It would potentially require keeping a copying of all relevant licence texts in gtk-doc. I guess that’s the only option really: for the GFDL, a COPYING-DOCS file isn’t good enough as it isn’t included in the HTML version of the docs.
Ping?
Review of attachment 294882 [details] [review]: ::: examples/Makefile.am @@ +8,3 @@ +# License the manual is under, which may differ from the module's license. +# Use short names from https://fedoraproject.org/wiki/Licensing:Main Can we use a distro neutral source for the licenses? maybe https://spdx.org/licenses/ ::: gtkdoc-mkdb.in @@ +56,3 @@ +# Supported licenses +# Short names from https://fedoraproject.org/wiki/Licensing:Main here too @@ +116,3 @@ + print "\nSee https://fedoraproject.org/wiki/Licensing:Main.\n"; + + exit 1; you can use die() to print the error and exit
Review of attachment 294875 [details] [review]: ::: licenses.xsl @@ +24,3 @@ + <xsl:when test="$role = 'Verbatim'">https://fedoraproject.org/wiki/Licensing/VerbatimLicense</xsl:when> + <xsl:when test="$role = 'Public Domain'">https://creativecommons.org/publicdomain/zero/1.0/</xsl:when> + <xsl:otherwise></xsl:otherwise> this should actually not happen, right? Maybe add a <xsl:message terminate="true"> so that if we add another license and forget to cover it here, this fires (same below).
Review of attachment 294877 [details] [review]: ::: gtk-doc.xsl @@ +449,3 @@ <xsl:choose> <xsl:when test="$uri != ''"> + <a href="{$uri}" rel="license"><xsl:value-of select="$name" /></a> can you squash that with the prev patch?
Can you rebase and squash the xsl changes? In addition it needs changes for the docs. For the GFDL, your suggestion sounds good, add the xml snippet to gtk-doc. You can then xi:include it.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #17) > Can you rebase and squash the xsl changes? In addition it needs changes for > the docs. > > For the GFDL, your suggestion sounds good, add the xml snippet to gtk-doc. > You can then xi:include it. (I am working on this, but doing the GFDL stuff is a bit trickier than I thought.)
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gtk-doc/issues/28.