[BACK]Return to INSTALL CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/INSTALL between version 1.5 and 1.9

version 1.5, 2014/08/18 13:27:47 version 1.9, 2014/12/11 07:44:46
Line 5  About mdocml, the portable mandoc distribution
Line 5  About mdocml, the portable mandoc distribution
 The mandoc manpage compiler toolset is a suite of tools compiling  The mandoc manpage compiler toolset is a suite of tools compiling
 mdoc(7), the roff(7) macro language of choice for BSD manual pages,  mdoc(7), the roff(7) macro language of choice for BSD manual pages,
 and man(7), the predominant historical language for UNIX manuals.  and man(7), the predominant historical language for UNIX manuals.
 The toolset does not yet implement man(1); that is only scheduled  Since the present version 1.13.2, it includes a man(1) manual viewer
 for the next release, 1.13.2.  It can, however, already serve to  in addition to the apropos(1) manual page search tool.
 translate source manpages to the output displayed by man(1).  
 For general information, see <http://mdocml.bsd.lv/>.  For general information, see <http://mdocml.bsd.lv/>.
   
 In this document, we describe the installation and deployment of  In this document, we describe the installation and deployment of
Line 22  tech@ mailing list, too.
Line 21  tech@ mailing list, too.
   
 Enjoy using the mandoc toolset!  Enjoy using the mandoc toolset!
   
 Ingo Schwarze, Karlsruhe, August 2014  Ingo Schwarze, Karlsruhe, December 2014
   
   
 Installation  Installation
Line 59  should work.  If the build fails, look at "configure.l
Line 58  should work.  If the build fails, look at "configure.l
 and go back to step 2.  and go back to step 2.
   
 4. Run "make -n install" and check whether everything will be  4. Run "make -n install" and check whether everything will be
 installed to the intended places.  Otherwise, put some *DIR variables  installed to the intended places.  Otherwise, put some *DIR or *NM*
 into "configure.local" and go back to step 2.  variables into "configure.local" and go back to step 2.
   
 5. Run "sudo make install".  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  package using some kind of fake root mechanism, you may need a
Line 70  in the "Makefile" to understand how DESTDIR is used.
Line 69  in the "Makefile" to understand how DESTDIR is used.
 6. To set up a man.cgi(8) server, read its manual page.  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"  7. To use mandoc(1) as your man(1) formatter, read the "Deployment"
 section below.  sections below.
   
   
 Understanding mandoc dependencies  Understanding mandoc dependencies
 ---------------------------------  ---------------------------------
 The mandoc(1), preconv(1), and demandoc(1) utilities have no external  The mandoc(1) and demandoc(1) utilities have no external dependencies.
 dependencies.  However, makewhatis(8) and apropos(1) depend on the  However, makewhatis(8), apropos(1), and man(1) depend on the following
 following software:  software:
   
 1. The SQLite database system, see <http://sqlite.org/>.  1. The SQLite database system, see <http://sqlite.org/>.
 The recommended version of SQLite is 3.8.4.3 or newer.  The mandoc  The recommended version of SQLite is 3.8.4.3 or newer.  The mandoc
Line 89  fails due to the missing sqlite3_errstr() API.  Both a
Line 88  fails due to the missing sqlite3_errstr() API.  Both a
 problems, apropos(1) is fully usable with SQLite 3.7.5.  Versions  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.  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  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  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,  glibc version of fts(3) is known to be broken on 32bit platforms,
 see <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>.  see <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>.
 If you run into that problem, set "HAVE_FTS=0" in configure.local.  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  If your system does not have it, the bundled compatibility version
 will be used, so you probably need not worry about it.  will be used, so you probably need not worry about it.
   
Line 145  in unusual headers.  You can also look at the file "co
Line 144  in unusual headers.  You can also look at the file "co
 check that no "#define HAVE_*" differ from your expectations.  check that no "#define HAVE_*" differ from your expectations.
   
   
 Deployment  Deployment using the integrated man(1) viewer
 ----------  ---------------------------------------------
 If you want to integrate the mandoc(1) tools with your existing  This mode of deployment requires database support.  In case of
 man(1) system as a formatter, then contact us first: on systems without  doubt, look at the section "user settings related to database
 mandoc(1) as the default, you may have your work cut out for you!  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 your 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" line 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.
   
   Whenever installing new manual pages, re-run makewhatis(8) to update
   the databases, or man(1) will not find the new pages.
   
   
   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  Usually, you can have your default installation and mandoc(1) work right
 alongside each other by using user-specific versions of the files  alongside each other by using user-specific versions of the files
 mentioned below.  mentioned below.
Line 174  mandoc(1)" to disregard them.
Line 201  mandoc(1)" to disregard them.
 of cached pages being pulled up.  You can usually do this by commenting  of cached pages being pulled up.  You can usually do this by commenting
 out NOCACHE or similar.  out NOCACHE or similar.
   
   
 mandoc(1) still has a long way to go in understanding non-trivial  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  low-level roff(7) markup embedded in some man(7) pages.  On the BSD
 systems using mandoc(1), third-party software is generally vetted  systems using mandoc(1), third-party software is generally vetted
 on whether it may be formatted with mandoc(1).  If not, groff(1)  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  is pulled in as a dependency and used to install a pre-formatted
 "catpage" intead of directly as manual page source.  "catpage" instead of directly as manual page source.
   
 For more background on switching operating systems to use mandoc(1)  For more background on switching operating systems to use mandoc(1)
 instead of groff(1) to format manuals, see the two BSDCan presentations  instead of groff(1) to format manuals, see the BSDCan and EuroBSDCon
 by Ingo Schwarze:  presentations by Ingo Schwarze:
 <http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html>  <http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html>
 <http://www.openbsd.org/papers/bsdcan14-mandoc.pdf>  <http://www.openbsd.org/papers/bsdcan14-mandoc.pdf>
   <http://www.openbsd.org/papers/eurobsdcon2014-mandoc-paper.pdf>

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.9

CVSweb