Removed need for superfluous `os' value in overstep calculation (thanks Ingo Schwarze).

[mandoc.git] / mandoc.1

diff --git a/mandoc.1 b/mandoc.1
index 318f0798b189dfc08489bcf1ae2291c51c1d7e03..431be5a0ada9bdba403390912fca8f1c5573c317 100644 (file)
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.1,v 1.38 2009/09/21 13:44:56 kristaps Exp $
+.\"    $Id: mandoc.1,v 1.43 2009/10/15 02:42:53 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: September 21 2009 $
+.Dd $Mdocdate: October 15 2009 $
 .Dt MANDOC 1
 .Os
 .
@@ -54,7 +54,7 @@ Input format.  See
 for available formats.  Defaults to
 .Fl m Ns Ar andoc .
 .
-.It Fl o Ns Ar format
+.It Fl o Ns Ar option...
 Comma-separated output options.  See
 .Sx Output Options
 for details.
@@ -260,13 +260,31 @@ The file
 .Ar style.css
 is used for an external style-sheet.  This must be a valid absolute or
 relative URI.
-.It Fl o Ns Ar base=http://base/
-The URL
-.Ar http://base/
-is used as a base URL for all relative links.  This is useful when
-linking between documents via the
+.It Fl o Ns Ar includes=fmt
+The string
+.Ar fmt ,
+for example, 
+.Ar ../src/%I.html ,
+is used as a template for linked header files (usually via the
+.Sq \&In
+macro).  Instances of
+.Sq \&%I
+are replaced with the include filename.  The default is not to present a
+hyperlink.
+.It Fl o Ns Ar man=fmt
+The string
+.Ar fmt ,
+for example, 
+.Ar ../html%S/%N.%S.html ,
+is used as a template for linked manuals (usually via the
 .Sq \&Xr
-macro.
+macro).  Instances of
+.Sq \&%N
+and
+.Sq %S
+are replaced with the linked manual's name and section, respectively.
+If no section is included, section 1 is assumed.  The default is not to
+present a hyperlink.
 .El
 .
 .Sh EXAMPLES
@@ -277,11 +295,11 @@ To page manuals to the terminal:
 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 .
 .Pp
-To produce HTML manuals with 
-.Pa http://localhost/
-as the base URI:
+To produce HTML manuals with
+.Ar style.css
+as the style-sheet:
 .Pp
-.D1 % mandoc \-Thtml -obase=http://localhost/ mdoc.7 > mdoc.7.html
+.D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html
 .Pp
 To check over a large set of manuals:
 .
@@ -356,14 +374,43 @@ retains spaces.
 .It
 Sentences are unilaterally monospaced.
 .El
+.
+.Ss HTML output
+.Bl -bullet -compact
+.It
+The
+.Xr mdoc 7
+.Sq \&Bl \-hang
+and
+.Sq \&Bl \-tag
+list types render similarly (no break following overreached left-hand
+side) due to the expressive constraints of HTML.
+.
+.It
+The
+.Xr man 7
+.Sq IP
+and
+.Sq TP
+lists render similarly.
+.El
 .\" SECTION
 .Sh SEE ALSO
 .Xr mandoc_char 7 ,
 .Xr mdoc 7 ,
 .Xr man 7
-.\" SECTION
+.
 .Sh AUTHORS
 The
 .Nm
 utility was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .
+.
+.Sh CAVEATS
+In
+.Fl T Ns Ar html ,
+the maximum size of an element attribute is determined by
+.Dv BUFSIZ ,
+which is usually 1024 bytes.  Be aware of this when setting long link
+formats with
+.Fl o Ns Ar man=fmt .