RE: thoughts on documentation reuse.

["Durham, David" <david.durham@intel.com>]

I would liken this to reading a book and having a glossary for acronyms.
After I read it once, I really don't want to know what IETF expands out to
be each and every time I use the acronym.

So even from a documentation standpoint, I could see the need for a
"glossary" of reused data in an appendix somewhere, but I wouldn't want to
see that extra text repeated over and over again everywhere in my
document... I don't view that as being particularly readable for anyone. 

-Dave

> -----Original Message-----
> From: Juergen Schoenwaelder [mailto:schoenw@ibr.cs.tu-bs.de]
> Sent: Friday, March 29, 2002 12:42 PM
> To: wes@hardakers.net
> Cc: sming@ops.ietf.org
> Subject: Re: thoughts on documentation reuse.
> 
> 
> 
> >>>>> Wes Hardaker writes:
> 
> Juergen> If I see a data type in a program and I need to know more
> Juergen> about it, I have to go to the place where it is defined to
> Juergen> see the details.  This is really not that hard to do.
> 
> Wes> The discussion in question centers around a notion that people
> Wes> aren't doing that.
> 
> I agree that modular systems require people to do more lookups. How
> people do these lookups is IMHO something outside the scope of a
> language definition. If you prefer to print MIBs with all IMPORTS
> resolved into one big set of definitions - no problem. It would be
> relatively easy to hack smidump so that it produces output which
> incorporates all imported definitions and thus works more or less like
> a C preprocessor (although I do not know how to deal with things like
> ifIndex - incorporate the whole ifTable??).
> 
> I personally doubt this is extremely useful (as much as I usually
> dislike reading C preprocessor output). But that is probably more
> personal taste and working style. I also doubt that it will work to
> provide little summaries that are automatically merged without
> generating some confusing output in same cases, especially if MIB
> authors tend to not read the expanded version of their documents.
> 
> I am not sure how big this problem really is and whether it really
> requires a solution in the language specification. I have heard people
> complaint that it is hard to obtain complete MIB definitions from some
> vendors and nasty to extract MIBs from RFCs. I never heard someone
> complain that looking up and imported definition was too complex once
> the MIB module was available.
> 
> /js
> 
> -- 
> Juergen Schoenwaelder    
<http://www.informatik.uni-osnabrueck.de/schoenw/>