diff options
| -rw-r--r-- | INSTALL | 170 | ||||
| -rw-r--r-- | Makefile | 54 |
2 files changed, 175 insertions, 49 deletions
diff --git a/INSTALL b/INSTALL new file mode 100644 index 00000000..d6f0f243 --- /dev/null +++ b/INSTALL @@ -0,0 +1,170 @@ +$Id$ + +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> @@ -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 $< > $@ |