[libvirt] [PATCH 7/7] docs: syntax highlight code blocks using SHJS

Fri Feb 1 12:29:19 UTC 2013

At Thu, 31 Jan 2013 09:20:28 -0700,
Eric Blake wrote:
> 
> On 01/31/2013 02:47 AM, Claudio Bley wrote:
> 
> > 
> > IMO, these files are "object files", as far as the GPL v3 is
> > concerned.
> > 
> > ,----[ GPL v3 1. Source Code ]
> > | The "source code" for a work means the preferred form of the work
> > | for making modifications to it.  "Object code" means any non-source
> > | form of a work.
> > `----
> 
> That sets off alarm bells in my head.  Doesn't GPL require that if we
> distribute binary files, then WE are responsible for shipping the source
> used to produce those binaries? 

Responsible, yes. But shipping it, no.

> That is, we can't offload our obligation onto a third-party project
> - if we are going to ship binary css and js pages, then the
> libvirt-1.x.x.tar.gz tarball must include the source code that
> produces those binaries.

No, not AFAICS but IANAL.

,----[ GPL v3 1. Source Code ]
| The "Corresponding Source" for a work in object code form means all
| the source code needed to generate, install, and (for an executable
| work) run the object code and to modify the work, including scripts to
| control those activities.  However, it does not include the work's
| System Libraries, or general-purpose tools or *generally* *available* *free*
| *programs* which are used unmodified in performing those activities but
| which are not part of the work.
`----

The compression was done using the YUI Compressor
(https://github.com/yui/yuicompressor) which is a free tool and we
don't have to ship that.

,----[ GPL v3 6. Conveying Non-Source Forms. ]
| d) [...] If the place to
|     copy the object code is a network server, the *Corresponding Source*
|     may be on a different server (operated by you or a third party)
|     that supports equivalent copying facilities, provided you maintain
|     clear directions next to the object code saying where to find the
|     Corresponding Source.
`----

So, all we'd have to do is adding a file with directions on how to
obtain the Corresponding Source. This would have to be distributed
with a libvirt tarball.

Remains only this paragraph to comply to:

,----
| Regardless of what server hosts the Corresponding Source, you remain
| obligated to ensure that it is available for as long as needed to
| satisfy these requirements.
`----

Probably the easiest way would be to add it to the repo.

> And if the source code is more legible, and the formula for
> generating the minimal size binary is simple enough, then
> libvirt.git should just store the source files and the creation
> rules, not the binary files.

No, I'd say it's not that simple. At least not when it comes to
ECMAScript.

> >> Also, since you are copying from somewhere else, a comment about the
> >> original source would be appropriate.
> > 
> > Fair enough, where should I put it?
> 
> Again, if we copy the original source files, rather than a compiled
> minimal generated version, then the attribution would go as a comment in
> the copied source file.  And if the generated compiled version is not
> shipped in the tarball, then not having a copyright disclaimer/license
> in the .js file _might_ be okay.  Then again, it might not be: the FSF
> LibreJS project exists to reject execution of any javascript files that
> do not contain a clear license.
> 
> https://www.gnu.org/software/librejs/
> https://www.gnu.org/software/librejs/free-your-javascript.html

I haven't read the whole text, but I found this section in Appendix A:

,----
| As additional permission under GNU GPL version 3 section 7, you may
| distribute non-source (e.g., minimized or compacted) forms of code
| without the copy of the GNU GPL normally required by section 4,
| provided you include this license notice and a URL through which
| recipients can access the Corresponding Source.
`----

Too bad SHJS doesn't have this added to its source code. Maybe I can
get this added...

> >>> diff --git a/docs/sh_main.min.js b/docs/sh_main.min.js
> >>> new file mode 100644
> >>> index 0000000..31d1ba0
> >>> --- /dev/null
> >>> +++ b/docs/sh_main.min.js
> >>> @@ -0,0 +1,4 @@
> >>> +/* Copyright (C) 2007, 2008 gnombat at users.sourceforge.net */
> >>> +/* License: http://shjs.sourceforge.net/doc/gplv3.html */
> >>
> >> This has a copyright, but the license is incomplete - the FSF states
> >> that it is insufficient to point to a URL when using the GPLv3 (and a
> >> non-canonical URL at that); while a URL is helpful, any package shipping
> >> a GPLv3 file must also ship the full GPLv3 text as part of the
> >> package.
> > 
> > OK, I'll add a GPLv3 license file.
> 
> The more you explain what this commit is trying to add, the more I'm
> worried that we are getting ourselves into legal hot water.  People
> downloading libvirt.git and seeing GPLv3 COPYING might be worried that
> we have changed the license of overall libvirt (although our goal is to
> avoid that, and leave most things at LGPLv2+, and some of the built
> executables at GPLv2 or GPLv3 depending on libraries that they were
> linked with).

We could move the SHJS files into docs/shjs with an accompanying
LICENSE.txt. I guess that would make it sufficiently clear which files
it applies to.

> Is source code highlighting on the web page documentation really
> worth the hassles?

Having written all that above, I'm not entirely sure, anymore. I chose
SHJS just because it had a GNU license, who would have known it would
cause so much hassle by itself...

But besides, arguing with you is always worthwhile. ;)

> >> What does upstream have against whitespace?
> > 
> > It is a compressed version of the original code. Intended to cut down
> > on download time, snappier page loading.
> 
> I'm not sure whether to believe their claim, though.  sh_emacs.min.css
> already weighs about 1800 bytes, so it already transmits as 2 packets
> with an MTU of 1500.  Upstream is arguing that shaving 30 or so
> strategic newlines would cause a noticeable speedup?  I would have been
> more impressed if the compression cut a file from 2 TCP packets down to 1.

Granted, CSS compression tends not to have great potential for
compression. Removal of comments, color compression, semicolon
reduction and - well - removal of newlines doesn't buy you that much
(especially when there are no comments in the source file to begin with).

But, in general, it makes a huge difference for ECMAScript
files. sh_main.js is reduced to 35% of the original size (15 to 5 KB).

In summary, this would be required for inclusion of SHJS for
rendering:

- compressed files (if we want to use them)
- doc/shjs/LICENSE.txt
- source code of the compressed files
- edit source code of SHJS in order to have it include
  a copyright
- doc/shjs/ABOUT.txt explaining where the files
  have been obtained

Claudio

-- 
AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany
Phone: +49 341 265 310 19
Web:<http://www.av-test.org>

Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076)
Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern