1$Id: INSTALL,v 1.23 2019/03/06 15:58:10 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, March 2019 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. In particular, regarding Solaris systems, look at the BUGS 71section of that manual page. 72 738. Run "sudo make install". If you intend to build a binary 74package using some kind of fake root mechanism, you may need a 75command like "make DESTDIR=... install". Read the *-install targets 76in the "Makefile" to understand how DESTDIR is used. 77 789. Run the command "sudo makewhatis" to build mandoc.db(5) databases 79in all the directory trees configured in step 3. Whenever installing 80new manual pages, re-run makewhatis(8) to update the databases, or 81apropos(1) will not find the new pages. 82 8310. To set up a man.cgi(8) server, read its manual page. 84 85Note that a very small number of man(7) pages contain low-level 86roff(7) markup that mandoc does not yet understand. On some BSD 87systems using mandoc, third-party software is vetted on whether it 88may be formatted with mandoc. If not, groff(1) is pulled in as a 89dependency and used to install pre-formatted "catpages" instead of 90manual page sources. This mechanism is used much less frequently 91than in the past. On OpenBSD, only 25 out of about 10000 ports 92still require formatting with groff(1). 93 94 95Understanding mandoc dependencies 96--------------------------------- 97The following libraries are required: 98 991. zlib for decompressing gzipped manual pages. 100 1012. The fts(3) directory traversion functions. 102If your system does not have them, the bundled compatibility version 103will be used, so you need not worry in that case. But be careful: old 104glibc versions of fts(3) were known to be broken on 32bit platforms, 105see <https://sourceware.org/bugzilla/show_bug.cgi?id=11460>. 106That was presumably fixed in glibc-2.23. 107If you run into that problem, set "HAVE_FTS=0" in configure.local. 108 1093. Marc Espie's ohash(3) library. 110If your system does not have it, the bundled compatibility version 111will be used, so you probably need not worry about it. 112 113One of the chief design goals of the mandoc toolbox is to make 114sure that nothing related to documentation requires C++. 115Consequently, linking mandoc against any kind of C++ program 116would defeat the purpose and is not supported. 117 118 119Checking autoconfiguration quality 120---------------------------------- 121If you want to check whether automatic configuration works well 122on your platform, consider the following: 123 124The mandoc package intentionally does not use GNU autoconf because 125we consider that toolset a blatant example of overengineering that 126is obsolete nowadays, since all modern operating systems are now 127reasonably close to POSIX and do not need arcane shell magic any 128longer. If your system does need such magic, consider upgrading 129to reasonably modern POSIX-compliant tools rather than asking for 130autoconf-style workarounds. 131 132As far as mandoc is using any features not mandated by ANSI X3.159-1989 133("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems 134do not have, we intend to provide autoconfiguration tests and 135compat_*.c implementations. Please report any that turn out to be 136missing. Note that while we do strive to produce portable code, 137we do not slavishly restrict ourselves to POSIX-only interfaces. 138For improved security and readability, we do use well-designed, 139modern interfaces like reallocarray(3) even if they are still rather 140uncommon, of course bundling compat_*.c implementations as needed. 141 142Where mandoc is using ANSI C or POSIX features that some systems 143still lack and that compat_*.c implementations can be provided for 144without too much hassle, we will consider adding them, too, so 145please report whatever is missing on your platform. 146 147The following steps can be used to manually check the automatic 148configuration on your platform: 149 1501. Run "make distclean". 151 1522. Run "./configure" 153 1543. Read the file "config.log". It shows the compiler commands used 155to test the libraries installed on your system and the standard 156output and standard error output these commands produce. Watch out 157for unexpected failures. Those are most likely to happen if headers 158or libraries are installed in unusual places or interfaces defined 159in unusual headers. You can also look at the file "config.h" and 160check that no "#define HAVE_*" differ from your expectations. 161