1*6d38604fSBaptiste Daroussin$Id: INSTALL,v 1.24 2021/09/20 13:25:42 schwarze Exp $ 261d06d6bSBaptiste Daroussin 361d06d6bSBaptiste DaroussinAbout the portable mandoc distribution 461d06d6bSBaptiste Daroussin-------------------------------------- 561d06d6bSBaptiste DaroussinThe mandoc manpage compiler toolset (formerly called "mdocml") 661d06d6bSBaptiste Daroussinis a suite of tools compiling mdoc(7), the roff(7) macro language 761d06d6bSBaptiste Daroussinof choice for BSD manual pages, and man(7), the predominant 861d06d6bSBaptiste Daroussinhistorical language for UNIX manuals. 961d06d6bSBaptiste Daroussin 1061d06d6bSBaptiste DaroussinIt includes a man(1) manual viewer and additional tools. 1161d06d6bSBaptiste DaroussinFor general information, see <http://mandoc.bsd.lv/>. 1261d06d6bSBaptiste Daroussin 1361d06d6bSBaptiste DaroussinIn case you have questions or want to provide feedback, read 1461d06d6bSBaptiste Daroussin<http://mandoc.bsd.lv/contact.html>. Consider subscribing to the 1561d06d6bSBaptiste Daroussindiscuss@ mailing list mentioned on that page. If you intend to 1661d06d6bSBaptiste Daroussinhelp with the development of mandoc, consider subscribing to the 1761d06d6bSBaptiste Daroussintech@ mailing list, too. 1861d06d6bSBaptiste Daroussin 1961d06d6bSBaptiste DaroussinEnjoy using the mandoc toolset! 2061d06d6bSBaptiste Daroussin 21*6d38604fSBaptiste DaroussinIngo Schwarze, Karlsruhe, September 2021 2261d06d6bSBaptiste Daroussin 2361d06d6bSBaptiste Daroussin 2461d06d6bSBaptiste DaroussinInstallation 2561d06d6bSBaptiste Daroussin------------ 2661d06d6bSBaptiste DaroussinBefore manually installing mandoc on your system, please check 2761d06d6bSBaptiste Daroussinwhether the newest version of mandoc is already installed by default 2861d06d6bSBaptiste Daroussinor available via a binary package or a ports system. A list of the 2961d06d6bSBaptiste Daroussinlatest bundled and ported versions of mandoc for various operating 3061d06d6bSBaptiste Daroussinsystems is maintained at <http://mandoc.bsd.lv/ports.html>. 3161d06d6bSBaptiste Daroussin 3261d06d6bSBaptiste DaroussinRegarding how packages and ports are maintained for your operating 3361d06d6bSBaptiste Daroussinsystem, please consult your operating system documentation. 3461d06d6bSBaptiste DaroussinTo install mandoc manually, the following steps are needed: 3561d06d6bSBaptiste Daroussin 3661d06d6bSBaptiste Daroussin1. If you want to build the CGI program, man.cgi(8), too, 3761d06d6bSBaptiste Daroussinrun the command "echo BUILD_CGI=1 >> configure.local". 3861d06d6bSBaptiste DaroussinThen run "cp cgi.h.example cgi.h" and edit cgi.h as desired. 3961d06d6bSBaptiste Daroussin 4061d06d6bSBaptiste Daroussin2. If you also want to build the catman(8) utility, run the 4161d06d6bSBaptiste Daroussincommand "echo BUILD_CATMAN=1 >> configure.local". Note that it 4261d06d6bSBaptiste Daroussinis unlikely to be a drop-in replacement providing the same 4361d06d6bSBaptiste Daroussinfunctionality as your system's "catman", if your operating 4461d06d6bSBaptiste Daroussinsystem contains one. 4561d06d6bSBaptiste Daroussin 4661d06d6bSBaptiste Daroussin3. Define MANPATH_DEFAULT in configure.local 4761d06d6bSBaptiste Daroussinif /usr/share/man:/usr/X11R6/man:/usr/local/man is not appropriate 4861d06d6bSBaptiste Daroussinfor your operating system. 4961d06d6bSBaptiste Daroussin 5061d06d6bSBaptiste Daroussin4. Run "./configure". 5161d06d6bSBaptiste DaroussinThis script attempts autoconfiguration of mandoc for your system. 5261d06d6bSBaptiste DaroussinRead both its standard output and the file "Makefile.local" it 5361d06d6bSBaptiste Daroussingenerates. If anything looks wrong or different from what you 5461d06d6bSBaptiste Daroussinwish, read the file "configure.local.example", create and edit 5561d06d6bSBaptiste Daroussina file "configure.local", and re-run "./configure" until the 5661d06d6bSBaptiste Daroussinresult seems right to you. 5761d06d6bSBaptiste Daroussin 5861d06d6bSBaptiste Daroussin5. Run "make". 5961d06d6bSBaptiste DaroussinAny POSIX-compatible make, in particular both BSD make and GNU make, 6061d06d6bSBaptiste Daroussinshould work. If the build fails, look at "configure.local.example" 6161d06d6bSBaptiste Daroussinand go back to step 2. 6261d06d6bSBaptiste Daroussin 6361d06d6bSBaptiste Daroussin6. Run "make -n install" and check whether everything will be 6461d06d6bSBaptiste Daroussininstalled to the intended places. Otherwise, put some *DIR or *NM* 6561d06d6bSBaptiste Daroussinvariables into "configure.local" and go back to step 4. 6661d06d6bSBaptiste Daroussin 6761d06d6bSBaptiste Daroussin7. Optionally run the regression suite. 68*6d38604fSBaptiste DaroussinBasically, that amounts to "make regress" to do a standard regression 69*6d38604fSBaptiste Daroussinrun, running all tests. For more fine-grained control, 70*6d38604fSBaptiste Daroussinread "./mandoc -l regress/regress.pl.1", 71*6d38604fSBaptiste Daroussinthen run "cd regress && ./regress.pl" with optional arguments. 72*6d38604fSBaptiste DaroussinThe regression suite requires a reasonably modern Perl interpreter. 73*6d38604fSBaptiste DaroussinExamples of systems that are too old to run the regression suite 74*6d38604fSBaptiste Daroussininclude Solaris 9, Solaris 10, and Mac OS X 10.4 Tiger. 75*6d38604fSBaptiste DaroussinOn Solaris 11, the suite does run, but some tests fail; 76*6d38604fSBaptiste Daroussinlook at the BUGS section of that manual page. 7761d06d6bSBaptiste Daroussin 7861d06d6bSBaptiste Daroussin8. Run "sudo make install". If you intend to build a binary 7961d06d6bSBaptiste Daroussinpackage using some kind of fake root mechanism, you may need a 8061d06d6bSBaptiste Daroussincommand like "make DESTDIR=... install". Read the *-install targets 8161d06d6bSBaptiste Daroussinin the "Makefile" to understand how DESTDIR is used. 8261d06d6bSBaptiste Daroussin 8361d06d6bSBaptiste Daroussin9. Run the command "sudo makewhatis" to build mandoc.db(5) databases 8461d06d6bSBaptiste Daroussinin all the directory trees configured in step 3. Whenever installing 8561d06d6bSBaptiste Daroussinnew manual pages, re-run makewhatis(8) to update the databases, or 8661d06d6bSBaptiste Daroussinapropos(1) will not find the new pages. 8761d06d6bSBaptiste Daroussin 8861d06d6bSBaptiste Daroussin10. To set up a man.cgi(8) server, read its manual page. 8961d06d6bSBaptiste Daroussin 9061d06d6bSBaptiste DaroussinNote that a very small number of man(7) pages contain low-level 9161d06d6bSBaptiste Daroussinroff(7) markup that mandoc does not yet understand. On some BSD 9261d06d6bSBaptiste Daroussinsystems using mandoc, third-party software is vetted on whether it 9361d06d6bSBaptiste Daroussinmay be formatted with mandoc. If not, groff(1) is pulled in as a 9461d06d6bSBaptiste Daroussindependency and used to install pre-formatted "catpages" instead of 9561d06d6bSBaptiste Daroussinmanual page sources. This mechanism is used much less frequently 9661d06d6bSBaptiste Daroussinthan in the past. On OpenBSD, only 25 out of about 10000 ports 9761d06d6bSBaptiste Daroussinstill require formatting with groff(1). 9861d06d6bSBaptiste Daroussin 9961d06d6bSBaptiste Daroussin 10061d06d6bSBaptiste DaroussinUnderstanding mandoc dependencies 10161d06d6bSBaptiste Daroussin--------------------------------- 10261d06d6bSBaptiste DaroussinThe following libraries are required: 10361d06d6bSBaptiste Daroussin 10461d06d6bSBaptiste Daroussin1. zlib for decompressing gzipped manual pages. 10561d06d6bSBaptiste Daroussin 10661d06d6bSBaptiste Daroussin2. The fts(3) directory traversion functions. 10761d06d6bSBaptiste DaroussinIf your system does not have them, the bundled compatibility version 10861d06d6bSBaptiste Daroussinwill be used, so you need not worry in that case. But be careful: old 10961d06d6bSBaptiste Daroussinglibc versions of fts(3) were known to be broken on 32bit platforms, 11061d06d6bSBaptiste Daroussinsee <https://sourceware.org/bugzilla/show_bug.cgi?id=11460>. 11161d06d6bSBaptiste DaroussinThat was presumably fixed in glibc-2.23. 11261d06d6bSBaptiste DaroussinIf you run into that problem, set "HAVE_FTS=0" in configure.local. 11361d06d6bSBaptiste Daroussin 11461d06d6bSBaptiste Daroussin3. Marc Espie's ohash(3) library. 11561d06d6bSBaptiste DaroussinIf your system does not have it, the bundled compatibility version 11661d06d6bSBaptiste Daroussinwill be used, so you probably need not worry about it. 11761d06d6bSBaptiste Daroussin 11861d06d6bSBaptiste DaroussinOne of the chief design goals of the mandoc toolbox is to make 11961d06d6bSBaptiste Daroussinsure that nothing related to documentation requires C++. 12061d06d6bSBaptiste DaroussinConsequently, linking mandoc against any kind of C++ program 12161d06d6bSBaptiste Daroussinwould defeat the purpose and is not supported. 12261d06d6bSBaptiste Daroussin 12361d06d6bSBaptiste Daroussin 12461d06d6bSBaptiste DaroussinChecking autoconfiguration quality 12561d06d6bSBaptiste Daroussin---------------------------------- 12661d06d6bSBaptiste DaroussinIf you want to check whether automatic configuration works well 12761d06d6bSBaptiste Daroussinon your platform, consider the following: 12861d06d6bSBaptiste Daroussin 12961d06d6bSBaptiste DaroussinThe mandoc package intentionally does not use GNU autoconf because 13061d06d6bSBaptiste Daroussinwe consider that toolset a blatant example of overengineering that 13161d06d6bSBaptiste Daroussinis obsolete nowadays, since all modern operating systems are now 13261d06d6bSBaptiste Daroussinreasonably close to POSIX and do not need arcane shell magic any 13361d06d6bSBaptiste Daroussinlonger. If your system does need such magic, consider upgrading 13461d06d6bSBaptiste Daroussinto reasonably modern POSIX-compliant tools rather than asking for 13561d06d6bSBaptiste Daroussinautoconf-style workarounds. 13661d06d6bSBaptiste Daroussin 13761d06d6bSBaptiste DaroussinAs far as mandoc is using any features not mandated by ANSI X3.159-1989 13861d06d6bSBaptiste Daroussin("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems 13961d06d6bSBaptiste Daroussindo not have, we intend to provide autoconfiguration tests and 14061d06d6bSBaptiste Daroussincompat_*.c implementations. Please report any that turn out to be 14161d06d6bSBaptiste Daroussinmissing. Note that while we do strive to produce portable code, 14261d06d6bSBaptiste Daroussinwe do not slavishly restrict ourselves to POSIX-only interfaces. 14361d06d6bSBaptiste DaroussinFor improved security and readability, we do use well-designed, 14461d06d6bSBaptiste Daroussinmodern interfaces like reallocarray(3) even if they are still rather 14561d06d6bSBaptiste Daroussinuncommon, of course bundling compat_*.c implementations as needed. 14661d06d6bSBaptiste Daroussin 14761d06d6bSBaptiste DaroussinWhere mandoc is using ANSI C or POSIX features that some systems 14861d06d6bSBaptiste Daroussinstill lack and that compat_*.c implementations can be provided for 14961d06d6bSBaptiste Daroussinwithout too much hassle, we will consider adding them, too, so 15061d06d6bSBaptiste Daroussinplease report whatever is missing on your platform. 15161d06d6bSBaptiste Daroussin 15261d06d6bSBaptiste DaroussinThe following steps can be used to manually check the automatic 15361d06d6bSBaptiste Daroussinconfiguration on your platform: 15461d06d6bSBaptiste Daroussin 15561d06d6bSBaptiste Daroussin1. Run "make distclean". 15661d06d6bSBaptiste Daroussin 15761d06d6bSBaptiste Daroussin2. Run "./configure" 15861d06d6bSBaptiste Daroussin 15961d06d6bSBaptiste Daroussin3. Read the file "config.log". It shows the compiler commands used 16061d06d6bSBaptiste Daroussinto test the libraries installed on your system and the standard 16161d06d6bSBaptiste Daroussinoutput and standard error output these commands produce. Watch out 16261d06d6bSBaptiste Daroussinfor unexpected failures. Those are most likely to happen if headers 16361d06d6bSBaptiste Daroussinor libraries are installed in unusual places or interfaces defined 16461d06d6bSBaptiste Daroussinin unusual headers. You can also look at the file "config.h" and 16561d06d6bSBaptiste Daroussincheck that no "#define HAVE_*" differ from your expectations. 166