docs: Adding a new example of how to use AnnotatedTopologyReader, as well as a new FAQ section with a couple of commonly asked questions.
diff --git a/docs/source/applications.rst b/docs/source/applications.rst
index fb2b4fb..ac4150f 100644
--- a/docs/source/applications.rst
+++ b/docs/source/applications.rst
@@ -132,10 +132,11 @@
 
 
 
-Example
-^^^^^^^
+Customer example
+^^^^^^^^^^^^^^^^
 
-The following code shows how a simple ndnSIM application can be created.  For details refer to API documentation of ndnSIM and NS-3.
+The following code shows how a simple ndnSIM application can be created.  
+For details refer to API documentation of ndnSIM and NS-3.
 
 .. code-block:: c++
 
@@ -230,3 +231,78 @@
         std::cout << "DATA received for name " << contentObject->GetName () << std::endl; 
       }
     };
+
+Producer example (Interest hijacker)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following code demonstrates how to implement a basic producer application that "hijacks" all incoming Interests.
+
+.. code-block:: c++
+
+    #include "ns3/core-module.h"
+    #include "ns3/network-module.h"
+    #include "ns3/ndnSIM-module.h"
+        
+    using namespace ns3;
+    
+    class Hijacker : public ndn::App
+    {
+    public: 
+      static TypeId
+      GetTypeId ();
+            
+      Hijacker ()
+      {
+      }
+    
+      // inherited from NdnApp
+      void OnInterest (const Ptr<const ndn::InterestHeader> &interest, Ptr<Packet> packet)
+      {
+        ndn::App::OnInterest (interest, packet); // forward call to perform app-level tracing
+        // do nothing else (hijack interest)
+      }
+    
+    protected:
+      // inherited from Application base class.
+      virtual void
+      StartApplication ()
+      {
+        App::StartApplication ();
+    
+        // equivalent to setting interest filter for "/" prefix
+        Ptr<ndn::Fib> fib = GetNode ()->GetObject<ndn::Fib> ();
+        Ptr<ndn::fib::Entry> fibEntry = fib->Add ("/", m_face, 0);
+        fibEntry->UpdateStatus (m_face, ndn::fib::FaceMetric::NDN_FIB_GREEN);
+      }
+    
+      virtual void
+      StopApplication ()
+      {
+        App::StopApplication ();
+      }
+    };
+    
+    // Necessary if you are planning to use ndn::AppHelper
+    NS_OBJECT_ENSURE_REGISTERED (Hijacker);
+    
+    TypeId
+    Hijacker::GetTypeId ()
+    {
+      static TypeId tid = TypeId ("ndn::Hijacker")
+        .SetParent<ndn::App> ()
+        .AddConstructor<Hijacker> ()
+        ;
+            
+      return tid;
+    }
+
+
+After defining this class, you can use it with :ndnsim:`ndn::AppHelper`. For example:
+
+.. code-block:: c++
+
+    ...
+    ndn::AppHelper producerHelper ("ndn::Hijacker");
+    producerHelper.Install (producerNode);
+    ...
+
diff --git a/docs/source/boost-custom-install.rst b/docs/source/boost-custom-install.rst
index 34ae785..860269a 100644
--- a/docs/source/boost-custom-install.rst
+++ b/docs/source/boost-custom-install.rst
@@ -1,3 +1,5 @@
+.. _boost-custom-install:
+
 Installing boost libraries
 ==========================
 
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 5ea290e..d65f4eb 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -1,6 +1,8 @@
 Examples
 ========
 
+.. _simple-scenario:
+
 Simple scenario
 ---------------
 
@@ -45,6 +47,10 @@
       Config::SetDefault ("ns3::PointToPointChannel::Delay", StringValue ("10ms"));
       Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("20"));
 
+      // Read optional command-line parameters (e.g., enable visualizer with ./waf --run=<> --visualize
+      CommandLine cmd;
+      cmd.Parse (argc, argv);
+
       // Creating nodes
       NodeContainer nodes;
       nodes.Create (3);
@@ -89,6 +95,8 @@
      NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
 
 
+.. _9-node-grid-example:
+ 
 9-node grid example
 -------------------
 
@@ -144,6 +152,10 @@
       Config::SetDefault ("ns3::PointToPointChannel::Delay", StringValue ("10ms"));
       Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("20"));
         
+      // Read optional command-line parameters (e.g., enable visualizer with ./waf --run=<> --visualize
+      CommandLine cmd;
+      cmd.Parse (argc, argv);
+
       // Creating 3x3 topology
       PointToPointHelper p2p;
       PointToPointGridHelper grid (3, 3, p2p);
@@ -195,3 +207,125 @@
 
     NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid
 
+.. _9-node-grid-example-using-topology-plugin:
+
+9-node grid example using topology plugin
+-----------------------------------------
+
+Instead of defining topology directly as in :ref:`simple-scenario` or using specialized helpers as in :ref:`9-node-grid-example`, ndnSIM provides experimental extended versions of TopologyReader classes: :ndnsim:`AnnotatedTopologyReader` and :ndnsim:`RocketfuelWeightsReader`.
+
+While :ndnsim:`RocketfuelWeightsReader` is a specialized version intended to be used with `Rocketfuel <http://www.cs.washington.edu/research/networking/rocketfuel/>`_ topology and link weights files (examples will be provided later), :ndnsim:`AnnotatedTopologyReader` is a general-use tool that allows creation of any custom topologies.  
+The based format for the input file the :ndnsim:`AnnotatedTopologyReader` expects::
+
+    # any empty lines and lines starting with '#' symbol is ignored
+
+    # The file should contain exactly two sections: router and link, each starting with the corresponding keyword
+
+    # router section defines topology nodes and their relative positions (e.g., to use in visualizer)
+    router
+
+    # each line in this section represents one router and should have the following data
+    # node  comment     yPos    xPos
+    Node0   NA          3       1
+    Node1   NA          3       2
+    Node2   NA          3       3
+    Node3   NA          2       1
+    Node4   NA          2       2
+    Node5   NA          2       3
+    Node6   NA          1       1
+    Node7   NA          1       2
+    Node8   NA          1       3
+    # Note that `node` can be any string. It is possible to access to the node by name using Names::Find, see examples.
+
+    # link section defines point-to-point links between nodes and characteristics of these links
+    link
+
+    # Each line should be in the following format (only first two are required, the rest can be omitted)
+    # srcNode   dstNode     bandwidth   metric  delay   queue
+    # bandwidth: link bandwidth
+    # metric: routing metric
+    # delay:  link delay
+    # queue:  MaxPackets for transmission queue on the link (both directions)
+    Node0       Node1       1Mbps       1       10ms    10
+    Node0       Node3       1Mbps       1       10ms    10
+    Node1       Node2       1Mbps       1       10ms    10
+    Node1       Node4       1Mbps       1       10ms    10
+    Node2       Node5       1Mbps       1       10ms    10
+    Node3       Node4       1Mbps       1       10ms    10
+    Node3       Node6       1Mbps       1       10ms    10
+    Node4       Node5       1Mbps       1       10ms    10
+    Node4       Node7       1Mbps       1       10ms    10
+    Node5       Node8       1Mbps       1       10ms    10
+    Node6       Node7       1Mbps       1       10ms    10
+    Node7       Node8       1Mbps       1       10ms    10
+
+
+If you save the topology file to `topo.txt` in the current directory, then the following code will duplicate the functionality of :ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`:
+
+.. code-block:: c++
+
+    #include "ns3/core-module.h"
+    #include "ns3/network-module.h"
+    #include "ns3/ndnSIM-module.h"
+    
+    using namespace ns3;
+    
+    int 
+    main (int argc, char *argv[])
+    {
+      CommandLine cmd;
+      cmd.Parse (argc, argv);
+    
+      AnnotatedTopologyReader topologyReader ("", 25);
+      topologyReader.SetFileName ("topo.txt");
+      topologyReader.Read (); 
+        
+      // Install CCNx stack on all nodes
+      ndn::StackHelper ccnxHelper;
+      ccnxHelper.InstallAll ();
+        
+      // Installing global routing interface on all nodes
+      ndn::GlobalRoutingHelper ccnxGlobalRoutingHelper;
+      ccnxGlobalRoutingHelper.InstallAll ();
+          
+      // Getting containers for the consumer/producer
+      Ptr<Node> producer = Names::Find<Node> ("Node8");
+      NodeContainer consumerNodes;
+      consumerNodes.Add (Names::Find<Node> ("Node0"));
+          
+      // Install CCNx applications
+      std::string prefix = "/prefix";
+          
+      ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
+      consumerHelper.SetPrefix (prefix);
+      consumerHelper.SetAttribute ("Frequency", StringValue ("100")); // 100 interests a second
+      consumerHelper.Install (consumerNodes);
+          
+      ndn::AppHelper producerHelper ("ns3::ndn::Producer");
+      producerHelper.SetPrefix (prefix);
+      producerHelper.SetAttribute ("PayloadSize", StringValue("1024"));
+      producerHelper.Install (producer);
+        
+      // Add /prefix origins to ndn::GlobalRouter
+      ccnxGlobalRoutingHelper.AddOrigins (prefix, producer);
+        
+      // Calculate and install FIBs
+      ccnxGlobalRoutingHelper.CalculateRoutes ();
+          
+      Simulator::Stop (Seconds (20.0));
+            
+      Simulator::Run ();
+      Simulator::Destroy ();
+            
+      return 0;
+    }
+    
+As you can see, scenario code became more compact and more readable.
+
+:ndnsim:`AnnotatedTopologyReader` provides two ways to access topology nodes.  
+First, you can use the method :ndnsim:`AnnotatedTopologyReader::GetNodes` which returns NodeContainer.
+
+Alternatively, nodes can be accessed by name using `Names::Find<Node> ("nodename")` call, as in the above example.
+For this purpose,:ndnsim:`AnnotatedTopologyReader` automatically registers all created nodes with names specified in topology file.
+For more information about `Names` class, please refer to `NS-3 documentation <.. http://www.nsnam.org/doxygen/classns3_1_1_names.html>`_
+.
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
new file mode 100644
index 0000000..3c3f9ec
--- /dev/null
+++ b/docs/source/faq.rst
@@ -0,0 +1,88 @@
+FAQ
+===
+
+Boost libraries
+---------------
+
+.. topic:: Custom boost libraries compilation problem
+
+    I'm trying to use custom boost libraries, but something is going wrong. What should I do?
+
+Please refer to :ref:`boost-custom-install` section for an example how custom boost libraries could be built.
+
+
+Visualizer problems
+-------------------
+
+.. topic:: Visualizer module is not working
+
+    Every time I'm trying to run visualizer, I get the following error::
+
+        Waf: Entering directory `/ndnSIM/ns-3/build'
+        Could not find a task generator for the name 'ns3-visualizer'..
+
+Something is wrong with your python bindings and python bindings dependencies. 
+Please follow the :ref:`requirements` section that lists what should be installed in order to run visualizer.
+
+Code questions
+--------------
+
+.. topic:: Failing a link between nodes
+
+    How can I fail a link between to NDN nodes?
+
+
+Right now, NS-3 does not provide ability to actually "break" the link between nodes in NS-3.
+However, exactly the same effect can be achieved by making an interface (:ndnsim:`ndn::Face`) up or down (:ndnsim:`ndn::Face::SetUp(true)` or :ndnsim:`ndn::Face::SetUp(false)`).
+
+Here is an example of function to "fail" a point-to-point link between two NDN nodes:
+
+.. code-block:: c++
+
+    // hijacker is more than an application. just disable all faces
+    void
+    FailLinks (Ptr<Node> node1, Ptr<Node> node2)
+    {
+      Ptr<ndn::L3Protocol> ndn1 = node1->GetObject<ndn::L3Protocol> ();
+      Ptr<ndn::L3Protocol> ndn2 = node2->GetObject<ndn::L3Protocol> ();
+    
+      // iterate over all faces to find the right one
+      for (uint32_t faceId = 0; faceId < ndn1->GetNFaces (); faceId++)
+        {
+          Ptr<ndn::NetDeviceFace> ndFace = ndn1->GetFace (faceId)->GetObject<ndn::NetDeviceFace> ();
+          if (ndFace == 0) continue;
+     
+          Ptr<PointToPointNetDevice> nd1 = ndFace->GetNetDevice ()->GetObject<PointToPointNetDevice> ();
+          if (nd1 == 0) continue;
+     
+          Ptr<Channel> channel = nd1->GetChannel ();
+          if (channel == 0) continue;
+     
+          Ptr<PointToPointChannel> ppChannel = DynamicCast<PointToPointChannel> (channel);
+     
+          Ptr<NetDevice> nd2 = ppChannel->GetDevice (0);
+          if (nd2->GetNode () == node1)
+            nd2 = ppChannel->GetDevice (1);
+     
+          if (nd2->GetNode () == node2)
+            {
+              Ptr<ndn::Face> face1 = ndn1->GetFaceByNetDevice (nd1);
+              Ptr<ndn::Face> face2 = ndn2->GetFaceByNetDevice (nd2);
+     
+              face1->SetUp (false);
+              face2->SetUp (false);
+              break;
+            }
+        }
+    }
+     
+
+General questions
+-----------------
+
+.. topic:: Errors/bugs reporting
+
+    I found an error in the documentation / bug in the code. What should I do?
+
+Please create an issue for the documentation error or code bug.  
+We will try to resolve the problem as fast as we can.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3a2f47e..510cf3a 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -12,4 +12,5 @@
    helpers
    applications
    examples
+   faq
    boost-custom-install
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 5ec2355..4a7252a 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -70,6 +70,8 @@
 
 ndnSIM has been successfully compiled and used under Ubuntu Linux 12.04 (stock gcc, boost 1.48), Mac OS 10.8 (gcc-4.2 apple/llvm, macports gcc 4.7, boost 1.49 or 1.50).
 
+.. _requirements:
+
 Requirements
 -------------