Fix the column numbers associated with in_line_argn() macros;

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 44a0717aa63d81830819bb9fe85290303142139e..a4aa1c70b0ab9e20945fecf756da55feda96a75b 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.227 2014/02/16 14:26:55 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.231 2014/07/02 03:48:07 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: February 16 2014 $
+.Dd $Mdocdate: July 2 2014 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -135,6 +135,8 @@ file for a utility
 The
 \&.Nm
 utility processes files ...
 The
 \&.Nm
 utility processes files ...

+\&.\e\(dq .Sh CONTEXT
+\&.\e\(dq For section 9 functions only.

 \&.\e\(dq .Sh IMPLEMENTATION NOTES
 \&.\e\(dq Not used in OpenBSD.
 \&.\e\(dq .Sh RETURN VALUES
 \&.\e\(dq .Sh IMPLEMENTATION NOTES
 \&.\e\(dq Not used in OpenBSD.
 \&.\e\(dq .Sh RETURN VALUES


@@ -318,6 +320,9 @@ macro followed by a non-standard section name, and each having
 several subsections, like in the present
 .Nm
 manual.
 several subsections, like in the present
 .Nm
 manual.

+.It Em CONTEXT
+This section lists the contexts in which functions can be called in section 9.
+The contexts are autoconf, process, or interrupt.

 .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side
 .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side


@@ -508,7 +513,6 @@ in the alphabetical
 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
 .It Sx \&Ad Ta memory address (>0 arguments)
 .It Sx \&Ms Ta mathematical symbol (>0 arguments)
 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
 .It Sx \&Ad Ta memory address (>0 arguments)
 .It Sx \&Ms Ta mathematical symbol (>0 arguments)

-.It Sx \&Tn Ta tradename (>0 arguments)

 .El
 .Ss Physical markup
 .Bl -column "Brq, Bro, Brc" description
 .El
 .Ss Physical markup
 .Bl -column "Brq, Bro, Brc" description


@@ -536,7 +540,6 @@ in the alphabetical
 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
 .It Sx \&St Ta reference to a standards document (one argument)
 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
 .It Sx \&St Ta reference to a standards document (one argument)

-.It Sx \&Ux Ta Ux

 .It Sx \&At Ta At
 .It Sx \&Bx Ta Bx
 .It Sx \&Bsx Ta Bsx
 .It Sx \&At Ta At
 .It Sx \&Bx Ta Bx
 .It Sx \&Bsx Ta Bsx


@@ -747,9 +750,8 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Bc
 Close a
 .Sx \&Bo
 .Ss \&Bc
 Close a
 .Sx \&Bo


@@ -1113,10 +1115,10 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Bt
 .Ss \&Bt

+Supported only for compatibility, do not use this in new manuals.

 Prints
 .Dq is currently in beta test.
 .Ss \&Bx
 Prints
 .Dq is currently in beta test.
 .Ss \&Bx


@@ -1136,9 +1138,8 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Cd
 Kernel configuration declaration.
 This denotes strings accepted by
 .Ss \&Cd
 Kernel configuration declaration.
 This denotes strings accepted by


@@ -1436,9 +1437,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
 .Sx \&Bx ,
 .Sx \&Fx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Ec
 Close a scope started by
 .Sx \&Eo .
 .Ss \&Ec
 Close a scope started by
 .Sx \&Eo .


@@ -1487,8 +1487,14 @@ See also
 and
 .Sx \&Sy .
 .Ss \&En
 and
 .Sx \&Sy .
 .Ss \&En

-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
+This macro is obsolete.
+Use
+.Sx \&Eo
+or any of the other enclosure macros.
+.Pp
+It encloses its argument in the delimiters specified by the last
+.Sx \&Es
+macro.

 .Ss \&Eo
 An arbitrary enclosure.
 Its syntax is as follows:
 .Ss \&Eo
 An arbitrary enclosure.
 Its syntax is as follows:


@@ -1514,7 +1520,14 @@ See also
 .Sx \&Dv
 for general constants.
 .Ss \&Es
 .Sx \&Dv
 for general constants.
 .Ss \&Es

-This macro is obsolete and not implemented.
+This macro is obsolete.
+Use
+.Sx \&Eo
+or any of the other enclosure macros.
+.Pp
+It takes two arguments, defining the delimiters to be used by subsequent
+.Sx \&En
+macros.

 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .


@@ -1694,13 +1707,10 @@ See also
 and
 .Sx \&Ft .
 .Ss \&Fr
 and
 .Sx \&Ft .
 .Ss \&Fr

-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
+This macro is obsolete.
+No replacement markup is needed.

 .Pp
 .Pp

-It was used to show function return values.
-The syntax was:
-.Pp
-.Dl Pf . Sx \&Fr Ar value
+It was used to show numerical function return values in an italic font.

 .Ss \&Ft
 A function type.
 Its syntax is as follows:
 .Ss \&Ft
 A function type.
 Its syntax is as follows:


@@ -1739,9 +1749,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Nx ,
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Nx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Hf
 This macro is not implemented in
 .Xr mandoc 1 .
 .Ss \&Hf
 This macro is not implemented in
 .Xr mandoc 1 .


@@ -2059,9 +2068,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,

-.Sx \&Ox ,

 and
 and

-.Sx \&Ux .
+.Sx \&Ox .

 .Ss \&Oc
 Close multi-line
 .Sx \&Oo
 .Ss \&Oc
 Close multi-line
 .Sx \&Oo


@@ -2115,8 +2123,12 @@ See also
 and
 .Sx \&Dt .
 .Ss \&Ot
 and
 .Sx \&Dt .
 .Ss \&Ot

-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
+This macro is obsolete.
+Use
+.Sx \&Ft
+instead; with
+.Xr mandoc 1 ,
+both have the same effect.

 .Pp
 Historical
 .Nm
 .Pp
 Historical
 .Nm


@@ -2138,9 +2150,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,

-.Sx \&Nx ,

 and
 and

-.Sx \&Ux .
+.Sx \&Nx .

 .Ss \&Pa
 An absolute or relative file system path, or a file or directory name.
 If an argument is not provided, the character
 .Ss \&Pa
 An absolute or relative file system path, or a file or directory name.
 If an argument is not provided, the character


@@ -2628,36 +2639,19 @@ Table cell separator in
 lists; can only be used below
 .Sx \&It .
 .Ss \&Tn
 lists; can only be used below
 .Sx \&It .
 .Ss \&Tn

-Format a tradename.
-.Pp
-Since this macro is often implemented to use a small caps font,
-it has historically been used for acronyms (like ASCII) as well.
-Such usage is not recommended because it would use the same macro
-sometimes for semantical annotation, sometimes for physical formatting.
-.Pp
-Examples:
-.Dl \&.Tn IBM
+Supported only for compatibility, do not use this in new manuals.
+Even though the macro name
+.Pq Dq tradename
+suggests a semantic function, historic usage is inconsistent, mostly
+using it as a presentation-level macro to request a small caps font.

 .Ss \&Ud
 .Ss \&Ud

+Supported only for compatibility, do not use this in new manuals.

 Prints out
 .Dq currently under development.
 .Ss \&Ux
 Prints out
 .Dq currently under development.
 .Ss \&Ux

-Format the
-.Ux
-name.
-Accepts no argument.
-.Pp
-Examples:
-.Dl \&.Ux
-.Pp
-See also
-.Sx \&At ,
-.Sx \&Bsx ,
-.Sx \&Bx ,
-.Sx \&Dx ,
-.Sx \&Fx ,
-.Sx \&Nx ,
-and
-.Sx \&Ox .
+Supported only for compatibility, do not use this in new manuals.
+Prints out
+.Dq Ux .

 .Ss \&Va
 A variable name.
 .Pp
 .Ss \&Va
 A variable name.
 .Pp


@@ -2909,6 +2903,7 @@ end of the line.
 .It Sx \&D1  Ta    \&No     Ta    \&Yes
 .It Sx \&Dl  Ta    \&No     Ta    Yes
 .It Sx \&Dq  Ta    Yes      Ta    Yes
 .It Sx \&D1  Ta    \&No     Ta    \&Yes
 .It Sx \&Dl  Ta    \&No     Ta    Yes
 .It Sx \&Dq  Ta    Yes      Ta    Yes

+.It Sx \&En  Ta    Yes      Ta    Yes

 .It Sx \&Op  Ta    Yes      Ta    Yes
 .It Sx \&Pq  Ta    Yes      Ta    Yes
 .It Sx \&Ql  Ta    Yes      Ta    Yes
 .It Sx \&Op  Ta    Yes      Ta    Yes
 .It Sx \&Pq  Ta    Yes      Ta    Yes
 .It Sx \&Ql  Ta    Yes      Ta    Yes


@@ -2986,16 +2981,15 @@ then the macro accepts an arbitrary number of arguments.
 .It Sx \&Dv  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Em  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Dv  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Em  Ta    Yes      Ta    Yes      Ta    >0

-.It Sx \&En  Ta    \&No     Ta    \&No     Ta    0

 .It Sx \&Er  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Er  Ta    Yes      Ta    Yes      Ta    >0

-.It Sx \&Es  Ta    \&No     Ta    \&No     Ta    0
+.It Sx \&Es  Ta    Yes      Ta    Yes      Ta    2

 .It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ex  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fd  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Fl  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Fn  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ex  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fd  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Fl  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Fn  Ta    Yes      Ta    Yes      Ta    >0

-.It Sx \&Fr  Ta    \&No     Ta    \&No     Ta    n
+.It Sx \&Fr  Ta    Yes      Ta    Yes      Ta    >0

 .It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Hf  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Hf  Ta    \&No     Ta    \&No     Ta    n


@@ -3012,7 +3006,7 @@ then the macro accepts an arbitrary number of arguments.
 .It Sx \&Ns  Ta    Yes      Ta    Yes      Ta    0
 .It Sx \&Nx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Os  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ns  Ta    Yes      Ta    Yes      Ta    0
 .It Sx \&Nx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Os  Ta    \&No     Ta    \&No     Ta    n

-.It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n
+.It Sx \&Ot  Ta    Yes      Ta    Yes      Ta    >0

 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1


@@ -3134,8 +3128,9 @@ Manually switching the font using the
 .Ql \ef
 font escape sequences is never required.
 .Sh COMPATIBILITY
 .Ql \ef
 font escape sequences is never required.
 .Sh COMPATIBILITY

-This section documents compatibility between mandoc and other
-troff implementations, at this time limited to GNU troff
+This section provides an incomplete list of compatibility issues
+between mandoc and other troff implementations, at this time limited
+to GNU troff

 .Pq Qq groff .
 The term
 .Qq historic groff
 .Pq Qq groff .
 The term
 .Qq historic groff


@@ -3244,7 +3239,7 @@ certain list types.
 can only be called by other macros, but not at the beginning of a line.
 .It
 .Sx \&%C
 can only be called by other macros, but not at the beginning of a line.
 .It
 .Sx \&%C

-is not implemented.
+is not implemented (up to and including groff-1.22.2).

 .It
 Historic groff only allows up to eight or nine arguments per macro input
 line, depending on the exact situation.
 .It
 Historic groff only allows up to eight or nine arguments per macro input
 line, depending on the exact situation.


@@ -3262,7 +3257,7 @@ in new groff and mandoc.
 .Sq \ef
 .Pq font face
 and
 .Sq \ef
 .Pq font face
 and

-.Sq \ef
+.Sq \eF

 .Pq font family face
 .Sx Text Decoration
 escapes behave irregularly when specified within line-macro scopes.
 .Pq font family face
 .Sx Text Decoration
 escapes behave irregularly when specified within line-macro scopes.


@@ -3284,36 +3279,6 @@ and
 .Fl offset Cm right .
 Groff does not implement centred and flush-right rendering either,
 but produces large indentations.
 .Fl offset Cm right .
 Groff does not implement centred and flush-right rendering either,
 but produces large indentations.

-.It
-The
-.Sq \eh
-.Pq horizontal position ,
-.Sq \ev
-.Pq vertical position ,
-.Sq \em
-.Pq text colour ,
-.Sq \eM
-.Pq text filling colour ,
-.Sq \ez
-.Pq zero-length character ,
-.Sq \ew
-.Pq string length ,
-.Sq \ek
-.Pq horizontal position marker ,
-.Sq \eo
-.Pq text overstrike ,
-and
-.Sq \es
-.Pq text size
-escape sequences are all discarded in mandoc.
-.It
-The
-.Sq \ef
-scaling unit is accepted by mandoc, but rendered as the default unit.
-.It
-In quoted literals, groff allows pairwise double-quotes to produce a
-standalone double-quote in formatted output.
-This is not supported by mandoc.

 .El
 .Sh SEE ALSO
 .Xr man 1 ,
 .El
 .Sh SEE ALSO
 .Xr man 1 ,