Add INSTALL, and remove WWW gunk from the Makefile, we are not

going to rebuild the website from this version.

2 files changed, 176 insertions, 50 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 00000000..06aa0ef5
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,170 @@
+$Id: INSTALL,v 1.3.2.1 2014/08/14 20:43:22 schwarze Exp $
+
+About 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.
+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).
+For general information, see <http://mdocml.bsd.lv/>.
+
+In this document, we describe the installation and deployment of
+mandoc(1), first as a simple, standalone formatter, and then as part of
+the man(1) system.
+
+In case you have questions or want to provide feedback, read
+<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
+
+
+Installation
+------------
+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 running "mandoc -V".
+
+The version contained in this distribution tarball is 1.12.4.
+This is not the newest version available, you can also get 1.13.1.
+Installing 1.12.4 only makes sense if all of the following conditions
+hold for you:
+
+ - You need apropos(1) and makewhatis(8) functionality.
+ - You do not need the man.cgi(8) web frontend.
+ - You do have the Berkeley database library, version 1.85.
+ - You lack at least one of the following: the SQLite3 database
+   library and/or the fts(3) file hierarchy traversal functions.
+
+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 the base tools mandoc(1),
+preconv(1) and demandoc(1) only or whether you also want to build the
+database tools apropos(1) and makewhatis(8).  For the latter,
+the Berkeley database system, version 1.85, is required.
+It is installed by default on BSD systems and available as an
+optional software package on other systems.
+
+2. 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.
+
+3. Run "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, should work.
+
+4. Run "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.
+
+5. Run "sudo make install".  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.
+
+6. To use mandoc(1) as your man(1) formatter, read the "Deployment"
+section below.
+
+
+Checking autoconfiguration quality
+----------------------------------
+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".
+
+
+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!
+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.
+
+0. Back up each file you want to change!
+
+1. First see whether your system has "/etc/man.conf" or "/etc/manpath.conf"
+(if it has neither, but man(1) is functional, then let us know) or,
+if running as your own user, a per-user override file.  In either
+case, find where man(1) is executing nroff(1) or groff(1) to format
+manuals.  Replace these calls with mandoc(1).
+
+2. Then make sure that man(1) isn't running preprocessors, so you may
+need to replace tbl(1), eqn(1), and similar references with cat(1).
+Some man(1) implementations, like that on Mac OSX, let you run "man -d"
+to see how the formatter is invoked.  Use this to test your changes.  On
+Mac OS X, for instance, man(1) will prepend all files with ".ll" and
+".nr" to set the terminal size, so you need to pass "tail -n+2 |
+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
+systems using mandoc(1), third-party software is generally vetted
+on whether it may be formatted with mandoc(1).  If not, groff(1)
+is pulled in as a dependency and used to install a pre-formatted
+"catpage" intead of directly as manual page source.
+
+For more background on switching operating systems to use mandoc(1)
+instead of groff(1) to format manuals, see the two BSDCan presentations
+by Ingo Schwarze:
+<http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html>
+<http://www.openbsd.org/papers/bsdcan14-mandoc.pdf>
diff --git a/Makefile b/Makefile
index 66dc6cfc..4fd749a1 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-# $Id: Makefile,v 1.395.2.28 2014/08/12 21:37:42 schwarze Exp $
+# $Id: Makefile,v 1.395.2.29 2014/08/14 20:43:22 schwarze Exp $
 #
 # Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 # Copyright (c) 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -73,9 +73,6 @@ BUILD_TARGETS	+= db-build
 #
 #CFLAGS		+= -DUSE_MANPATH
 
-WWWPREFIX	 = /var/www
-HTDOCDIR	 = $(WWWPREFIX)/htdocs
-
 # === END OF USER SETTINGS =============================================
 
 INSTALL_TARGETS	 = $(BUILD_TARGETS:-build=-install)
@@ -150,7 +147,8 @@ SRCS		 = apropos.c \
 		   vol.c \
 		   $(TESTSRCS)
 
-DISTFILES	 = LICENSE \
+DISTFILES	 = INSTALL \
+		   LICENSE \
 		   Makefile \
 		   Makefile.depend \
 		   NEWS \
@@ -275,30 +273,6 @@ APROPOS_OBJS	 = apropos.o apropos_db.o manpath.o
 
 DEMANDOC_OBJS	 = demandoc.o
 
-WWW_MANS	 = apropos.1.html \
-		   demandoc.1.html \
-		   mandoc.1.html \
-		   preconv.1.html \
-		   whatis.1.html \
-		   mandoc.3.html \
-		   mandoc_escape.3.html \
-		   mandoc_html.3.html \
-		   mandoc_malloc.3.html \
-		   mchars_alloc.3.html \
-		   tbl.3.html \
-		   eqn.7.html \
-		   man.7.html \
-		   mandoc_char.7.html \
-		   mdoc.7.html \
-		   roff.7.html \
-		   tbl.7.html \
-		   mandocdb.8.html \
-		   man.h.html \
-		   mandoc.h.html \
-		   mandoc_aux.h.html \
-		   manpath.h.html \
-		   mdoc.h.html
-
 WWW_OBJS	 = mdocml.tar.gz \
 		   mdocml.sha256
 
@@ -312,7 +286,7 @@ db-build: $(DBBIN)
 
 install: base-install $(INSTALL_TARGETS)
 
-www: $(WWW_OBJS) $(WWW_MANS)
+www: $(WWW_OBJS)
 
 include Makefile.depend
 
@@ -326,7 +300,7 @@ clean:
 	rm -f demandoc $(DEMANDOC_OBJS)
 	rm -f mandoc $(MANDOC_OBJS)
 	rm -f config.h config.log $(COMPAT_OBJS)
-	rm -f $(WWW_MANS) $(WWW_OBJS)
+	rm -f $(WWW_OBJS)
 	rm -rf *.dSYM
 
 base-install: base-build
@@ -357,15 +331,6 @@ db-install: db-build
 	$(INSTALL_MAN) apropos.1 whatis.1 $(DESTDIR)$(MANDIR)/man1
 	$(INSTALL_MAN) mandocdb.8 $(DESTDIR)$(MANDIR)/man8
 
-www-install: www
-	mkdir -p $(DESTDIR)$(HTDOCDIR)/snapshots
-	$(INSTALL_DATA) $(WWW_MANS) style.css $(DESTDIR)$(HTDOCDIR)
-	$(INSTALL_DATA) $(WWW_OBJS) $(DESTDIR)$(HTDOCDIR)/snapshots
-	$(INSTALL_DATA) mdocml.tar.gz \
-		$(DESTDIR)$(HTDOCDIR)/snapshots/mdocml-$(VERSION).tar.gz
-	$(INSTALL_DATA) mdocml.sha256 \
-		$(DESTDIR)$(HTDOCDIR)/snapshots/mdocml-$(VERSION).sha256
-
 depend: config.h
 	mkdep -f Makefile.depend $(CFLAGS) $(SRCS)
 	perl -e 'undef $$/; $$_ = <>; s|/usr/include/\S+||g; \
@@ -404,14 +369,5 @@ config.h: configure config.h.pre config.h.post $(TESTSRCS)
 	rm -f config.log
 	CC="$(CC)" CFLAGS="$(CFLAGS)" VERSION="$(VERSION)" ./configure
 
-.PHONY: 	 base-install db-install install www-install
+.PHONY: 	 base-install db-install install
 .PHONY: 	 clean depend
-.SUFFIXES:	 .1       .3       .5       .7       .8       .h
-.SUFFIXES:	 .1.html  .3.html  .5.html  .7.html  .8.html  .h.html
-
-.h.h.html:
-	highlight -I $< > $@
-
-.1.1.html .3.3.html .5.5.html .7.7.html .8.8.html: mandoc
-	./mandoc -Thtml -Wall,stop \
-		-Ostyle=style.css,man=%N.%S.html,includes=%I.html $< > $@