1$Id: INSTALL,v 1.22 2018/07/31 15:34:00 schwarze Exp $ 2 3About the portable mandoc distribution 4-------------------------------------- 5The mandoc manpage compiler toolset (formerly called "mdocml") 6is a suite of tools compiling mdoc(7), the roff(7) macro language 7of choice for BSD manual pages, and man(7), the predominant 8historical language for UNIX manuals. 9 10It includes a man(1) manual viewer and additional tools. 11For general information, see <http://mandoc.bsd.lv/>. 12 13In case you have questions or want to provide feedback, read 14<http://mandoc.bsd.lv/contact.html>. Consider subscribing to the 15discuss@ mailing list mentioned on that page. If you intend to 16help with the development of mandoc, consider subscribing to the 17tech@ mailing list, too. 18 19Enjoy using the mandoc toolset! 20 21Ingo Schwarze, Karlsruhe, August 2018 22 23 24Installation 25------------ 26Before manually installing mandoc on your system, please check 27whether the newest version of mandoc is already installed by default 28or available via a binary package or a ports system. A list of the 29latest bundled and ported versions of mandoc for various operating 30systems is maintained at <http://mandoc.bsd.lv/ports.html>. 31 32Regarding how packages and ports are maintained for your operating 33system, please consult your operating system documentation. 34To install mandoc manually, the following steps are needed: 35 361. If you want to build the CGI program, man.cgi(8), too, 37run the command "echo BUILD_CGI=1 >> configure.local". 38Then run "cp cgi.h.example cgi.h" and edit cgi.h as desired. 39 402. If you also want to build the catman(8) utility, run the 41command "echo BUILD_CATMAN=1 >> configure.local". Note that it 42is unlikely to be a drop-in replacement providing the same 43functionality as your system's "catman", if your operating 44system contains one. 45 463. Define MANPATH_DEFAULT in configure.local 47if /usr/share/man:/usr/X11R6/man:/usr/local/man is not appropriate 48for your operating system. 49 504. Run "./configure". 51This script attempts autoconfiguration of mandoc for your system. 52Read both its standard output and the file "Makefile.local" it 53generates. If anything looks wrong or different from what you 54wish, read the file "configure.local.example", create and edit 55a file "configure.local", and re-run "./configure" until the 56result seems right to you. 57 585. Run "make". 59Any POSIX-compatible make, in particular both BSD make and GNU make, 60should work. If the build fails, look at "configure.local.example" 61and go back to step 2. 62 636. Run "make -n install" and check whether everything will be 64installed to the intended places. Otherwise, put some *DIR or *NM* 65variables into "configure.local" and go back to step 4. 66 677. Optionally run the regression suite. 68Basically, that amounts to "cd regress && ./regress.pl". 69But you should probably look at "./mandoc -l regress/regress.pl.1" 70first. 71 728. Run "sudo make install". If you intend to build a binary 73package using some kind of fake root mechanism, you may need a 74command like "make DESTDIR=... install". Read the *-install targets 75in the "Makefile" to understand how DESTDIR is used. 76 779. Run the command "sudo makewhatis" to build mandoc.db(5) databases 78in all the directory trees configured in step 3. Whenever installing 79new manual pages, re-run makewhatis(8) to update the databases, or 80apropos(1) will not find the new pages. 81 8210. To set up a man.cgi(8) server, read its manual page. 83 84Note that a very small number of man(7) pages contain low-level 85roff(7) markup that mandoc does not yet understand. On some BSD 86systems using mandoc, third-party software is vetted on whether it 87may be formatted with mandoc. If not, groff(1) is pulled in as a 88dependency and used to install pre-formatted "catpages" instead of 89manual page sources. This mechanism is used much less frequently 90than in the past. On OpenBSD, only 25 out of about 10000 ports 91still require formatting with groff(1). 92 93 94Understanding mandoc dependencies 95--------------------------------- 96The following libraries are required: 97 981. zlib for decompressing gzipped manual pages. 99 1002. The fts(3) directory traversion functions. 101If your system does not have them, the bundled compatibility version 102will be used, so you need not worry in that case. But be careful: old 103glibc versions of fts(3) were known to be broken on 32bit platforms, 104see <https://sourceware.org/bugzilla/show_bug.cgi?id=11460>. 105That was presumably fixed in glibc-2.23. 106If you run into that problem, set "HAVE_FTS=0" in configure.local. 107 1083. Marc Espie's ohash(3) library. 109If your system does not have it, the bundled compatibility version 110will be used, so you probably need not worry about it. 111 112One of the chief design goals of the mandoc toolbox is to make 113sure that nothing related to documentation requires C++. 114Consequently, linking mandoc against any kind of C++ program 115would defeat the purpose and is not supported. 116 117 118Checking autoconfiguration quality 119---------------------------------- 120If you want to check whether automatic configuration works well 121on your platform, consider the following: 122 123The mandoc package intentionally does not use GNU autoconf because 124we consider that toolset a blatant example of overengineering that 125is obsolete nowadays, since all modern operating systems are now 126reasonably close to POSIX and do not need arcane shell magic any 127longer. If your system does need such magic, consider upgrading 128to reasonably modern POSIX-compliant tools rather than asking for 129autoconf-style workarounds. 130 131As far as mandoc is using any features not mandated by ANSI X3.159-1989 132("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems 133do not have, we intend to provide autoconfiguration tests and 134compat_*.c implementations. Please report any that turn out to be 135missing. Note that while we do strive to produce portable code, 136we do not slavishly restrict ourselves to POSIX-only interfaces. 137For improved security and readability, we do use well-designed, 138modern interfaces like reallocarray(3) even if they are still rather 139uncommon, of course bundling compat_*.c implementations as needed. 140 141Where mandoc is using ANSI C or POSIX features that some systems 142still lack and that compat_*.c implementations can be provided for 143without too much hassle, we will consider adding them, too, so 144please report whatever is missing on your platform. 145 146The following steps can be used to manually check the automatic 147configuration on your platform: 148 1491. Run "make distclean". 150 1512. Run "./configure" 152 1533. Read the file "config.log". It shows the compiler commands used 154to test the libraries installed on your system and the standard 155output and standard error output these commands produce. Watch out 156for unexpected failures. Those are most likely to happen if headers 157or libraries are installed in unusual places or interfaces defined 158in unusual headers. You can also look at the file "config.h" and 159check that no "#define HAVE_*" differ from your expectations. 160