Gui Documentation [Was Re: Latest Nist Tests Attached]

[John Darrington]

[ CCing address@hidden ]

On Sun, Dec 11, 2011 at 02:09:27PM -0800, Selma Leathem wrote:

     Concerning help for the gui, unless there are any objections I'll use 
javahelp, with the idea being that anyone in the future could easily contribute 
independent of the platform they are working on. It creates a standalone help 
that can be run from the application?similar to the likes of open office, which 
is the basis of the layout style I'll use.

I'd not heard of Javahelp before you mentioned it, but anything with those 
4 letters in the name it rings alarm bells for me.  There are numerous reasons 
why this raises concerns:

1. The use of Java based technology has always been uncertain in the GNU project
for licensing reasons.  See the text at 
http://www.gnu.org/philosophy/java-trap.html
I don't know if Javahelp itself would have such problems, however I did a 
little bit
of (very amateur) research and discovered a thread about it on the debian-legal 
mailing
list.  See http://lists.debian.org/debian-legal/2002/07/msg00044.html - it seems
there is a lot of uncertainty on that discussion.

2. I'm not sure that it would make anything any less platform dependent - at 
least not
in any practical sense.  I think a lot of people would be very annoyed at 
having to 
install an entire Java Runtime Environment merely to get help texts.

3. I wouldn't find it easier at all to contribute, since I don't haven't 
touched any
Java related technology for about 15 years.

4. It doesn't really fit the GNU standards for documentation. See 
http://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation

I understand your concern about seemless integration of the help system, and we 
need to 
improve that.  The existing system works reasonably well, but can be made 
better.
Part of the reason we haven't done so until now, is that not having anyone to 
write
help texts, there simply wasn't much point.

I had envisaged that the help texts would form a section of the user manual, 
and 
when the user clicks on the Help button, the relevant sub-section of the manual 
gets
popped up.  This way, the texts can be read as part of the manual (either 
printed
or as softcopy), or as online help.

Of course, if you are familiar with Javahelp, and want to use it to write help 
texts,
then you are certainly welcome to do so.  But I have reservations about 
distributing
such texts as part of PSPP.  They'd have to be converted to Texinfo or 
something else first,
or else you could distribute them yourself as "contrib" work.

Anyway, before we make a firm decision about the format in which the help is 
presented,
I think we should get an idea of the scale of the problem (count the number of 
help 
buttons), and write a few help texts for them - even if they are very rough 
drafts.
Then we'll get a better idea of how to solve the technical issues.

Ben, what are your thoughts?

-- 
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://keys.gnupg.net or any PGP keyserver for public key.

signature.asc
Description: Digital signature