Re: [security-discuss] GFDL holds the answer about fancy javascript (was: gnuradio project..)

[Jean Louis]

On Mon, Mar 06, 2017 at 01:37:20AM -0500, Alfred M. Szmidt wrote:
>    Source code is in gnuradio-3.7.10.1/docs/doxygen/other, if I am no
>    mistaken.
> 
>    And GNU radio package is to be found here:
>    http://gnuradio.org/releases/gnuradio/gnuradio-3.7.10.1.tar.gz
> 
>    Source code of documentation is not in simple format, it seems to
>    be Doxygen format. Doxygen extracts documentation from C++ files.
> 
> What is "simple format"?

The reference is to the well drafted Information for Maintainers of
GNU Software that is available here:
https://www.gnu.org/prep/maintain/maintain.html

First to review, by GNU Radio maintainers would be to read about the
documentation, License Notices for Documentation:
https://www.gnu.org/prep/maintain/maintain.html#License-Notices-for-Documentation

Documentation files should have license notices also. Manuals should
use the GNU Free Documentation License. Following is an example of the
license notice to use after the copyright line(s) using all the
features of the GFDL.

While the copyright on GNU Radio belongs to the FSF, I guess that
adding the GNU Free Documentation License should be simple matter,
that is up to the GNU Radio maintainers and FSF to do.

GNU Radio documentation currently has no license notices displayed, it
means it is licensed under the GNU GPL version as in the package.

Now, back to common sense:

- even if documentation is not currently licensed under the GFDL, and
  it should be, as it is GNU package, one of best, common sense says
  that documentation shall be readable.

Some people have put great efforts to explain how the documentation
shall be presented to the users in the GNU Free Documentation License,
which was prepared and made exactly for that purpose.

Reference is here:
https://www.gnu.org/prep/maintain/maintain.html#GNU-Free-Documentation-License

Even if GNU Radio documentation is not currently licensed by the GFDL,
and it should be, it is however a common sense that documentation
shall be given in a transparent copy, and not files that are suitable
for Doxygen processing only. Such files are not transparent, as there
are limitations imposed to read the documentation. One such limitation
is that one need to install the Doxygen software, to process the
source code to read the documentation, to generate the HTML to read
the documentation.

Further, one is prevented to revise documents straightforwardly with
generic text editors. Please read the GFDL to find the references for
my words.

Purpose of this email is to give notice to maintainers of GNU Radio
and the FSF, to bring the GNU Radio documentation on the standard as
expected for the GNU package. 

Jean Louis

P.S.

Quoting from the GFDL:

“Transparent” copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not
Transparent. An image format is not Transparent if used for any
substantial amount of text. A copy that is not “Transparent” is called
“Opaque”.

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.