provide some instructions for manual installation

1 files changed, 119 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 00000000..4d0d721c
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,119 @@
+$Id: INSTALL,v 1.1 2014/08/08 16:45:39 schwarze Exp $
+
+Installing mdocml, the portable mandoc distribution
+---------------------------------------------------
+
+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.
+For general information, see:  http://mdocml.bsd.lv/
+
+Before manually installing mandoc on your system, please check
+whether the newest version of mandoc is already installed by default
+or available via a binary package or a ports system.  A list of the
+latest bundled and ported versions of mandoc for various operating
+systems is maintained at:  http://mdocml.bsd.lv/ports.html
+
+If mandoc is installed, you can check the version by typing:  mandoc -V
+The version contained in this distribution tarball is listed near
+the beginning of the file "Makefile".  Regarding how packages and
+ports are maintained for your operating system, please consult your
+operating system documentation.
+
+
+To install mandoc manually, the following steps are needed:
+
+1. Decide whether you want to build just the basic tools mandoc(1),
+preconv(1) and demandoc(1) or whether you also want to build the
+database tools apropos(1) and makewhatis(8).  For the latter, a
+working installation of SQLite is required, see: http://sqlite.org/
+The recommended version of SQLite is 3.8.4.3 or newer.  The mandoc
+toolset is known to work with version 3.7.5 or newer.  Versions
+older than 3.8.3 may not achieve full performance due to the
+missing SQLITE_DETERMINISTIC optimization flag.  Versions older
+than 3.8.0 may not show full error information if opening a database
+fails due to the missing sqlite3_errstr() API.  Both are very minor
+problems, apropos(1) is fully usable with SQLite 3.7.5.
+The database tools also require 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.
+
+2. If you choose to build the database tools, too, decide whether
+you also want to build the CGI program, man.cgi(8).
+
+3. Read the beginning of the file "Makefile" from "USER SETTINGS"
+to "END OF USER SETTINGS" and edit it as required.  In particular,
+disable "BUILD_TARGETS += db-build" if you do not want database
+support or enable "BUILD_TARGETS += cgi-build" if you do want
+the CGI program.
+
+4. Run the command "make".  No separate "./configure" or "make
+depend" steps are needed.  The former is run automatically by "make".
+The latter is a maintainer target.  If you merely want to build the
+released version as opposed to doing active development, there is
+no need to regenerate the dependency specifications.  Any
+POSIX-compatible make, in particular both BSD make and GNU make,
+is supposed to work.
+
+5. Run the command "make -n install" and check whether everything
+will be installed to the intended places.  Otherwise, edit the *DIR
+variables in the Makefile until it is.
+
+6. Run "sudo make install".  Instead, if you intend to build a binary
+package using some kind of fake root mechanism, you may need a
+command like "make DESTDIR=... install".  Read the *-install targets
+in the "Makefile" to understand how DESTDIR is used.
+
+
+If you want to check whether automatic configuration works well
+on your platform, consider the following:
+
+The mandoc package intentionally does not use GNU autoconf because
+we consider that toolset a blatant example of overengineering that
+is obsolete nowadays, since all modern operating systems are now
+reasonably close to POSIX and do not need arcane shell magic any
+longer.  If your system does need such magic, consider upgrading
+to reasonably modern POSIX-compliant tools rather than asking for
+autoconf-style workarounds.
+
+As far as mandoc is using any features not mandated by ANSI X3.159-1989
+("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems
+do not have, we intend to provide autoconfiguration tests and
+compat_*.c implementations.  Please report any that turn out to be
+missing.  Note that while we do strive to produce portable code,
+we do not slavishly restrict ourselves to POSIX-only interfaces.
+For improved security and readability, we do use well-designed,
+modern interfaces like reallocarray(3) even if they are still rather
+uncommon, of course bundling compat_*.c implementations as needed.
+
+Where mandoc is using ANSI C or POSIX features that some systems
+still lack and that compat_*.c implementations can be provided for
+without too much hassle, we will consider adding them, too, so
+please report whatever is missing on your platform.
+
+The following steps can be used to manually check the automatic
+configuration on your platform:
+
+1. Run "make clean".
+
+2. Run "make config.h"
+
+3. Read the file "config.log".  It shows the compiler commands used
+to test the libraries installed on your system and the standard
+output and standard error output these commands produce.  Watch out
+for unexpected failures.  Those are most likely to happen if headers
+or libraries are installed in unusual places or interfaces defined
+in unusual headers.  You can also look at the file "config.h" and
+check that no expected "#define HAVE_*" lines are missing.  The
+list of tests run can be found in the file "configure".
+
+
+In case you have questions or want to provide feedback, look at:
+http://mdocml.bsd.lv/contact.html
+
+Consider subscribing to the discuss@ mailing list mentioned on that
+page.  If you intend to help with the development of mandoc, consider
+subscribing to the tech@ mailing list, too.
+
+Enjoy using the mandoc toolset!
+Ingo Schwarze, Karlsruhe, August 2014