1322249Sbapt$Id: INSTALL,v 1.20 2017/07/28 14:57:56 schwarze Exp $ 2274876Sbapt 3322249SbaptAbout the portable mandoc distribution 4322249Sbapt-------------------------------------- 5322249SbaptThe mandoc manpage compiler toolset (formerly called "mdocml") 6322249Sbaptis a suite of tools compiling mdoc(7), the roff(7) macro language 7322249Sbaptof choice for BSD manual pages, and man(7), the predominant 8322249Sbapthistorical language for UNIX manuals. 9322249Sbapt 10280025SbaptIt includes a man(1) manual viewer and additional tools. 11322249SbaptFor general information, see <http://mandoc.bsd.lv/>. 12274876Sbapt 13274876SbaptIn case you have questions or want to provide feedback, read 14322249Sbapt<http://mandoc.bsd.lv/contact.html>. Consider subscribing to the 15274876Sbaptdiscuss@ mailing list mentioned on that page. If you intend to 16274876Sbapthelp with the development of mandoc, consider subscribing to the 17274876Sbapttech@ mailing list, too. 18274876Sbapt 19274876SbaptEnjoy using the mandoc toolset! 20274876Sbapt 21322249SbaptIngo Schwarze, Karlsruhe, July 2017 22274876Sbapt 23274876Sbapt 24274876SbaptInstallation 25274876Sbapt------------ 26274876SbaptBefore manually installing mandoc on your system, please check 27274876Sbaptwhether the newest version of mandoc is already installed by default 28274876Sbaptor available via a binary package or a ports system. A list of the 29274876Sbaptlatest bundled and ported versions of mandoc for various operating 30322249Sbaptsystems is maintained at <http://mandoc.bsd.lv/ports.html>. 31274876Sbapt 32274876SbaptRegarding how packages and ports are maintained for your operating 33274876Sbaptsystem, please consult your operating system documentation. 34274876SbaptTo install mandoc manually, the following steps are needed: 35274876Sbapt 36322249Sbapt1. If you want to build the CGI program, man.cgi(8), too, 37322249Sbaptrun the command "echo BUILD_CGI=1 >> configure.local". 38322249SbaptThen run "cp cgi.h.example cgi.h" and edit cgi.h as desired. 39274876Sbapt 40322249Sbapt2. If you also want to build the catman(8) utility, run the 41322249Sbaptcommand "echo BUILD_CATMAN=1 >> configure.local". Note that it 42322249Sbaptis unlikely to be a drop-in replacement providing the same 43322249Sbaptfunctionality as your system's "catman", if your operating 44322249Sbaptsystem contains one. 45322249Sbapt 46322249Sbapt3. Define MANPATH_DEFAULT in configure.local 47316420Sbaptif /usr/share/man:/usr/X11R6/man:/usr/local/man is not appropriate 48316420Sbaptfor your operating system. 49316420Sbapt 50322249Sbapt4. Run "./configure". 51275432SbaptThis script attempts autoconfiguration of mandoc for your system. 52275432SbaptRead both its standard output and the file "Makefile.local" it 53275432Sbaptgenerates. If anything looks wrong or different from what you 54275432Sbaptwish, read the file "configure.local.example", create and edit 55275432Sbapta file "configure.local", and re-run "./configure" until the 56275432Sbaptresult seems right to you. 57294113SbaptOn Solaris 10 and earlier, you may have to run "ksh ./configure" 58294113Sbaptbecause the native /bin/sh lacks some POSIX features. 59275432Sbapt 60322249Sbapt5. Run "make". 61275432SbaptAny POSIX-compatible make, in particular both BSD make and GNU make, 62275432Sbaptshould work. If the build fails, look at "configure.local.example" 63275432Sbaptand go back to step 2. 64275432Sbapt 65322249Sbapt6. Run "make -n install" and check whether everything will be 66276219Sbaptinstalled to the intended places. Otherwise, put some *DIR or *NM* 67322249Sbaptvariables into "configure.local" and go back to step 4. 68275432Sbapt 69322249Sbapt7. Optionally run the regression suite. 70322249SbaptBasically, that amounts to "cd regress && ./regress.pl". 71322249SbaptBut you should probably look at "./mandoc -l regress/regress.pl.1" 72322249Sbaptfirst. 73322249Sbapt 74322249Sbapt8. Run "sudo make install". If you intend to build a binary 75275432Sbaptpackage using some kind of fake root mechanism, you may need a 76275432Sbaptcommand like "make DESTDIR=... install". Read the *-install targets 77275432Sbaptin the "Makefile" to understand how DESTDIR is used. 78275432Sbapt 79322249Sbapt9. Run the command "sudo makewhatis" to build mandoc.db(5) databases 80322249Sbaptin all the directory trees configured in step 3. Whenever installing 81322249Sbaptnew manual pages, re-run makewhatis(8) to update the databases, or 82322249Sbaptapropos(1) will not find the new pages. 83275432Sbapt 84322249Sbapt10. To set up a man.cgi(8) server, read its manual page. 85275432Sbapt 86280025SbaptNote that some man(7) pages may contain low-level roff(7) markup 87280025Sbaptthat mandoc does not yet understand. On some BSD systems using 88280025Sbaptmandoc, third-party software is vetted on whether it may be formatted 89280025Sbaptwith mandoc. If not, groff(1) is pulled in as a dependency and 90280025Sbaptused to install a pre-formatted "catpage" instead of directly as 91280025Sbaptmanual page source. 92280025Sbapt 93280025Sbapt 94275432SbaptUnderstanding mandoc dependencies 95275432Sbapt--------------------------------- 96316420SbaptThe following libraries are required: 97275432Sbapt 98316420Sbapt1. zlib for decompressing gzipped manual pages. 99274876Sbapt 100276219Sbapt2. The fts(3) directory traversion functions. 101275432SbaptIf your system does not have them, the bundled compatibility version 102322249Sbaptwill be used, so you need not worry in that case. But be careful: old 103322249Sbaptglibc versions of fts(3) were known to be broken on 32bit platforms, 104322249Sbaptsee <https://sourceware.org/bugzilla/show_bug.cgi?id=11460>. 105322249SbaptThat was presumably fixed in glibc-2.23. 106275432SbaptIf you run into that problem, set "HAVE_FTS=0" in configure.local. 107274876Sbapt 108276219Sbapt3. Marc Espie's ohash(3) library. 109274876SbaptIf your system does not have it, the bundled compatibility version 110274876Sbaptwill be used, so you probably need not worry about it. 111274876Sbapt 112294113SbaptOne of the chief design goals of the mandoc toolbox is to make 113294113Sbaptsure that nothing related to documentation requires C++. 114294113SbaptConsequently, linking mandoc against any kind of C++ program 115294113Sbaptwould defeat the purpose and is not supported. 116274876Sbapt 117294113Sbapt 118274876SbaptChecking autoconfiguration quality 119274876Sbapt---------------------------------- 120274876SbaptIf you want to check whether automatic configuration works well 121274876Sbapton your platform, consider the following: 122274876Sbapt 123274876SbaptThe mandoc package intentionally does not use GNU autoconf because 124274876Sbaptwe consider that toolset a blatant example of overengineering that 125274876Sbaptis obsolete nowadays, since all modern operating systems are now 126274876Sbaptreasonably close to POSIX and do not need arcane shell magic any 127274876Sbaptlonger. If your system does need such magic, consider upgrading 128274876Sbaptto reasonably modern POSIX-compliant tools rather than asking for 129274876Sbaptautoconf-style workarounds. 130274876Sbapt 131274876SbaptAs far as mandoc is using any features not mandated by ANSI X3.159-1989 132274876Sbapt("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems 133274876Sbaptdo not have, we intend to provide autoconfiguration tests and 134274876Sbaptcompat_*.c implementations. Please report any that turn out to be 135274876Sbaptmissing. Note that while we do strive to produce portable code, 136274876Sbaptwe do not slavishly restrict ourselves to POSIX-only interfaces. 137274876SbaptFor improved security and readability, we do use well-designed, 138274876Sbaptmodern interfaces like reallocarray(3) even if they are still rather 139274876Sbaptuncommon, of course bundling compat_*.c implementations as needed. 140274876Sbapt 141274876SbaptWhere mandoc is using ANSI C or POSIX features that some systems 142274876Sbaptstill lack and that compat_*.c implementations can be provided for 143274876Sbaptwithout too much hassle, we will consider adding them, too, so 144274876Sbaptplease report whatever is missing on your platform. 145274876Sbapt 146274876SbaptThe following steps can be used to manually check the automatic 147274876Sbaptconfiguration on your platform: 148274876Sbapt 149275432Sbapt1. Run "make distclean". 150274876Sbapt 151275432Sbapt2. Run "./configure" 152274876Sbapt 153274876Sbapt3. Read the file "config.log". It shows the compiler commands used 154274876Sbaptto test the libraries installed on your system and the standard 155274876Sbaptoutput and standard error output these commands produce. Watch out 156274876Sbaptfor unexpected failures. Those are most likely to happen if headers 157274876Sbaptor libraries are installed in unusual places or interfaces defined 158274876Sbaptin unusual headers. You can also look at the file "config.h" and 159275432Sbaptcheck that no "#define HAVE_*" differ from your expectations. 160