* mdocml: first cut at updating for the next release
@ 2014-12-09 9:19 schwarze
0 siblings, 0 replies; only message in thread
From: schwarze @ 2014-12-09 9:19 UTC (permalink / raw)
To: source
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=utf-8, Size: 5552 bytes --]
Log Message:
-----------
first cut at updating for the next release
Modified Files:
--------------
mdocml:
INSTALL
Revision Data
-------------
Index: INSTALL
===================================================================
RCS file: /home/cvs/mdocml/mdocml/INSTALL,v
retrieving revision 1.6
retrieving revision 1.7
diff -LINSTALL -LINSTALL -u -p -r1.6 -r1.7
--- INSTALL
+++ INSTALL
@@ -5,9 +5,8 @@ About mdocml, the portable mandoc distri
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.
-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).
+Since the present version 1.13.2, it includes a man(1) manual viewer
+in addition to the apropos(1) manual page search tool.
For general information, see <http://mdocml.bsd.lv/>.
In this document, we describe the installation and deployment of
@@ -22,7 +21,7 @@ tech@ mailing list, too.
Enjoy using the mandoc toolset!
-Ingo Schwarze, Karlsruhe, August 2014
+Ingo Schwarze, Karlsruhe, December 2014
Installation
@@ -59,8 +58,8 @@ should work. If the build fails, look a
and go back to step 2.
4. Run "make -n install" and check whether everything will be
-installed to the intended places. Otherwise, put some *DIR variables
-into "configure.local" and go back to step 2.
+installed to the intended places. Otherwise, put some *DIR or *NM*
+variables into "configure.local" and go back to step 2.
5. Run "sudo make install". If you intend to build a binary
package using some kind of fake root mechanism, you may need a
@@ -70,14 +69,14 @@ in the "Makefile" to understand how DEST
6. To set up a man.cgi(8) server, read its manual page.
7. To use mandoc(1) as your man(1) formatter, read the "Deployment"
-section below.
+sections below.
Understanding mandoc dependencies
---------------------------------
-The mandoc(1), preconv(1), and demandoc(1) utilities have no external
-dependencies. However, makewhatis(8) and apropos(1) depend on the
-following software:
+The mandoc(1) and demandoc(1) utilities have no external dependencies.
+However, makewhatis(8), apropos(1), and man(1) depend on the following
+software:
1. The SQLite database system, see <http://sqlite.org/>.
The recommended version of SQLite is 3.8.4.3 or newer. The mandoc
@@ -89,14 +88,14 @@ fails due to the missing sqlite3_errstr(
problems, apropos(1) is fully usable with SQLite 3.7.5. Versions
older than 3.7.5 may or may not work, they have not been tested.
-1.2. The fts(3) directory traversion functions.
+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: the
glibc version of fts(3) is known to be broken on 32bit platforms,
see <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>.
If you run into that problem, set "HAVE_FTS=0" in configure.local.
-1.3. Marc Espie's ohash(3) library.
+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.
@@ -145,11 +144,36 @@ in unusual headers. You can also look a
check that no "#define HAVE_*" differ from your expectations.
-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!
+Deployment using the integrated man(1) viewer
+---------------------------------------------
+This mode of deployment requires database support. In case of
+doubt, look at the section "user settings related to database
+support" in the file configure.local.example.
+
+Deployment requires the following steps:
+
+1. Build and install mandoc as described above in steps 2 to 5
+below "Installation".
+
+2. If you system uses manpath(1), make sure it is configured
+correctly, in particular, it returns all directory trees where
+manual pages are installed. If your system uses man.conf(5), make
+sure it contains a "_whatdb" for each directory tree, and the order
+of these lines meets your wishes.
+
+3. Run the command "sudo makewhatis" to build mandoc.db(5) databases
+in all the directory trees configured in step 2.
+
+At this point, your new man(1), apropos(1), and whatis(1) should work.
+Otherwise, please look at <http://mdocml.bsd.lv/contact.html>, both
+for help and to have these instructions improved.
+
+
+Deployment using your system's native man(1) viewer
+---------------------------------------------------
+This mode of deployment does not require database support,
+so it works even if you don't have SQLite3.
+
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.
@@ -173,6 +197,7 @@ 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
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2014-12-09 9:19 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-12-09 9:19 mdocml: first cut at updating for the next release schwarze
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).