=================================================================== RCS file: /cvs/mandoc/INSTALL,v retrieving revision 1.1 retrieving revision 1.3.2.1 diff -u -p -r1.1 -r1.3.2.1 --- mandoc/INSTALL 2014/08/08 16:45:39 1.1 +++ mandoc/INSTALL 2014/08/14 20:43:22 1.3.2.1 @@ -1,70 +1,89 @@ -$Id: INSTALL,v 1.1 2014/08/08 16:45:39 schwarze Exp $ +$Id: INSTALL,v 1.3.2.1 2014/08/14 20:43:22 schwarze Exp $ -Installing mdocml, the portable mandoc distribution ---------------------------------------------------- - +About mdocml, the portable mandoc distribution +---------------------------------------------- The mandoc manpage compiler toolset 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. -For general information, see: http://mdocml.bsd.lv/ +The toolset does not yet implement man(1); that is only scheduled +for the next release, 1.13.2. It can, however, already serve to +translate source manpages to the output displayed by man(1). +For general information, see . +In this document, we describe the installation and deployment of +mandoc(1), first as a simple, standalone formatter, and then as part of +the man(1) system. + +In case you have questions or want to provide feedback, read +. 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 + + +Installation +------------ Before manually installing mandoc on your system, please check 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 latest bundled and ported versions of mandoc for various operating -systems is maintained at: http://mdocml.bsd.lv/ports.html +systems is maintained at . -If mandoc is installed, you can check the version by typing: mandoc -V -The version contained in this distribution tarball is listed near -the beginning of the file "Makefile". Regarding how packages and -ports are maintained for your operating system, please consult your -operating system documentation. +If mandoc is installed, you can check the version by running "mandoc -V". +The version contained in this distribution tarball is 1.12.4. +This is not the newest version available, you can also get 1.13.1. +Installing 1.12.4 only makes sense if all of the following conditions +hold for you: + - You need apropos(1) and makewhatis(8) functionality. + - You do not need the man.cgi(8) web frontend. + - You do have the Berkeley database library, version 1.85. + - You lack at least one of the following: the SQLite3 database + library and/or the fts(3) file hierarchy traversal functions. + +Regarding how packages and ports are maintained for your operating +system, please consult your operating system documentation. To install mandoc manually, the following steps are needed: -1. Decide whether you want to build just the basic tools mandoc(1), -preconv(1) and demandoc(1) or whether you also want to build the -database tools apropos(1) and makewhatis(8). For the latter, a -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. +1. Decide whether you want to build the base tools mandoc(1), +preconv(1) and demandoc(1) only or whether you also want to build the +database tools apropos(1) and makewhatis(8). For the latter, +the Berkeley database system, version 1.85, is required. +It is installed by default on BSD systems and available as an +optional software package on other systems. -2. If you choose to build the database tools, too, decide whether -you also want to build the CGI program, man.cgi(8). - -3. Read the beginning of the file "Makefile" from "USER SETTINGS" +2. Read the beginning of the file "Makefile" from "USER SETTINGS" to "END OF USER SETTINGS" and edit it as required. In particular, disable "BUILD_TARGETS += db-build" if you do not want database -support or enable "BUILD_TARGETS += cgi-build" if you do want -the CGI program. +support. -4. Run the command "make". No separate "./configure" or "make -depend" steps are needed. The former is run automatically by "make". -The latter is a maintainer target. If you merely want to build the -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. +3. Run "make". No separate "./configure" or "make depend" steps +are needed. The former is run automatically by "make". The latter +is a maintainer target. If you merely want to build the 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, should work. -5. Run the command "make -n install" and check whether everything -will be installed to the intended places. Otherwise, edit the *DIR -variables in the Makefile until it is. +4. Run "make -n install" and check whether everything will be +installed to the intended places. Otherwise, edit the *DIR variables +in the Makefile until it is. -6. Run "sudo make install". Instead, if you intend to build a binary +5. Run "sudo make install". If you intend to build a binary package using some kind of fake root mechanism, you may need a command like "make DESTDIR=... install". Read the *-install targets in the "Makefile" to understand how DESTDIR is used. +6. To use mandoc(1) as your man(1) formatter, read the "Deployment" +section below. + +Checking autoconfiguration quality +---------------------------------- If you want to check whether automatic configuration works well on your platform, consider the following: @@ -108,12 +127,44 @@ check that no expected "#define HAVE_*" lines are miss 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 +Deployment +---------- +If you want to integrate the mandoc(1) tools with your existing +man(1) system as a formatter, then contact us first: on systems without +mandoc(1) as the default, you may have your work cut out for you! +Usually, you can have your default installation and mandoc(1) work right +alongside each other by using user-specific versions of the files +mentioned below. -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. +0. Back up each file you want to change! -Enjoy using the mandoc toolset! -Ingo Schwarze, Karlsruhe, August 2014 +1. First see whether your system has "/etc/man.conf" or "/etc/manpath.conf" +(if it has neither, but man(1) is functional, then let us know) or, +if running as your own user, a per-user override file. In either +case, find where man(1) is executing nroff(1) or groff(1) to format +manuals. Replace these calls with mandoc(1). + +2. Then make sure that man(1) isn't running preprocessors, so you may +need to replace tbl(1), eqn(1), and similar references with cat(1). +Some man(1) implementations, like that on Mac OSX, let you run "man -d" +to see how the formatter is invoked. Use this to test your changes. On +Mac OS X, for instance, man(1) will prepend all files with ".ll" and +".nr" to set the terminal size, so you need to pass "tail -n+2 | +mandoc(1)" to disregard them. + +3. Finally, make sure that mandoc(1) is actually being invoked instead +of cached pages being pulled up. You can usually do this by commenting +out NOCACHE or similar. + +mandoc(1) still has a long way to go in understanding non-trivial +low-level roff(7) markup embedded in some man(7) pages. On the BSD +systems using mandoc(1), third-party software is generally vetted +on whether it may be formatted with mandoc(1). If not, groff(1) +is pulled in as a dependency and used to install a pre-formatted +"catpage" intead of directly as manual page source. + +For more background on switching operating systems to use mandoc(1) +instead of groff(1) to format manuals, see the two BSDCan presentations +by Ingo Schwarze: + +