Hi Frank,
My understanding is that in the current implementation comments are not being preserved at any data structure in libsmi.
If I'm right, I would like to suggest that a code will be added to do this. The advantages of preserving comments are that utilities like dumpsmi will be able to regenerate the exact contents of the original MIB module, and that there are some places, like enum values definition, were it is more convinient to use a comment near the definition.
Mark.
Hi!
Mark> My understanding is that in the current implementation Mark> comments are not being preserved at any data structure in Mark> libsmi.
Right. Comments are filtered out by the flex scanner.
Mark> If I'm right, I would like to suggest that a code will be Mark> added to do this. The advantages of preserving comments are Mark> that utilities like dumpsmi will be able to regenerate the Mark> exact contents of the original MIB module, and that there are Mark> some places, like enum values definition, were it is more Mark> convinient to use a comment near the definition.
I disagree. Comments are just comments. All essential information of a MIB has to be placed in formal constructs, i.e. DESCRIPTION and REFERENCES clauses. Otherwise this information is not available, e.g. in MIB browsers, smiquery, or other tools.
In case you are really looking for a tool that regenerates the exact contens of a MIB file, try `cp'. ;-)
-frank
I'm working on windows so I would probably use copy :-)
Anyway, I agree that all the information should be in some kind of formal construct, but: 1. The SMI constructs do not answer all needs. There is no good/easy way to explain a dependency between two or more objects. 2. Descriptions which contain all the information might get very big, especially where enums are concerned, which makes harder their reading and understanding. When I'm (as a sysadmin) need to know what does the number 4 means for StorageType (RFC2579) it is much faster to learn it from the comment then from the description. What is worse is that there is no automatic way to associate an enum with its explenation contained at the description. 3. In practice comments apear in many MIBs, even some of the standard ones has some non trivial comments. The fact that current MIB browsers do not know how to handle comments, does not mean that the end user will not benefit from reading them.
The way I see libsmi, it is a generic tool to compile MIB files to other formats/langauges, therefor I don't see the point of limiting the generated format to "formats which do not contain comment information".
Have fun, Mark.
----- Original Message ----- From: "Frank Strauss" strauss@ibr.cs.tu-bs.de To: "Mark Kaplun" markk5@bezeqint.net Cc: libsmi@ibr.cs.tu-bs.de Sent: Saturday, May 18, 2002 7:03 PM Subject: Re: [libsmi] preserving comments
Hi!
Mark> My understanding is that in the current implementation Mark> comments are not being preserved at any data structure in Mark> libsmi.
Right. Comments are filtered out by the flex scanner.
Mark> If I'm right, I would like to suggest that a code will be Mark> added to do this. The advantages of preserving comments are Mark> that utilities like dumpsmi will be able to regenerate the Mark> exact contents of the original MIB module, and that there are Mark> some places, like enum values definition, were it is more Mark> convinient to use a comment near the definition.
I disagree. Comments are just comments. All essential information of a MIB has to be placed in formal constructs, i.e. DESCRIPTION and REFERENCES clauses. Otherwise this information is not available, e.g. in MIB browsers, smiquery, or other tools.
In case you are really looking for a tool that regenerates the exact contens of a MIB file, try `cp'. ;-)
-frank
!! This message is brought to you via the `libsmi' mailing list. !! Please do not reply to this message to unsubscribe. To unsubscribe or
adjust
!! your settings, send a mail message to libsmi-request@ibr.cs.tu-bs.de !! or look at https://www.ibr.cs.tu-bs.de/mailman/listinfo/libsmi.
Mark Kaplun writes:
Mark> The way I see libsmi, it is a generic tool to compile MIB files Mark> to other formats/langauges, therefor I don't see the point of Mark> limiting the generated format to "formats which do not contain Mark> comment information".
Did you ever wonder what a C compiler does with your comments?
It is quite normal for compilers to drop comments very early in the process. Trying to retain them is not as trivial as it might look like. For example, how do you decide the anchor for a given comment?
The point is that Frank and I do not consider it important enough to preserve comments and thus we dislike spending time on this. If others feel strong about it, please go ahead and write patches that do not add much of complexity (also maintenance wise) and send them to the list.
/js
Hi!
Mark> [...] Anyway, I agree that all the information should be in some Mark> kind of formal construct, but:
Mark> 1. The SMI constructs do not answer all needs. There is no Mark> good/easy way to explain a dependency between two or more Mark> objects.
I agree. But I don't see how comments could serve this need any better than DESCRIPTION clauses.
Mark> 2. Descriptions which contain all the information might get Mark> very big, especially where enums are concerned, which makes Mark> harder their reading and understanding. When I'm (as a sysadmin) Mark> need to know what does the number 4 means for StorageType Mark> (RFC2579) it is much faster to learn it from the comment then Mark> from the description. What is worse is that there is no Mark> automatic way to associate an enum with its explenation Mark> contained at the description.
The length of a text does not make it more or less appropriate for being placed in a DESCRIPTION or comment. I don't think that
SYNTAX INTEGER { [...] nsip(27), -- XNS over IP slip(28), -- generic SLIP ultra(29), -- ULTRA technologies ds3(30), -- DS3-MIB [...]
or more or less difficult to read than e.g.
DESCRIPTION " [...] nsip 27 XNS over IP slip 28 generic SLIP ultra 29 ULTRA technologies ds3 30 DS3-MIB [...]
The problem is, that there is no formal structure in both cases and there is some redundancy (which should only worry the author and not the reader or the MIB). The advantage of the second approach is that you can access this information also from an arbitrary MIB browser.
Mark> 3. In practice comments apear in many MIBs, even some of the Mark> standard ones has some non trivial comments. The fact that Mark> current MIB browsers do not know how to handle comments, does Mark> not mean that the end user will not benefit from reading them.
Comments are meant for readers and authors working at the same level as the original MIB author. They are not meant for any higher level processing or application. That's true for all computer languages that come to my mind (except some uggly compiler directives).
I don't see a need to support wrong usage of comments (especially because a useful interpretation of comments would be quite difficult to implement and *cannot* be reliable). And AFAIK standard MIB revision processes are much better these days, so that in recent MIBs you won't find `useful' information in comments.
Mark> The way I see libsmi, it is a generic tool to compile MIB files Mark> to other formats/langauges, therefor I don't see the point of Mark> limiting the generated format to "formats which do not contain Mark> comment information".
I agree. But I think, that's not the point.
-frank
----- Original Message ----- From: "Frank Strauss" strauss@ibr.cs.tu-bs.de To: "Mark Kaplun" markk5@bezeqint.net Cc: libsmi@ibr.cs.tu-bs.de Sent: Saturday, May 25, 2002 2:48 PM Subject: Re: [libsmi] preserving comments
[snip part which should be disccused at IETF WG]
Mark> The way I see libsmi, it is a generic tool to compile MIB files Mark> to other formats/langauges, therefor I don't see the point of Mark> limiting the generated format to "formats which do not contain Mark> comment information".
I agree. But I think, that's not the point.
This is realy my only point. I will leave the IETF to worry about whether comments are needed at all, and how to standertise the data in the descriptions, but while they are here and people are adding comments to MIB files, I think that libsmi should to something with them and not just ignore the text contained in them.
I would gladly contribute some time for adding comment support to libsmi, but the last time I have done any YACC/LEX coding was sometime at the prehistoric times. so I will require help at that aspect. If there is anyone who feels it is a worthy cuase and have some YACC experience he can contact me.
Mark.
HI Mark,
In SMICng, I have a flag to "capture" comments. Its been in there for many years. However, the hard part is associating the comments with the proper item(s). How to do this varies with the style of writing comments. For example, one of the reasons for capturing comments is to get the description of enumerated values, such as SYNTAX INTEGER { a(1), -- when condition a b(2), -- when condition b c(3), -- when condition c d(4) -- when condition d } As shown above, this is the simple and easy case. Here is another example: SYNTAX INTEGER { -- values that can only be written a(1), -- when condition a b(2), -- when condition b -- values that can only be read c(3), -- when condition c -- values that can be written and read d(4) -- when condition d }
And how do you write comments that are over multiple lines? For example: SYNTAX INTEGER { -- when condition a, and blah, blah, blah a(1), -- more about a, blah, blah
-- or this way b(2) -- when condition b, and blah, blah, blah -- more about b, blah, blah }
Many years ago, I made several proposals to extend the syntax of MIB modules to capture more of text that is associated with different parts. They were not well received because of the additional work that would be needed to MIB modules. For example: SYNTAX ENUM { WRITE-ONLY { VALUE a(1) DESCRIPTION "when condition a", VALUE b(2) DESCRIPTION "when condition b" } READ-ONLY { VALUE c(3) DESCRIPTION "when condition c" } READ-WRITE { VALUE d(4) DESCRIPTION "when condition d" } }
And by the way on SMICng, yes, it can save the comments, but doesn't do anything with them yet (other than print them out, if requested).
At 11:57 PM 5/29/2002 +0200, Mark Kaplun wrote:
----- Original Message ----- From: "Frank Strauss" strauss@ibr.cs.tu-bs.de To: "Mark Kaplun" markk5@bezeqint.net Cc: libsmi@ibr.cs.tu-bs.de Sent: Saturday, May 25, 2002 2:48 PM Subject: Re: [libsmi] preserving comments
[snip part which should be disccused at IETF WG]
Mark> The way I see libsmi, it is a generic tool to compile MIB files Mark> to other formats/langauges, therefor I don't see the point of Mark> limiting the generated format to "formats which do not contain Mark> comment information".
I agree. But I think, that's not the point.
This is realy my only point. I will leave the IETF to worry about whether comments are needed at all, and how to standertise the data in the descriptions, but while they are here and people are adding comments to MIB files, I think that libsmi should to something with them and not just ignore the text contained in them.
I would gladly contribute some time for adding comment support to libsmi, but the last time I have done any YACC/LEX coding was sometime at the prehistoric times. so I will require help at that aspect. If there is anyone who feels it is a worthy cuase and have some YACC experience he can contact me.
Mark.
-- !! This message is brought to you via the `libsmi' mailing list. !! Please do not reply to this message to unsubscribe. To unsubscribe or adjust !! your settings, send a mail message to libsmi-request@ibr.cs.tu-bs.de !! or look at https://www.ibr.cs.tu-bs.de/mailman/listinfo/libsmi.
Regards, /david t. perkins
From practical point of view, the need for preserving comments may arise
when designing a MIB editor. It is usualy unexceptable for an editor to omit information which was at the original file.
There is at least one editor (MG-SOFT MIB builder) which lets the MIB designer to add comments to the MIB before or after a node.
Another practical application is the generation of HTML with syntax coloring out of MIBs.
I agree that the implementation is probably not a trivial one. What I would have done, is to start with an easy case (multiple lines of comments between nodes) while trying to lay out an infrastructure, and handle all other cases when the need arises (the case where comments are placed between "SYNTAX" and "INTEGER" will be delayed till infinity ;-).
----- Original Message ----- From: "David T. Perkins" dperkins@dsperkins.com To: "Mark Kaplun" markk5@bezeqint.net; "Frank Strauss" strauss@ibr.cs.tu-bs.de Cc: libsmi@ibr.cs.tu-bs.de Sent: Thursday, May 30, 2002 12:48 AM Subject: Re: [libsmi] preserving comments
HI Mark,
In SMICng, I have a flag to "capture" comments. Its been in there for many years. However, the hard part is associating the comments with the proper item(s). How to do this varies with the style of writing comments. For example, one of the reasons for capturing comments is to get the description of enumerated values, such as SYNTAX INTEGER { a(1), -- when condition a b(2), -- when condition b c(3), -- when condition c d(4) -- when condition d } As shown above, this is the simple and easy case. Here is another example: SYNTAX INTEGER { -- values that can only be written a(1), -- when condition a b(2), -- when condition b -- values that can only be read c(3), -- when condition c -- values that can be written and read d(4) -- when condition d }
And how do you write comments that are over multiple lines? For example: SYNTAX INTEGER { -- when condition a, and blah, blah, blah a(1), -- more about a, blah, blah
-- or this way b(2) -- when condition b, and blah, blah, blah -- more about b, blah, blah }Many years ago, I made several proposals to extend the syntax of MIB modules to capture more of text that is associated with different parts. They were not well received because of the additional work that would be needed to MIB modules. For example: SYNTAX ENUM { WRITE-ONLY { VALUE a(1) DESCRIPTION "when condition a", VALUE b(2) DESCRIPTION "when condition b" } READ-ONLY { VALUE c(3) DESCRIPTION "when condition c" } READ-WRITE { VALUE d(4) DESCRIPTION "when condition d" } }
And by the way on SMICng, yes, it can save the comments, but doesn't do anything with them yet (other than print them out, if requested).
At 11:57 PM 5/29/2002 +0200, Mark Kaplun wrote:
----- Original Message ----- From: "Frank Strauss" strauss@ibr.cs.tu-bs.de To: "Mark Kaplun" markk5@bezeqint.net Cc: libsmi@ibr.cs.tu-bs.de Sent: Saturday, May 25, 2002 2:48 PM Subject: Re: [libsmi] preserving comments
[snip part which should be disccused at IETF WG]
Mark> The way I see libsmi, it is a generic tool to compile MIB files Mark> to other formats/langauges, therefor I don't see the point of Mark> limiting the generated format to "formats which do not contain Mark> comment information".
I agree. But I think, that's not the point.
This is realy my only point. I will leave the IETF to worry about whether comments are needed at all, and how to standertise the data in the descriptions, but while they are here and people are adding comments to
MIB
files, I think that libsmi should to something with them and not just
ignore
the text contained in them.
I would gladly contribute some time for adding comment support to libsmi, but the last time I have done any YACC/LEX coding was sometime at the prehistoric times. so I will require help at that aspect. If there is
anyone
who feels it is a worthy cuase and have some YACC experience he can
contact
me.
Mark.
-- !! This message is brought to you via the `libsmi' mailing list. !! Please do not reply to this message to unsubscribe. To unsubscribe or
adjust
!! your settings, send a mail message to libsmi-request@ibr.cs.tu-bs.de !! or look at https://www.ibr.cs.tu-bs.de/mailman/listinfo/libsmi.
Regards, /david t. perkins
-- !! This message is brought to you via the `libsmi' mailing list. !! Please do not reply to this message to unsubscribe. To unsubscribe or
adjust
!! your settings, send a mail message to libsmi-request@ibr.cs.tu-bs.de !! or look at https://www.ibr.cs.tu-bs.de/mailman/listinfo/libsmi.
Hi Mark,
FYI, MIB Designer (http://www.mibdesigner.com) also supports editing of comments around object definitions and at the beginning and the end of a MIB file.
In addition, it supports exporting of MIBs into XML using the SMI DTD DRAFT Juergen Schoenwaelder proposed. I also missed ASN.1 comments in the DTD, while understanding and agreeing to the arguments against supporting ASN.1 comments in higher level representations of SMI definitions.
My idea is to create a XSLT based converter from XML to PDF. I hope I get some time within the next months to implement it.
Best regards, Frank
Mark Kaplun wrote:
From practical point of view, the need for preserving comments may arise
when designing a MIB editor. It is usualy unexceptable for an editor to omit information which was at the original file.
There is at least one editor (MG-SOFT MIB builder) which lets the MIB designer to add comments to the MIB before or after a node.
Another practical application is the generation of HTML with syntax coloring out of MIBs.
I agree that the implementation is probably not a trivial one. What I would have done, is to start with an easy case (multiple lines of comments between nodes) while trying to lay out an infrastructure, and handle all other cases when the need arises (the case where comments are placed between "SYNTAX" and "INTEGER" will be delayed till infinity ;-).
----- Original Message ----- From: "David T. Perkins" dperkins@dsperkins.com To: "Mark Kaplun" markk5@bezeqint.net; "Frank Strauss" strauss@ibr.cs.tu-bs.de Cc: libsmi@ibr.cs.tu-bs.de Sent: Thursday, May 30, 2002 12:48 AM Subject: Re: [libsmi] preserving comments
HI Mark,
In SMICng, I have a flag to "capture" comments. Its been in there for many years. However, the hard part is associating the comments with the proper item(s). How to do this varies with the style of writing comments. For example, one of the reasons for capturing comments is to get the description of enumerated values, such as SYNTAX INTEGER { a(1), -- when condition a b(2), -- when condition b c(3), -- when condition c d(4) -- when condition d } As shown above, this is the simple and easy case. Here is another example: SYNTAX INTEGER { -- values that can only be written a(1), -- when condition a b(2), -- when condition b -- values that can only be read c(3), -- when condition c -- values that can be written and read d(4) -- when condition d }
And how do you write comments that are over multiple lines? For example: SYNTAX INTEGER { -- when condition a, and blah, blah, blah a(1), -- more about a, blah, blah
-- or this way b(2) -- when condition b, and blah, blah, blah -- more about b, blah, blah }Many years ago, I made several proposals to extend the syntax of MIB modules to capture more of text that is associated with different parts. They were not well received because of the additional work that would be needed to MIB modules. For example: SYNTAX ENUM { WRITE-ONLY { VALUE a(1) DESCRIPTION "when condition a", VALUE b(2) DESCRIPTION "when condition b" } READ-ONLY { VALUE c(3) DESCRIPTION "when condition c" } READ-WRITE { VALUE d(4) DESCRIPTION "when condition d" } }
And by the way on SMICng, yes, it can save the comments, but doesn't do anything with them yet (other than print them out, if requested).
At 11:57 PM 5/29/2002 +0200, Mark Kaplun wrote:
----- Original Message ----- From: "Frank Strauss" strauss@ibr.cs.tu-bs.de To: "Mark Kaplun" markk5@bezeqint.net Cc: libsmi@ibr.cs.tu-bs.de Sent: Saturday, May 25, 2002 2:48 PM Subject: Re: [libsmi] preserving comments
[snip part which should be disccused at IETF WG]
Mark> The way I see libsmi, it is a generic tool to compile MIB files Mark> to other formats/langauges, therefor I don't see the point of Mark> limiting the generated format to "formats which do not contain Mark> comment information".
I agree. But I think, that's not the point.
This is realy my only point. I will leave the IETF to worry about whether comments are needed at all, and how to standertise the data in the descriptions, but while they are here and people are adding comments to
MIB
files, I think that libsmi should to something with them and not just
ignore
the text contained in them.
I would gladly contribute some time for adding comment support to libsmi, but the last time I have done any YACC/LEX coding was sometime at the prehistoric times. so I will require help at that aspect. If there is
anyone
who feels it is a worthy cuase and have some YACC experience he can
contact
me.
Mark.
-- !! This message is brought to you via the `libsmi' mailing list. !! Please do not reply to this message to unsubscribe. To unsubscribe or
adjust
!! your settings, send a mail message to libsmi-request@ibr.cs.tu-bs.de !! or look at https://www.ibr.cs.tu-bs.de/mailman/listinfo/libsmi.
Regards, /david t. perkins
-- !! This message is brought to you via the `libsmi' mailing list. !! Please do not reply to this message to unsubscribe. To unsubscribe or
adjust
!! your settings, send a mail message to libsmi-request@ibr.cs.tu-bs.de !! or look at https://www.ibr.cs.tu-bs.de/mailman/listinfo/libsmi.
-- !! This message is brought to you via the `libsmi' mailing list. !! Please do not reply to this message to unsubscribe. To unsubscribe or adjust !! your settings, send a mail message to libsmi-request@ibr.cs.tu-bs.de !! or look at https://www.ibr.cs.tu-bs.de/mailman/listinfo/libsmi.
Hi!
FrankF> FYI, MIB Designer (http://www.mibdesigner.com) also supports FrankF> editing of comments around object definitions and at the FrankF> beginning and the end of a MIB file.
FrankF> In addition, it supports exporting of MIBs into XML using the FrankF> SMI DTD DRAFT Juergen Schoenwaelder proposed. I also missed FrankF> ASN.1 comments in the DTD, while understanding and agreeing to FrankF> the arguments against supporting ASN.1 comments in higher level FrankF> representations of SMI definitions.
FrankF> My idea is to create a XSLT based converter from XML to PDF. I FrankF> hope I get some time within the next months to implement it.
Interesting. What is the intended layout of the PDF files? To enhance readability and support a better overview of the structure of a MIB?
BTW, is it possible to access XML comments by (standard) XSL means? I don't think so (but I'm not sure).
-frank
Hi Frank,
Frank Strauss wrote:
FrankF> My idea is to create a XSLT based converter from XML to PDF. I FrankF> hope I get some time within the next months to implement it.
Interesting. What is the intended layout of the PDF files? To enhance readability and support a better overview of the structure of a MIB?
Both. The structure of a MIB module should be reflected by the "bookmarks". Links/References should be used to enhance readability (which is already known from HTML representations). Another goal is improved printing layout.
BTW, is it possible to access XML comments by (standard) XSL means?
Interesting question which I will investigate...
Best regards, Frank Fock
participants (5)
-
David T. Perkins -
Frank Strauss -
Frank.Fock＠t-online.de -
Juergen Schoenwaelder -
Mark Kaplun