What free manuals do we need?

Aubrey Jaffer jaffer@ai.mit.edu
Fri Dec 4 18:05:00 GMT 1998


   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.



More information about the Gdb mailing list