mdocml: first cut at updating for the next release

[schwarze@mdocml.bsd.lv]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=utf-8, Size: 5552 bytes --]

Log Message:
-----------
first cut at updating for the next release

Modified Files:
--------------
    mdocml:
        INSTALL

Revision Data
-------------
Index: INSTALL
===================================================================
RCS file: /home/cvs/mdocml/mdocml/INSTALL,v
retrieving revision 1.6
retrieving revision 1.7
diff -LINSTALL -LINSTALL -u -p -r1.6 -r1.7
--- INSTALL
+++ INSTALL
@@ -5,9 +5,8 @@ About mdocml, the portable mandoc distri
 The mandoc manpage compiler toolset is a suite of tools compiling
 mdoc(7), the roff(7) macro language of choice for BSD manual pages,
 and man(7), the predominant historical language for UNIX manuals.
-The toolset does not yet implement man(1); that is only scheduled
-for the next release, 1.13.2.  It can, however, already serve to
-translate source manpages to the output displayed by man(1).
+Since the present version 1.13.2, it includes a man(1) manual viewer
+in addition to the apropos(1) manual page search tool.
 For general information, see <http://mdocml.bsd.lv/>.
 
 In this document, we describe the installation and deployment of
@@ -22,7 +21,7 @@ tech@ mailing list, too.
 
 Enjoy using the mandoc toolset!
 
-Ingo Schwarze, Karlsruhe, August 2014
+Ingo Schwarze, Karlsruhe, December 2014
 
 
 Installation
@@ -59,8 +58,8 @@ should work.  If the build fails, look a
 and go back to step 2.
 
 4. Run "make -n install" and check whether everything will be
-installed to the intended places.  Otherwise, put some *DIR variables
-into "configure.local" and go back to step 2.
+installed to the intended places.  Otherwise, put some *DIR or *NM*
+variables into "configure.local" and go back to step 2.
 
 5. Run "sudo make install".  If you intend to build a binary
 package using some kind of fake root mechanism, you may need a
@@ -70,14 +69,14 @@ in the "Makefile" to understand how DEST
 6. To set up a man.cgi(8) server, read its manual page.
 
 7. To use mandoc(1) as your man(1) formatter, read the "Deployment"
-section below.
+sections below.
 
 
 Understanding mandoc dependencies
 ---------------------------------
-The mandoc(1), preconv(1), and demandoc(1) utilities have no external
-dependencies.  However, makewhatis(8) and apropos(1) depend on the
-following software:
+The mandoc(1) and demandoc(1) utilities have no external dependencies.
+However, makewhatis(8), apropos(1), and man(1) depend on the following
+software:
 
 1. The SQLite database system, see <http://sqlite.org/>.
 The recommended version of SQLite is 3.8.4.3 or newer.  The mandoc
@@ -89,14 +88,14 @@ fails due to the missing sqlite3_errstr(
 problems, apropos(1) is fully usable with SQLite 3.7.5.  Versions
 older than 3.7.5 may or may not work, they have not been tested.
 
-1.2. The fts(3) directory traversion functions.
+2. The fts(3) directory traversion functions.
 If your system does not have them, the bundled compatibility version
 will be used, so you need not worry in that case.  But be careful: the
 glibc version of fts(3) is known to be broken on 32bit platforms,
 see <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>.
 If you run into that problem, set "HAVE_FTS=0" in configure.local.
 
-1.3. Marc Espie's ohash(3) library.
+3. Marc Espie's ohash(3) library.
 If your system does not have it, the bundled compatibility version
 will be used, so you probably need not worry about it.
 
@@ -145,11 +144,36 @@ in unusual headers.  You can also look a
 check that no "#define HAVE_*" differ from your expectations.
 
 
-Deployment
-----------
-If you want to integrate the mandoc(1) tools with your existing
-man(1) system as a formatter, then contact us first: on systems without
-mandoc(1) as the default, you may have your work cut out for you!
+Deployment using the integrated man(1) viewer
+---------------------------------------------
+This mode of deployment requires database support.  In case of
+doubt, look at the section "user settings related to database
+support" in the file configure.local.example.
+
+Deployment requires the following steps:
+
+1. Build and install mandoc as described above in steps 2 to 5
+below "Installation".
+
+2. If you system uses manpath(1), make sure it is configured
+correctly, in particular, it returns all directory trees where
+manual pages are installed.  If your system uses man.conf(5), make
+sure it contains a "_whatdb" for each directory tree, and the order
+of these lines meets your wishes.
+
+3. Run the command "sudo makewhatis" to build mandoc.db(5) databases
+in all the directory trees configured in step 2.
+
+At this point, your new man(1), apropos(1), and whatis(1) should work.
+Otherwise, please look at <http://mdocml.bsd.lv/contact.html>, both
+for help and to have these instructions improved.
+
+
+Deployment using your system's native man(1) viewer
+---------------------------------------------------
+This mode of deployment does not require database support,
+so it works even if you don't have SQLite3.
+
 Usually, you can have your default installation and mandoc(1) work right
 alongside each other by using user-specific versions of the files
 mentioned below.
@@ -173,6 +197,7 @@ mandoc(1)" to disregard them.
 3. Finally, make sure that mandoc(1) is actually being invoked instead
 of cached pages being pulled up.  You can usually do this by commenting
 out NOCACHE or similar.
+
 
 mandoc(1) still has a long way to go in understanding non-trivial
 low-level roff(7) markup embedded in some man(7) pages.  On the BSD
--
 To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv