thoughts on documentation reuse.

[Wes Hardaker <wes@hardakers.net>]

The other day I came up with an idea that I hated originally, but have
grown to like it more as it has settled in my poor head.  The other
day, I mentioned that we've clearly decided (I think) that we should
optimize for the MIB readers and writers and not for the compilers.
I'm pretty sure we've all agreed on this, but as I stated in the
meeting, I'm not sure which of the "readers" and "writers" groups we
should try and please the most.  

<aside>
And, by the way, I wasn't trying to say that {}s were bad.  I
was trying to say that un-needed structure like {}s, and ;s aren't
useful to readers unless they provide a purpose.  {}s are good to
people because they provide grouping, which is a very valid purpose.
;s, however do nothing for the reader but add clutter to the screen.
They already have a \n to make use of.  Only the compliers really need
the ;s, and even this is questionable.
</aside>

Anyway, the biggest problem that was talked about in the meeting was
that reading OO like documentation is very difficult because of
needing to follow the references.  But, cut-n-pasting 5 billion lines
of text into every row-creation column is equally as bad.

So, I'm now thinking we need not 1 but 2 MIB formats.  One which is
short, allows reuse of documentation itself, and compiles into one
which is more readable and with greater text auto-expansion.  This is
already similar to hove IDs are published themselves, as no one writes
straight text.  They write it in nroff, xml, word, latex, etc and have
it produce the resulting text.  I'm beginning to think that a similar
approach would be a good thing for MIBs.  And possibly both the
compiled and the uncompiled versions should be published, but
certainly the compiled version.  As an example, I'll try to take an
example from Andy's lastest document:

  VAR STRUCT myAddress {
      SYNTAX      HostInetAddress
      STATUS      current
      DESCRIPTION
          "Internet address of this host."
  } ::= { someBase 1 }

The problem is that if someone was truly confused by the syntax
statement above, they'd have to look up  the resulting document
describing a HostInetAddress.  The writer wants to simply state the
above, however, because they don't want to provide a greater
description because that takes time and energy to ensure that the
multiple cut-n-paste results are accurate (over time).

So, if HostInetAddress was define like (not that I'm not trying to
make this concept look perfect in syntax, at this time, I'm just bring
the idea forward itself.  The exact syntax is left for future
consideration if the concept idea is appreciated):

  TYPEDEF STRUCT HostInetAddress {
      DESCRIPTION
         "Internet address for an end-station host, adhering
          to the SMIv2 'associated objects' design approach."

-------------------------------------------------- new stuff here ----------
      DESCRIPTIONTAG addressdescr       
         "An internet address SYNTAX type is composed of a address
          type and a representational UNION containing the value."
-------------------------------------------------- end new stuff  ----------

      SCALAR addrType {
         SYNTAX      InetAddressType
         MAX-ACCESS  read-only
         STATUS      current
         DESCRIPTION
             "The type of Internet address."
      } ::= 1

      UNION addr {
         SYNTAX      InetAddressUnion
         STATUS      current
         DESCRIPTION
             "The Internet address."
      } ::= 2
  }

Then myAddress, might be redefined as (looking kind of java-tagish in
this example, with an @ in front of the key word):

  VAR STRUCT myAddress {
      SYNTAX      HostInetAddress
      STATUS      current
      DESCRIPTION
          "Internet address of this host.

           @magicalinclude addressdescr"
  } ::= { someBase 1 }

Thus, the above though ugly to readers would help writers reuse text
without requiring massive cut-n-pasting and thus would increase the
understand of what a given object was.  The writer->reader mib
conversion would then compile the template mib to produce something like

  VAR STRUCT myAddress {
      SYNTAX      HostInetAddress
      STATUS      current
      DESCRIPTION
          "Internet address of this host.

           An internet address is composed of a address type and a
           representational UNION containing the value."
  } ::= { someBase 1 }

Doing something like this would allow writers to include standard
descriptions of parent mib objects with a simple "include" directive,
but would allow it to be slightly more readable from the readers point
of view if they haven't seen the parent object types before.

I didn't really like this idea when I first thought about it, but the
more I thought about it the more I realized that it would solve a
number of problems.  It would have to be used carefully, of course,
and included documentation strings should probably always be
paragraphs in their own right rather words, pieces of sentences or
sentences to be included into other paragraph or sentence constructs.

I'd recommend that the fully compiled MIB be published and possibly
that the "reduced" form be published in IDs as well since MIB authors
would need to use any references defined within.  Yes I realize this
increases the length of IDs (or at least appendix portions maybe).

Thoughts?

(Randy and I had a discussion about this and he mentioned "XML" and
"style sheets" as the probably best way of accomplishing something
like this in his mind)
-- 
Wes Hardaker
NAI Labs
Network Associates