From: schwarze@mdocml.bsd.lv
To: source@mdocml.bsd.lv
Subject: mdocml: provide some instructions for manual installation
Date: Fri, 8 Aug 2014 12:45:40 -0400 (EDT) [thread overview]
Message-ID: <201408081645.s78Gjejd009077@krisdoz.my.domain> (raw)
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
reply other threads:[~2014-08-08 16:45 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=201408081645.s78Gjejd009077@krisdoz.my.domain \
--to=schwarze@mdocml.bsd.lv \
--cc=source@mdocml.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).