From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from krisdoz.my.domain (schwarze@localhost [127.0.0.1]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id s78Gje6B005712 for ; Fri, 8 Aug 2014 12:45:40 -0400 (EDT) Received: (from schwarze@localhost) by krisdoz.my.domain (8.14.5/8.14.3/Submit) id s78Gjejd009077; Fri, 8 Aug 2014 12:45:40 -0400 (EDT) Date: Fri, 8 Aug 2014 12:45:40 -0400 (EDT) Message-Id: <201408081645.s78Gjejd009077@krisdoz.my.domain> X-Mailinglist: mdocml-source Reply-To: source@mdocml.bsd.lv MIME-Version: 1.0 From: schwarze@mdocml.bsd.lv To: source@mdocml.bsd.lv Subject: mdocml: provide some instructions for manual installation X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Log Message: ----------- provide some instructions for manual installation Added Files: ----------- mdocml: INSTALL Revision Data ------------- --- /dev/null +++ INSTALL @@ -0,0 +1,119 @@ +$Id: INSTALL,v 1.1 2014/08/08 16:45:39 schwarze Exp $ + +Installing 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/ + +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 + +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. + + +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. + +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" +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. + +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. + +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. + +6. Run "sudo make install". Instead, 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. + + +If you want to check whether automatic configuration works well +on your platform, consider the following: + +The mandoc package intentionally does not use GNU autoconf because +we consider that toolset a blatant example of overengineering that +is obsolete nowadays, since all modern operating systems are now +reasonably close to POSIX and do not need arcane shell magic any +longer. If your system does need such magic, consider upgrading +to reasonably modern POSIX-compliant tools rather than asking for +autoconf-style workarounds. + +As far as mandoc is using any features not mandated by ANSI X3.159-1989 +("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems +do not have, we intend to provide autoconfiguration tests and +compat_*.c implementations. Please report any that turn out to be +missing. Note that while we do strive to produce portable code, +we do not slavishly restrict ourselves to POSIX-only interfaces. +For improved security and readability, we do use well-designed, +modern interfaces like reallocarray(3) even if they are still rather +uncommon, of course bundling compat_*.c implementations as needed. + +Where mandoc is using ANSI C or POSIX features that some systems +still lack and that compat_*.c implementations can be provided for +without too much hassle, we will consider adding them, too, so +please report whatever is missing on your platform. + +The following steps can be used to manually check the automatic +configuration on your platform: + +1. Run "make clean". + +2. Run "make config.h" + +3. Read the file "config.log". It shows the compiler commands used +to test the libraries installed on your system and the standard +output and standard error output these commands produce. Watch out +for unexpected failures. Those are most likely to happen if headers +or libraries are installed in unusual places or interfaces defined +in unusual headers. You can also look at the file "config.h" and +check that no expected "#define HAVE_*" lines are missing. The +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 -- To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv