Re: Documentation (Was: Re: [1.2 installation]: how to tell X to ...)
Fabien Ninoles <ninf01@castor.GEL.USherb.CA> wrote:
> On Tue, 14 Jan 1997, Daniel S. Barclay wrote:
>
> > 3. Keep in mind that it's hard to keep up with constantly-changing
> > documentation. That is, a new user probably would read all
> > the HOWTOs, README files, etc., to get started, but after that,
> > it's impossible to re-read everything just to find the changes.
> > [...]
> That's why Changelogs exists.
changelogs are fine for getting a general idea of what's been changed
in a system. but a change entry like `clarified section on feature
XYZ' isn't enough detail to find out what's *really* changed; it's
just a hint that an interested user should look further.
for years, people who write voluminous and ever-changing technical
material have used `change bars' to indicate new, changed, or deleted
content in text. i don't know whether the text formatting system that
creates the HOWTOs can deal with changebars, nor if `man' (nroff,
really) can.
a cheap and ugly way to do this would be:
cp -a /usr/doc /usr/doc.old
(install new HOWTOs, READMEs, etc.)
diff -rc /usr/doc.old /usr/doc | (your favorite pager)
this will show the changes, in context, between the last version and
the new version of all the documentation in /usr/doc, recursively. it
won't show the contents of new files, but it will tell you that they
now exist. it will also tell you that deleted files no longer exist.
(actually, i lie: the above wouldn't work because many of the files
are compressed. i suppose we'd have to uncompress *both* trees
somewhere, *then* compare them...)
a related question -- has there been any thought of moving the debian
changelog entries into the Packages files themselves? when i run
dselect and it tells me there are updates, i would like to see what
the changelogs are before necessarily choosing to update. obviously,
this could vastly increase the size of the Packages files, but perhaps
the older changelog entries could be culled after some period of
time...
john
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-user-REQUEST@lists.debian.org . Trouble? e-mail to Bruce@Pixar.com
Reply to: