README: minor wording tweak.

[nagios-mode.git] / README

diff --git a/README b/README
index 5e6129025e436374cfe37828902503745ec2fe6c..c184bce584ba3c4686f47f91db0ba6199036f39b 100644 (file)
--- a/README
+++ b/README
@@ -1,26 +1,20 @@
-1. What
+== What this is ==
 
-Nagios-mode is an Emacs mode for editing Nagios[1] configuration
-files. You probably already know that, or you wouldn't be reading
-this. But maybe you just love Emacs, and you go around looking for
-things that end in -mode. Then you README them.
+Nagios-mode is an Emacs mode for editing Nagios configuration
+files. Nagios is monitoring software that is configured via plain-text
+(*.cfg) files. Those configuration files have a C-like syntax, and a
+bunch of special keywords. Witin Emacs, nagios-mode will apply syntax
+highlighting to them, possibly alerting you to the fact that you have
+done something wrong, and making your buffers look pretty in any case.
 
-So, Nagios is monitoring software that is configured via plain-text
-(*.cfg) files. They have a C-like syntax, and a bunch of special
-keywords. Nagios mode will apply syntax highlighting to these
-configuration files, possibly alerting you to the fact that you have
-done something stupid. Moreover, the buffers will look prettier.
 
-[1] http://www.nagios.org/
-
-
-2. Where
+== How to install it ==
 
 Stick nagios-mode.el somewhere, and add that place to your Emacs load
 path. For example,
 
   (setq load-path
-    (append (list "~/.home/emacs/modes/nagios-mode/")                  
+    (append (list "~/.home/emacs/modes/nagios-mode/")
       load-path))
 
 is how I do it. With that in your load path, you just have to add
@@ -34,25 +28,27 @@ And tell Emacs to use it automatically when editing *.cfg files,
     (append (list '("\\.cfg$" . nagios-mode))
       auto-mode-alist))
 
-which is great as long as you don't have other *.cfg files with a
-different syntax. That case is left as an exercise for the reader.
+which works great so long as you don't edit any other *.cfg files that
+have a different syntax.
 
 
-3. How
+== How it works ==
 
 The macros and object definitions are parsed from the Nagios source
 code. Object definitions are found within xdata/xodtemplate.h, while
 the macros are cleverly hidden within include/macros.h. Once they have
-been parsed, they are cuth and pasteth in to nagios-mode.
+been parsed, they are cut and pasted in to nagios-mode.el.
+
+The directives are a bit tricker. They too are parsed from the Nagios
+source (xdata/xodtemplate.c), but not all of the names map nicely to
+internal C variables, so there's no explicit list of them. Instead we
+try to piece together the valid names based on what Nagios's config
+parser is looking for. It's possible that some have been overlooked.
 
-The directives (or variables) are another story. There is no obvious
-way to parse the object variables from the source code. So, it's done
-the old-fashioned way: I use nagios-mode until I notice that one of my
-variables isn't highlighted. Then I add it. You can mail me these and
-I will probably add them.
+The helper scripts for this can be found in the "utils" directory.
 
 
-4. When
+== Bugs et cetera ==
 
-No seriously, I'm running out of words to use as headings. Send bug
-reports and feature requests to michael@orlitzky.com.
+Send all bug reports, feature requests, and unprompted criticism to
+michael@orlitzky.com.