fixes and updates to FAQ

6 files changed, 54 insertions, 95 deletions

diff --git a/docs/source/faq/how-to-implement-agent-mib.rst b/docs/source/faq/how-to-implement-agent-mib.rst
index 6d2bbb98..d667fb07 100644
--- a/docs/source/faq/how-to-implement-agent-mib.rst
+++ b/docs/source/faq/how-to-implement-agent-mib.rst
@@ -5,7 +5,7 @@ How to implement MIB at the Agent
 Q. How to instantiate static MIB table at my SNMP Agent?
 
 A. You need to create MibScalarInstance class instances and register 
-   them with your Agent's SNMP engine (mibBuilder, more specifically). 
+   them with your Agent's SNMP engine (mibBuilder, more specifically).
    Here's an example code for a IP-MIB table:
 
 .. code-block:: python
@@ -110,11 +110,11 @@ A. You need to create MibScalarInstance class instances and register
 
     # Command responder code would follow...
 
-   Keep in mind that the values of this table row will not change by 
-   themselves. They basically hold a snapshot of a data set so your 
-   application may have to update them somehow. For example, an app could 
-   periodically lookup particular MibScalarInstance by OID at mibBuilder and 
-   update its "syntax" attribute with a new value.
+Keep in mind that the values of this table row will not change by 
+themselves. They basically hold a snapshot of a data set so your 
+application may have to update them somehow. For example, an app could 
+periodically lookup particular MibScalarInstance by OID at mibBuilder and 
+update its "syntax" attribute with a new value.
 
-   There are other ways for building MIB tables that represent dynamic 
-   Managed Objects.
+There are other ways for building MIB tables that represent dynamic 
+Managed Objects.
diff --git a/docs/source/faq/non-printable-snmp-values-apps.rst b/docs/source/faq/non-printable-snmp-values-apps.rst
index cee5166e..9b8fa19a 100644
--- a/docs/source/faq/non-printable-snmp-values-apps.rst
+++ b/docs/source/faq/non-printable-snmp-values-apps.rst
@@ -35,6 +35,6 @@ A. Always use prettyPrint() method for all pyasn1-based objects -- it
     > > > rfc1902.IpAddress.prettyPrint(a)
     '1.2.3.4'
 
-   See `pyasn1 tutorial <http://pyasn1.sourceforge.net/>`_ for more information
-   on pyasn1 data model.
+See `pyasn1 tutorial <http://pyasn1.sourceforge.net/>`_ for more information
+on pyasn1 data model.
 
diff --git a/docs/source/faq/non-printable-snmp-values-tools.rst b/docs/source/faq/non-printable-snmp-values-tools.rst
index 89671e28..475a9f26 100644
--- a/docs/source/faq/non-printable-snmp-values-tools.rst
+++ b/docs/source/faq/non-printable-snmp-values-tools.rst
@@ -32,12 +32,12 @@ A. The difference is that Net-SNMP prints values into hex by-default,
     SNMPv2-SMI::enterprises.14988.1.1.1.2.1.1.0.23.183.34.8.200.3 = 
     OctetString: 00 17 b7 22 08 c8
 
-   Another matter is MIB lookup - when snmp*.py tool can use a MIB to figure 
-   out what are the display conventions for particular value type, it will 
-   reformat the value in a human-readable form.
+Another matter is MIB lookup - when snmp*.py tool can use a MIB to figure 
+out what are the display conventions for particular value type, it will 
+reformat the value in a human-readable form.
 
-   To let MIB lookup work, please pass appropriate MIB name to snmp*.py
-   tool through command line:
+To let MIB lookup work, please pass appropriate MIB name to snmp*.py
+tool through command line:
 
 .. code-block:: bash
 
diff --git a/docs/source/faq/pass-custom-mib-to-manager.rst b/docs/source/faq/pass-custom-mib-to-manager.rst
index af2d5c00..839f3045 100644
--- a/docs/source/faq/pass-custom-mib-to-manager.rst
+++ b/docs/source/faq/pass-custom-mib-to-manager.rst
@@ -1,70 +1,29 @@
 
-How to pass custom MIB to the Manager
--------------------------------------
+How to pass MIB to the Manager
+------------------------------
 
 Q. How to make use of my own MIBs at my Manager application?
 
-A. First you have to convert your plain-text MIB files into 
-   pysnmp-compliant Python modules using libsmi2pysnmp tool.
-
-   Once you have your own pysnmp MIB files at hand, you'd have to put them 
-   somewhere on the filesystem (possibly bundling them with your application). 
-   In order to let pysnmp engine locating and using these modules, pysnmp 
-   MIB search path has to be modified.
-
-.. code-block:: python
-
-    from pysnmp.entity.rfc3413.oneliner import cmdgen
-    from pysnmp.smi import builder
-
-    cmdGen = cmdgen.CommandGenerator()
-
-    mibBuilder = cmdGen.snmpEngine.msgAndPduDsp.mibInstrumController
-    .mibBuilder
-
-    mibSources = mibBuilder.getMibSources() + (
-        builder.DirMibSource('/opt/my_pysnmp_mibs'),
-        )
-
-    mibBuilder.setMibSources(*mibSources)
-
-    # Rest of CommandGenerator app would follow
-
-   The same effect could be achieved by exporting the PYSNMP_MIB_DIRS variable 
-   to process environment. Individual directories should be separated with 
-   semicolons.
-
-   In case you'd like to .egg your application or just the pysnmp MIB 
-   modules, the following code would work.
-
-.. code-block:: python
-
-    from pysnmp.entity.rfc3413.oneliner import cmdgen
-    from pysnmp.smi import builder
-
-    cmdGen = cmdgen.CommandGenerator()
-
-    mibBuilder = cmdGen.snmpEngine.msgAndPduDsp.mibInstrumController
-    .mibBuilder
-
-    mibSources = mibBuilder.getMibSources() + (
-        builder.ZipMibSource('my_pysnmp_mibs_pkg.mibs'),
-        )
-
-    mibBuilder.setMibSources(*mibSources)
-
-    # Rest of CommandGenerator app would follow
-
-   The PYSNMP_MIB_PKGS environment variable holding semicolon-separated 
-   list of modules could also be used for the same purpose.
-
-   Please, note, that Python should be able to import the [.egg] package 
-   holding your MIB modules (my_pysnmp_mibs_pkg in the example above). 
-   That requires either putting your module into site-packages or modifying 
-   Python search math (PYTHONPATH variable).
-
-   Then in your application you could refer to your MIB by its name (when
-   resolving symbolic names to OIDs) or import MIB explicitly (with 
-   mibBuilder.loadModules()) so that you could resolve OIDs to symbolic 
-   names (as well as other MIB information).
-
+A. Starting from PySNMP 4.3.x, plain-text (ASN.1) MIBs can be
+   automatically parsed into PySNMP form by the
+   `PySMI <http://pysmi.sf.net>`_ tool.  PySNMP will call PySMI
+   automatically, parsed PySNMP MIB will be cached in
+   $HOME/.pysnmp/mibs/ (default location).
+
+   MIB compiler could be configured to search for plain-text
+   MIBs at multiple local and remote locations. As for remote
+   MIB repos, you are welcome to use our collection of ASN.1
+   MIB files at
+   `http://mibs.snmplabs.com/asn1/ <http://mibs.snmplabs.com/asn1/>`_
+   as shown below.
+
+.. literalinclude:: /../../examples/hlapi/asyncore/sync/manager/cmdgen/custom-asn1-mib-search-path.py
+   :start-after: """#
+   :language: python
+
+:download:`Download</../../examples/hlapi/asyncore/sync/manager/cmdgen/custom-asn1-mib-search-path.py>` script.
+
+Alternatively, you can invoke the
+`mibdump.py <http://pysmi.sourceforge.net/user-perspective.html>`_
+(shipped with PySMI) by hand and this way compile plain-text MIB
+into PySNMP format.
diff --git a/docs/source/faq/response-values-mib-resolution.rst b/docs/source/faq/response-values-mib-resolution.rst
index 68633190..6f6ef5bc 100644
--- a/docs/source/faq/response-values-mib-resolution.rst
+++ b/docs/source/faq/response-values-mib-resolution.rst
@@ -13,14 +13,14 @@ A. The most easy to use interface to MIB lookup feature is supported by
 
     lookupNames=True, lookupValues=True
 
-   parameters to getCmd(), setCmd(), nextCmd(), bulkCmd() methods of 
-   oneliner CommandGenerator. Then the OIDs in response variable-binding 
-   list will get replaced by similarily looking MibVariable instances, 
-   their prettyPrint() methods return MIB symbols instead of OIDs.
+parameters to getCmd(), setCmd(), nextCmd(), bulkCmd() methods of 
+oneliner CommandGenerator. Then the OIDs in response variable-binding 
+list will get replaced by similarily looking MibVariable instances, 
+their prettyPrint() methods return MIB symbols instead of OIDs.
 
-   Response values will still be PyASN1 objects but some may be replaced 
-   by TEXTUAL-CONVENTION decorators what make their prettyPrint() methods 
-   returning even more human-friendly output.
+Response values will still be PyASN1 objects but some may be replaced 
+by TEXTUAL-CONVENTION decorators what make their prettyPrint() methods 
+returning even more human-friendly output.
 
 .. code-block:: python
 
@@ -46,5 +46,5 @@ A. The most easy to use interface to MIB lookup feature is supported by
     'Linux cray 2.6.37.6-smp #2 SMP Sat Apr 9 23:39:07 CDT 2011 i686'
     >>>
 
-   If you are using older PySNMP versions it's strongly recommended to 
-   upgrade to the latest one.
+If you are using older PySNMP versions it's strongly recommended to 
+upgrade to the latest one.
diff --git a/docs/source/faq/snmp-data-constraints-verification-failure.rst b/docs/source/faq/snmp-data-constraints-verification-failure.rst
index f489b404..c45c6749 100644
--- a/docs/source/faq/snmp-data-constraints-verification-failure.rst
+++ b/docs/source/faq/snmp-data-constraints-verification-failure.rst
@@ -23,10 +23,10 @@ A. Yes, it can do that. The Manager will verify the values you pass to SET
         ( cmdgen.MibVariable('SNMPv2-MIB', 'sysName', 0), 'new system name' )
     )
 
-   To verify the response values, you should pass at least lookupValues flag 
-   to CommandGenerator *cmd() method you use. In the following example 
-   PySNMP will make sure that Agent-supplied value for SNMPv2-MIB::sysName 
-   Managed Object satisfies MIB constraints (if any).
+To verify the response values, you should pass at least lookupValues flag 
+to CommandGenerator *cmd() method you use. In the following example 
+PySNMP will make sure that Agent-supplied value for SNMPv2-MIB::sysName 
+Managed Object satisfies MIB constraints (if any).
 
 .. code-block:: python
 
@@ -37,4 +37,4 @@ A. Yes, it can do that. The Manager will verify the values you pass to SET
         lookupValues=True
     )
 
-   In case of constraint violation, a PySNMP exception will be raised.
+In case of constraint violation, a PySNMP exception will be raised.