update plugin-writing docs for site_local_files setting

lib/App/Netdisco/Manual/Configuration.pod

@@ -159,23 +159,21 @@ Value: List. Default: Empty List.
 Additional paths for L<Template::Toolkit> templates. Files in these paths will
 be loaded before (and hence override) any templates built in to Netdisco.
 
-If you do want to copy and override a built in web template, then create the
+If you want to copy and override a built in web template, then create the
-directories necessary (such as "ajax" or "sidebar") in this path.
+directories necessary (such as "ajax" or "sidebar") in this path.  Note that
-
+templates may need to have a further "C<views>" subdirectory created.
-Note that templates may need to have a further "C<views>" subdirectory
-created.
 
 =head3 C<site_local_files>
 
 Value: Boolean. Default: false.
 
 A shortcut for using C<include_paths> and C<template_paths>. Setting this to
-true will push C<< $home/nd-site-local/{lib,share} >> into those settings,
+true will push C<< $ENV{NETDISCO_HOME}/nd-site-local/{lib,share} >> into those
-respectively. You can then put Perl code in C</lib> and templates in C</share>
+settings, respectively. You can then put Perl code in C</lib> and templates in
-within the C<nd-site-local> directory (you have to create this yourself).
+C</share> within the C<nd-site-local> directory.
 
-Note that templates may need to have a further "C<views>" subdirectory
+Note that you still need to create the directories yourself, and templates may
-created.
+need to have a further "C<views>" subdirectory created within "C<share>".
 
 =head3 C<external_databases>
 

lib/App/Netdisco/Manual/Troubleshooting.pod

@@ -79,6 +79,13 @@ See the tips at L<Vendors Guide|App::Netdisco::Manual::Vendors>, or else
 contact the L<community email
 list|https://lists.sourceforge.net/lists/listinfo/netdisco-users>.
 
+=head1 Devices are not being discovered
+
+Besides reading the whole of this manual page for general tips, take a look at
+the "SNMP Connect Failures" report under the Admin menu. Any devices listed
+have had multiple SNMP connect failures, indicating a possible configuration
+error on the device or in Netdisco's configuration.
+
 =head1 After OS update or upgrade, Netdisco fails
 
 If you upgrade the operating system then your system libraries will change and

lib/App/Netdisco/Manual/WritingPlugins.pod

@@ -118,8 +118,8 @@ the name of the registration helper sub:
 =head1 Reports
 
 Report components contain pre-canned searches which the user community have
-found to be useful. Before you go further, it might be the case that you can
+found to be useful. Before you go further, it might be the case that Netdisco
-generate the report without any Perl or HTML: see the L<Reports
+can generate the report for you without any Perl or HTML: see the L<Reports
 Configuration|App::Netdisco::Manual::Configuration/reports> for details.
 
 Otherwise, the typical implementation is very similar to one of the Search
@@ -267,9 +267,11 @@ To register the column call the following helper routine:
    default  => 'on',   # or undef
  });
 
-App::Netdisco searches for one Template::Toolkit file in the regular template
+App::Netdisco searches for Template::Toolkit files in the regular template
-include paths (see also C<register_template_path>, below). The template must
+include paths: either its internal locations, or those configured with the
-be called "C<device_port_column.tt>" on disk and live in the directory:
+C<site_local_files> setting or the C<register_template_path> helper (see
+below). The template must be called "C<device_port_column.tt>" on disk and
+live in the directory:
 
  plugin/myportcolumnplugin/device_port_column.tt
 
@@ -293,9 +295,11 @@ To register the column call the following helper routine:
    label => 'My Device Details Heading',
  });
 
-App::Netdisco searches for one Template::Toolkit file in the regular template
+App::Netdisco searches for Template::Toolkit files in the regular template
-include paths (see also C<register_template_path>, below). The template must
+include paths: either its internal locations, or those configured with the
-be called "C<device_details.tt>" on disk and live in the directory:
+C<site_local_files> setting or the C<register_template_path> helper (see
+below). The template must be called "C<device_port_column.tt>" on disk and
+live in the directory:
 
  plugin/mydevicedetailsplugin/device_details.tt
 
@@ -363,7 +367,15 @@ probably installed in your system's or user's Perl directory. It's not
 recommended that you mess about with those files.
 
 So in order to replace a template with your own version, or to reference a
-template file of your own in your plugin, you need a new path:
+template file of your own in your plugin, you need a new path.
+
+If you don't plan on redistributing the plugin via CPAN, then configuring the
+"C<site_local_files>" setting to be true will enable "C</nd-site-local/lib>"
+for Perl code and "C</nd-site-local/share>" for tmplates in your Netdisco home
+location. You will need to create these directories.
+
+Alternatively, shipping templates within a CPAN distribution, the following
+code would be appropriate:
 
  package App::Netdisco::Web::Plugin::Search::MyNewFeature
   
@@ -429,11 +441,14 @@ current page with some additional parameters, for example:
 A simple mechanism exists for loading additional Javascript and CSS documents.
 This is done in the C<< <head> >> section of the web page.
 
-Within a Template include path (see C<register_template_path>, above) create a
+Netdisco searches all template include paths, both those built into the
-directory called "C<plugin>" and within that another directory named after
+application and those configured in your plugin(s) with "C<site_local_files>"
-your plugin (e.g. "C<mynewfeature>"). The Javascript and/or CSS files must
+or C<register_template_path>.
-then be named "C<mynewfeature.js>" and "C<mynewfeature.css>" respectively.
+
-For example:
+Within the template location, create a directory called "C<plugin>" and within
+that another directory named after your plugin (e.g. "C<mynewfeature>"). The
+Javascript and/or CSS files must then be named "C<mynewfeature.js>" and
+"C<mynewfeature.css>" respectively. For example:
 
   plugin/mynewfeature/mynewfeature.js
   plugin/mynewfeature/mynewfeature.css
@@ -444,10 +459,6 @@ helper routines:
   register_javascript('mynewfeature');
   register_css('mynewfeature');
 
-Note that this searches all template include paths, both those built into the
-application and those configured in your plugin(s) with
-C<register_template_path>.
-
 =head1 Naming and File Location
 
 There are several options for how you name, distribute and install your
@@ -467,16 +478,25 @@ abbreviated form "X::MyPluginName" which is then expanded to the full package.
 
 =head2 File Location
 
-If writing your own plugins, Netdisco supports a local include path which is
+If writing your own plugins that are not for redistribution or packaging on
-usually C<~/site_plugins> (or C<${NETDISCO_HOME}/site_plugins>).
+CPAN, Netdisco can enable local include paths for Perl, templates, and static
+content such as javascript and images.
 
-This means if your plugin is called
+Configuring the "C<site_local_files>" to be "true" enables:
+
+ # perl code
+ $ENV{NETDISCO_HOME}/nd-site-local/lib
+ 
+ # templates and static content
+ $ENV{NETDISCO_HOME}/nd-site-local/share
+
+Note that you still need to create the directories yourself, and templates may
+need to have a further "C<views>" subdirectory created within "C<share>".
+
+As an example, if your plugin is called
 "App::NetdiscoX::Web::Plugin::MyPluginName" then it could live at:
 
- ~/site_plugins/App/NetdiscoX/Web/Plugin/MyPluginName.pm
+ ~netdisco/nd-site-local/lib/App/NetdiscoX/Web/Plugin/MyPluginName.pm
-
-This feature should make development of new plugins or maintenance of local
-plugins much more straighforward.
 
 =head1 Plugin Configuration