RE: thoughts on documentation reuse.

[Andy Bierman <abierman@cisco.com>]

At 08:18 AM 3/25/2002, Ayers, Mike wrote:

>> From: Andy Bierman [mailto:abierman@cisco.com] 
>> Sent: Saturday, March 23, 2002 04:58 PM
>
>> They already have to follow references for TCs.
>> I think the problem is that it's not very clear where they
>> should look for the TC definitions.
>
>        ??????
>
>        From RFC3231 (chosen at random):
>
><SNIP>
>   IMPORTS
>       MODULE-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE,
>       Integer32, Unsigned32, Counter32, mib-2, zeroDotZero
>           FROM SNMPv2-SMI
>
>       TEXTUAL-CONVENTION,
>       DateAndTime, RowStatus, StorageType, VariablePointer
>           FROM SNMPv2-TC
>
>       MODULE-COMPLIANCE, OBJECT-GROUP, NOTIFICATION-GROUP
>           FROM SNMPv2-CONF
>
>       SnmpAdminString
>           FROM SNMP-FRAMEWORK-MIB;
></SNIP>
>
>        And I keep all my MIBs in one directory, so I need merely:
>
>$ grep "SNMPv2-TC *DEFINITIONS" *
>
>        ...which yields a list of all versions of the MIB.  I do a `more` on
>the most recent (highest numbered) one, and search for, say, "RowStatus",
>which puts me exactly at the definition.  I don't often say things like
>this, but anyone who has trouble with this simply hasn't put any effort into
>the problem.

This requires that you do all the prep work of extracting MIBs from RFCs.
I don't think this problem of finding types is very important. It's
not the reason MIBs can be difficult to use.  Personally, I don't
want types expanded at every use. If others want 14 pages of text
inserted at every instance of a RowStatus object, that's fine for them.



>>  I like having the local
>> TCs defined at the top of the MIB, and not cut-and-pasted
>> for every object instance in the MIB.
>
>        Who wouldn't?  Have you actually seen this in IETF MIBs?
>
>>  But if people really wanted
>> a tool that expanded referenced types inline, it should be
>> fairly easy to create such a tool. 
>
>        So easy that I wonder why we're having this discussion.

Agreed -- somebody who wants this tool can go create and maintain
it for everyone.


>> We need to rethink our TC procedures as they become TYPEDEFs.
>> Steve Waldbusser suggested in the RMONMIB WG meeting that maybe
>> IANA should maintain common TC modules.
>
>        They're not numbers, so maintaining them as such should raise at
>least an itty bitty warning klaxon...?
>
>>  I think this idea
>> is worth investigating. If there were well-defined modules
>> based on functionality (like stdlib, string, time, inetaddr, etc.)
>> that could be modified without waiting a year to get an RFC out,
>> then people would be more willing to use them.
>
>        Hmmm...?  First, I don't think we have a problem with willingness to
>use.  The problem I've seen has been the lack of TCs to use when the
>situation merits them (e.g. a full length UTF-8 string).  We do agree that
>there has been a problem with delivering new TCs, but disagree about the
>solution, most likely because we disagree about the cause.  I think that
>turning the TCs over to IANA so that they can be easily modified will simply
>result in a flood of TCs that don't get used.  IMHO, the problem with TCs
>has been the reticent attitude floating about that refuses to do any
>maintenance work (TCs, encryption algorithms, etc.) on SNMP, claiming that
>such work would give the impression that SNMPv3 is unstable.  So long as
>this attitude of "don't change the oil, the neighbors will think the car's
>unreliable" persists, changing the mechanics of TC definition and
>importation will not improve things.

I've seen many times in WG meetings (even my own!) where the group
recognized that a TC or even MIB objects really belong in a
different document, but are totally unwilling to delay their
own work so that another group can take ownership of the problem, 
revise their charter, publish an I-D, go through Last Calls,
and finally the RFC Editor will publish something. It saves
at least a year to just leave the misplaced definitions alone.

This is different than the ridiculous argument that if we just let
SNMPv3 lie still long enough, vendors and operators will flock
to it like it was undiscovered treasure.


>> As we start using more complex TYPEDEFs instead of simple TCs,
>> some changes may be needed:
>> 
>> 1) Versioning
>
>        This is not only unnecessary, it is an invitation to bad
>engineering.  There is a simple versioning scheme in place right now: if you
>change the functionality, you have created a new TC, if you enhance the
>functionality (old and new software can interact fully without using the new
>stuff, but new and new will use it), then you may keep the name the same.
>This is based on the fact that the only thing that matters in the field is
>whether or not older and newer implementations can interoperate.  All else
>is fluff.

So I change the name of FooType to BarType if it changes.
This is remarkably similar to changing FooTypeV1 to FooTypeV2
except the user has a clue what happened. This issue doesn't
exist with TCs today, because they are only for base types,
and only trivial changes are allowed.  If I add a new field
to a struct, then how does a user of the BAR-MIB tell which
version of FooType is actually used?  I would rather be
able to change a struct if needed.  I would rather not
have versioning either, but given the history of protecting
people from their own mistakes, I don't know if this will be accepted.



>> 2) Relocation
>>    It's not always easy to recognize that a TYPEDEF is defined in the
>>    wrong place (e.g., RMON OwnerString).  It might be useful to have
>>    a RELOCATED clause in the TYPEDEF, to let humans and machines
>>    know the FooType in the FOO-MIB is the same FooType in a IANA
>>    common type module.
>
>        Perhaps I am missing something, but I find the IMPORTS clause
>already does what you want.  ???

We don't have the ability to move a TC once it's already been defined
in a MIB.  MIB tools don't handle this well at all, like OwnerString
in RMON-MIB and then in IF-MIB as well. Maybe it's just bad tools.



>/|/|ike

Andy