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.
