MIB Smithy

Formatting Considerations

MIB Smithy uses textual analysis to intuit which parts text such as quoted DESCRIPTION fields and comments are paragraphs that should be word wrapped and which parts appear to be pre-formatted diagrams, lists or tables. The information below will help you understand MIB Smithy's textual analysis and formatting rules so that you can format your documents appropriately.

Formatting Text Fields

The SMI language provides many "quoted text" fields in the various macros. These include fields such as DESCRIPTION, REFERENCE, CONTACT-INFO, etc. These fields may be interpreted or formatted differently than an original source MIB file that was not originally created by MIB Smithy, since steps are taken to ensure consistent formatting within margin requirements for RFC documents. The following information will help you in understanding MIB Smithy's formatting rules, both for use with MIB files not created by MIB Smithy and for your own MIB files. The way MIB Smithy formats these text fields is as follows:

1. All sequences of three or more consecutive newlines are collapsed to at most two newlines. Tabs are converted to spaces.
2. The entire body of text is left-shifted a sufficient number of spaces so that at least some text begins at the start of a line rather than all text being indented.
3. A blank line (that is, two consecutive newlines) are interpreted as a paragraph or section break. Individual sections are formatted separately according to remaining rules.
4. A line consisting entirely of three or more common line-drawing characters (e.g. hyphen, plus, underscore, equals and bar or -, +, _, = and |), with or without spaces, and the non-blank line immediately above (if any) is interpreted as the beginning of a diagram, table or other preformatted text. All text up to the next section break are treated as preformatted text.
5. A preformatted section is unindented as with the entire body of text. If the maximum line-width of a preformatted section is less than the maximum after-margin line width, minus 4 characters, then it is indented 4 characters in from the left margin with respect to the rest of the text.
6. For non-preformatted text, newlines are converted to spaces wherever the surrounding text appear to be parts of a sentence (i.e., line ends with punctuation or letter and begins with a letter or quote). Lines beginning with numbers, for example, are interpreted as likely to be lists and are not joined.
7. The resulting paragraphs text is then word-wrapped with indentation to fit within an allowed margin of 72 characters per line.

Formatting Comments

As with programming languages, the SMI language provides syntax for comments, which are bits of text that are normally treated as whitespace and discarded by most parsers. MIB Smithy does not discard comments, but it does impose some rules on their use, both for compatibility and readability.

The form for comments in the SMI language comes from ASN.1. A double-hyphen sequence (--) begins a comment. The comment continues until either the end of line or another double-hyphen sequence is encountered. This can be considered sort of a hybrid of C's /* */, which has both begin and end sequences, and C++'s //, which marks through to the end of line as a comment. This is a common source for confusion, as new MIB authors tend to assume comments always end with a newline. This is not helped by the fact that some parser implementations also handle comments this way. It is not necessary to add the comment sequence when writing your comments; MIB Smithy will add them for you when saving or previewing in normal SMI format.

Comments in source MIB files created manually (e.g. with a text editor) may show up in a different location or with different formatting when saved by MIB Smithy. This is because MIB Smithy requires each comment to be associated an appropriate record or to a named-number enumeration label/value. Such records include MIB modules, ASN.1 value/type assignments, a macro invocation such as OBJECT-TYPE, or a conformance module, group or variation within a MODULE-COMPLIANCE or AGENT-CAPABILITIES statements. Generally speaking, any item visible in the Browser tab of the Project panel in the MIB Smithy GUI is considered a record that can have comments associated with it (exceptions being the project file its self, its files, or one of the special folders containing type definitions).

When a MIB file is parsed (i.e., loaded), MIB smithy will temporarily associate each comment with the token that immediately follows the comment. All such comments are then assembled together and assigned to the most logical record (or enumeration, as the case may be). For example, all comments immediately preceding the identifier for an OBJECT-TYPE definition, up to the point immediately preceding the last token of the definition's OBJECT IDENTIFIER value (the closing brace or '}' character), not including those associated with enumeration labels/values, become assembled and assigned to the OBJECT-TYPE definition. Any comments before a MIB module header, through the IMPORTS section, and after the last definition within the module (before the END keyword), are assembled and associated with the module its self.

The process is similar for comments associated with enumeration labels/values. All comments between the opening and closing braces ('{' and '}') surrounding the enumeration list are assembled and associated with the closest enumeration. In general, this means any comments immediately preceding an enumeration's label through any comments immediately preceding the comma separator. If any comments follow the last enumeration, immediately preceding the closing brace, then those comments will be associated with the last enumeration. Also in this case, if the first enumeration had no preceding comments, then MIB Smithy will assume comments are formatted following each enumeration, rather than before, and adjust the comment associations accordingly.

In general, it is considered bad practice among MIB designers to place comments in between token elements or fields in a MIB module (such as between a STATUS field and a DESCRIPTION field). MIB Smithy will preserve such comments; however, they will be output immediately preceding the record that they are associated with in the generated MIB file. This is due to the way comments are processed at load time, and because it would be infeasible and cumbersome to the user for the MIB Smithy GUI to provide comment fields for every property and token of every record type. As well, MIB designers should use comments sparingly, opting instead for the more appropriate DESCRIPTION fields of most record types in SMIv2.

When saving or previewing MIB modules, MIB Smithy will apply the same formatting rules to comments as it does to quoted text fields, with few exceptions. To prevent comments from accidentally being closed, MIB Smithy will convert any double-hyphen sequences to four hyphens (-- --). This can be problematic for diagrams and tables where some authors are inclined to use strings of hyphens to draw lines. This should either be avoided by using an alternate character (such as an underscore or equals character) or, better still, use more appropriate DESCRIPTION fields wherever possible. Remember that most parsers discard these comments, and while most parsers also discard such text fields some do not and actually make that information available to a management application user. Think about what documentation the user may lack under normal circumstances if those comments are discarded by the parser.