What free manuals do we need?

What free manuals do we need?

[Richard Stallman]

I would like to make a list of the free software packages that
don't have a full set of the free manuals that they ought to have.
This is to expand the list of neeed manuals in the GNU task list.

Typically, a package ought to have both a tutorial introduction and a
reference manual (though sometimes it is possible to make one manual
do both jobs).  A good reference manual is not just a list of
functions and documentation for each one--it should be organized by
topics, and should discuss each topic as a whole, describing
individual functions as a part of that.  (Contrast the GNU Emacs Lisp
Reference Manual with the collection of Emacs Lisp doc strings.)

If a package doesn't have all the free documentation it really calls
for have, or if it isn't good enough to publish, then we have a gap.
The goal here is to make a more complete list of these gaps.

This is not limited to GNU programs (programs released under the
auspices of the GNU project).  We need documentation for all the
programs used in the GNU/Linux system (if users need to know about
them).  So please make suggestions about important non-GNU free
packages also.

Thanks.

Re: What free manuals do we need?

[Aubrey Jaffer]

   Resent-From: GNU Mailing List Maintenance <gnu@gnu.org>
   Resent-To: gnu-prog-mod-it@gnu.org
   Date: Fri, 2 Oct 1998 10:13:03 -0600
   From: Richard Stallman <rms@santafe.edu>
   Reply-To: rms@gnu.org
   X-UIDL: 6952c6578a2067675b7d5b0f0344fd81

   I would like to make a list of the free software packages that
   don't have a full set of the free manuals that they ought to have.
   This is to expand the list of neeed manuals in the GNU task list.

   Typically, a package ought to have both a tutorial introduction and a
   reference manual (though sometimes it is possible to make one manual
   do both jobs).  A good reference manual is not just a list of
   functions and documentation for each one--it should be organized by
   topics, and should discuss each topic as a whole, describing
   individual functions as a part of that.  (Contrast the GNU Emacs Lisp
   Reference Manual with the collection of Emacs Lisp doc strings.)

   If a package doesn't have all the free documentation it really calls
   for have, or if it isn't good enough to publish, then we have a gap.
   The goal here is to make a more complete list of these gaps.

   This is not limited to GNU programs (programs released under the
   auspices of the GNU project).  We need documentation for all the
   programs used in the GNU/Linux system (if users need to know about
   them).  So please make suggestions about important non-GNU free
   packages also.

   Thanks.

One problem with documentation is that it is always changing -- but
easily finding what changed is not supported by current packages.

I really miss change bars in documentation.  Computer companies used
to send out updates of documentation by just sending the (looseleaf)
sheets that changed.  In the page margin, they would mark the lines
that had changed with vertical bars.  Looking through the update
sheets, one quickly saw what changed.  It was easy to keep current.

Is there TeXinfo/HTML/emacs-font-lock support for changebars?

The only relevant package Alta-Vista finds is latex2html.  It has a
changebar `style' which puts inserts boxes before and after
paragraphs.  These intrusions change the line spacing; and whole
paragraphs are too large a region for finding single word changes.

I think it would be a great step forward for TeXinfo and/or Emacs to
support change highlighting by using a different text color for
changed text.

This might be implemented as a post-process using diff between the old
and new info files.  HTML can certainly support multiple colors,
although a program would have to be careful to insert highlights only
in text (and not markups).

I don't see any support in diff for noting columns as well as lines;
but even if whole lines are marked, this would be useful so long as
diff ignores whitespace (formatting) changes.



-- 
			     -=-=-=-=-=-
I am a guest and *not* a member of the MIT Artificial Intelligence Lab.
      My actions and comments do not reflect in any way on MIT.

Re: What free manuals do we need?

[Miguel de Icaza]

> Is there TeXinfo/HTML/emacs-font-lock support for changebars?
> 
> The only relevant package Alta-Vista finds is latex2html.  It has a
> changebar `style' which puts inserts boxes before and after
> paragraphs.  These intrusions change the line spacing; and whole
> paragraphs are too large a region for finding single word changes.

I think the wdiff command shipped with a simple script that added
latex commands to tag the changes.

Miguel.

Re: lynx-dev Re: What free manuals do we need?

[David Woolley]

> Is there TeXinfo/HTML/emacs-font-lock support for changebars?

HTML has explicit support, <INS> and <DEL>, although they are unlikely
to be used properly by most authors.

I also remember that there is a change bar preprocessor for *roff,
but maybe not a free software version.

> This might be implemented as a post-process using diff between the old
> and new info files.  HTML can certainly support multiple colors,
> although a program would have to be careful to insert highlights only
> in text (and not markups).

HTML 4.0 strict DOES NOT support colours, only styles.  Please think
in terms of marking up with INS and DEL and then letting the user define
a local style sheet to select the colours, or suppress <DEL></DEL> entirely;
that would be the proper way of using HTML.
 
> I don't see any support in diff for noting columns as well as lines;
> but even if whole lines are marked, this would be useful so long as
> diff ignores whitespace (formatting) changes.
> 

File differencers tend to get unstable at the word level and are likely
to choose the wrong set of differences.  Even MS Word doesn't try to
compute word level changes although it can be configured to track changes
to that level as you type them in.  However, I do seem to remember reading
of a wrapper for diff that will do word level differencing.

Of course, before everything went plug and play, the changes would have
been transmitted as just the differences to be used by patch to change
the document source.

[ Article read on the lynx-dev mailing list and might be rejected by the
  others ]