Return to INSTALL CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.1, 2014/08/08 16:45:39 | version 1.21, 2018/07/31 10:18:15 | ||
---|---|---|---|
|
|
||
$Id$ | $Id$ | ||
Installing mdocml, the portable mandoc distribution | About the portable mandoc distribution | ||
--------------------------------------------------- | -------------------------------------- | ||
The mandoc manpage compiler toolset (formerly called "mdocml") | |||
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 mandoc manpage compiler toolset is a suite of tools compiling | It includes a man(1) manual viewer and additional tools. | ||
mdoc(7), the roff(7) macro language of choice for BSD manual pages, | For general information, see <http://mandoc.bsd.lv/>. | ||
and man(7), the predominant historical language for UNIX manuals. | |||
For general information, see: http://mdocml.bsd.lv/ | |||
In case you have questions or want to provide feedback, read | |||
<http://mandoc.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 2018 | |||
Installation | |||
------------ | |||
Before manually installing mandoc on your system, please check | Before manually installing mandoc on your system, please check | ||
whether the newest version of mandoc is already installed by default | 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 | or available via a binary package or a ports system. A list of the | ||
latest bundled and ported versions of mandoc for various operating | latest bundled and ported versions of mandoc for various operating | ||
systems is maintained at: http://mdocml.bsd.lv/ports.html | systems is maintained at <http://mandoc.bsd.lv/ports.html>. | ||
If mandoc is installed, you can check the version by typing: mandoc -V | Regarding how packages and ports are maintained for your operating | ||
The version contained in this distribution tarball is listed near | system, please consult your operating system documentation. | ||
the beginning of the file "Makefile". Regarding how packages and | To install mandoc manually, the following steps are needed: | ||
ports are maintained for your operating system, please consult your | |||
operating system documentation. | |||
1. If you want to build the CGI program, man.cgi(8), too, | |||
run the command "echo BUILD_CGI=1 >> configure.local". | |||
Then run "cp cgi.h.example cgi.h" and edit cgi.h as desired. | |||
To install mandoc manually, the following steps are needed: | 2. If you also want to build the catman(8) utility, run the | ||
command "echo BUILD_CATMAN=1 >> configure.local". Note that it | |||
is unlikely to be a drop-in replacement providing the same | |||
functionality as your system's "catman", if your operating | |||
system contains one. | |||
1. Decide whether you want to build just the basic tools mandoc(1), | 3. Define MANPATH_DEFAULT in configure.local | ||
preconv(1) and demandoc(1) or whether you also want to build the | if /usr/share/man:/usr/X11R6/man:/usr/local/man is not appropriate | ||
database tools apropos(1) and makewhatis(8). For the latter, a | for your operating system. | ||
working installation of SQLite is required, see: http://sqlite.org/ | |||
The recommended version of SQLite is 3.8.4.3 or newer. The mandoc | |||
toolset is known to work with version 3.7.5 or newer. Versions | |||
older than 3.8.3 may not achieve full performance due to the | |||
missing SQLITE_DETERMINISTIC optimization flag. Versions older | |||
than 3.8.0 may not show full error information if opening a database | |||
fails due to the missing sqlite3_errstr() API. Both are very minor | |||
problems, apropos(1) is fully usable with SQLite 3.7.5. | |||
The database tools also require Marc Espie's ohash(3) library; | |||
if your system does not have it, the bundled compatibility version | |||
will be used, so you probably need not worry about it. | |||
2. If you choose to build the database tools, too, decide whether | 4. Run "./configure". | ||
you also want to build the CGI program, man.cgi(8). | This script attempts autoconfiguration of mandoc for your system. | ||
Read both its standard output and the file "Makefile.local" it | |||
generates. If anything looks wrong or different from what you | |||
wish, read the file "configure.local.example", create and edit | |||
a file "configure.local", and re-run "./configure" until the | |||
result seems right to you. | |||
On Solaris 10 and earlier, you may have to run "ksh ./configure" | |||
because the native /bin/sh lacks some POSIX features. | |||
3. Read the beginning of the file "Makefile" from "USER SETTINGS" | 5. Run "make". | ||
to "END OF USER SETTINGS" and edit it as required. In particular, | Any POSIX-compatible make, in particular both BSD make and GNU make, | ||
disable "BUILD_TARGETS += db-build" if you do not want database | should work. If the build fails, look at "configure.local.example" | ||
support or enable "BUILD_TARGETS += cgi-build" if you do want | and go back to step 2. | ||
the CGI program. | |||
4. Run the command "make". No separate "./configure" or "make | 6. Run "make -n install" and check whether everything will be | ||
depend" steps are needed. The former is run automatically by "make". | installed to the intended places. Otherwise, put some *DIR or *NM* | ||
The latter is a maintainer target. If you merely want to build the | variables into "configure.local" and go back to step 4. | ||
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, | |||
is supposed to work. | |||
5. Run the command "make -n install" and check whether everything | 7. Optionally run the regression suite. | ||
will be installed to the intended places. Otherwise, edit the *DIR | Basically, that amounts to "cd regress && ./regress.pl". | ||
variables in the Makefile until it is. | But you should probably look at "./mandoc -l regress/regress.pl.1" | ||
first. | |||
6. Run "sudo make install". Instead, if you intend to build a binary | 8. Run "sudo make install". If you intend to build a binary | ||
package using some kind of fake root mechanism, you may need a | package using some kind of fake root mechanism, you may need a | ||
command like "make DESTDIR=... install". Read the *-install targets | command like "make DESTDIR=... install". Read the *-install targets | ||
in the "Makefile" to understand how DESTDIR is used. | in the "Makefile" to understand how DESTDIR is used. | ||
9. Run the command "sudo makewhatis" to build mandoc.db(5) databases | |||
in all the directory trees configured in step 3. Whenever installing | |||
new manual pages, re-run makewhatis(8) to update the databases, or | |||
apropos(1) will not find the new pages. | |||
10. To set up a man.cgi(8) server, read its manual page. | |||
Note that a very small number of man(7) pages contain low-level | |||
roff(7) markup that mandoc does not yet understand. On some BSD | |||
systems using mandoc, third-party software is vetted on whether it | |||
may be formatted with mandoc. If not, groff(1) is pulled in as a | |||
dependency and used to install pre-formatted "catpages" instead of | |||
manual page sources. This mechanism is used much less frequently | |||
than in the past. On OpenBSD, only 25 out of about 10000 ports | |||
still require formatting with groff(1). | |||
Understanding mandoc dependencies | |||
--------------------------------- | |||
The following libraries are required: | |||
1. zlib for decompressing gzipped manual pages. | |||
2. The fts(3) directory traversion functions. | |||
If your system does not have them, the bundled compatibility version | |||
will be used, so you need not worry in that case. But be careful: old | |||
glibc versions of fts(3) were known to be broken on 32bit platforms, | |||
see <https://sourceware.org/bugzilla/show_bug.cgi?id=11460>. | |||
That was presumably fixed in glibc-2.23. | |||
If you run into that problem, set "HAVE_FTS=0" in configure.local. | |||
3. Marc Espie's ohash(3) library. | |||
If your system does not have it, the bundled compatibility version | |||
will be used, so you probably need not worry about it. | |||
One of the chief design goals of the mandoc toolbox is to make | |||
sure that nothing related to documentation requires C++. | |||
Consequently, linking mandoc against any kind of C++ program | |||
would defeat the purpose and is not supported. | |||
Checking autoconfiguration quality | |||
---------------------------------- | |||
If you want to check whether automatic configuration works well | If you want to check whether automatic configuration works well | ||
on your platform, consider the following: | on your platform, consider the following: | ||
|
|
||
The following steps can be used to manually check the automatic | The following steps can be used to manually check the automatic | ||
configuration on your platform: | configuration on your platform: | ||
1. Run "make clean". | 1. Run "make distclean". | ||
2. Run "make config.h" | 2. Run "./configure" | ||
3. Read the file "config.log". It shows the compiler commands used | 3. Read the file "config.log". It shows the compiler commands used | ||
to test the libraries installed on your system and the standard | to test the libraries installed on your system and the standard | ||
|
|
||
for unexpected failures. Those are most likely to happen if headers | for unexpected failures. Those are most likely to happen if headers | ||
or libraries are installed in unusual places or interfaces defined | or libraries are installed in unusual places or interfaces defined | ||
in unusual headers. You can also look at the file "config.h" and | in unusual headers. You can also look at the file "config.h" and | ||
check that no expected "#define HAVE_*" lines are missing. The | check that no "#define HAVE_*" differ from your expectations. | ||
list of tests run can be found in the file "configure". | |||
In case you have questions or want to provide feedback, look at: | |||
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 |