Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!wuarchive!zaphod.mps.ohio-state.edu!van-bc!ubc-cs!uw-beaver!fluke!gtisqr!roger
From: roger@gtisqr.uucp (Roger Droz)
Newsgroups: comp.text
Subject: Re: SCCS-type system for documentation?
Summary: Sounds like a job for RCS to me.
Keywords: documentation current accurate automated
Message-ID: <1990Nov15.223623.10800@gtisqr.uucp>
Date: 15 Nov 90 22:36:23 GMT
References: <1990Nov5.022533.29625@nixtdc.uucp>
Distribution: na
Organization: Global Tech International Inc.
Lines: 55

In article <1990Nov5.022533.29625@nixtdc.uucp> 
jhm@nixtdc.uucp (John H. McMullen) writes:
>It sounds like SCCS or RCS, doesn't it?  However, since the documentation
>process (in our shop) doesn't *really* start to roll until the software
>hits the testing stage (how else will I know what is actually in the release?),
>there is the problem that I am lagging several months behind everyone else.

We have been experimenting with Brian Berliner's CVS at our site.  I
have been making a few hacks to it to make it more suitable for
documentation.  CVS is a front end to RCS, available from the archives
of comp.sources.unix.  The advantages over RCS are that CVS deals with
directories of files, and permits several writable copies to be checked
out at once.  

While originally developed for source code, I think it will work well for
any sort of ASCII files.  Thanks to this newsgroup, I now have a *roff
macro that sets the DT string used by the mm macro package to the date
the file was checked into RCS.  The CVS symbolic tagging capabilty
allows me to retreive the man pages that applied to a given release using
the same key as I would use to get at the corresponding version of the 
source code.  CVS is quite used to the notion that not all files change
in every release.

As you may gather from the above, we haven't yet used CVS for any really
serious (large) documentation effort.  I am posting rather than mailing
because I am interested in other's experience using a source code
control system for documentation.

>Someday, it would be nice to have something that runs through the source
>and cross-correlates references to functions and programs in my *user*
>documentation with the actual functions.  Even if it just notified me that
>a function I have referred to has been modified in some way, I could keep
>my documentation up to date.

You are dealing with fairly low level tools.  Would ctags(1) help you?

Given the name of a function, the ctags facility can show you the
function definition.  Somewhere in the vacinity should be a block of
comments giving a function description of the routine.

The file output by ctags contains the names of all functions and the
file in which they were defined.  Given a list of files that have
changed, ctags could help provide a list of functions that might have
changed.

____________
               Roger Droz       UUCP: uw-beaver!gtisqr!roger
()       ()    Maverick MICRoSystems / Global Technology International
 (_______)     Mukilteo, WA 
  (     )      
   |   |       Disclaimer: "We're all mavericks here: 
   |   |                    Each of us has our own opinions,
   (___)                    and the company has yet different ones!"