Print this page
feedback from Hans
*** 13,24 ****
.\"
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
.\"
! .Dd Jan 3, 2012
.Dt MDOC 5
.Os
.Sh NAME
.Nm mdoc
.Nd semantic markup language for formatting manual pages
--- 13,25 ----
.\"
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
+ .\" Copyright 2014 Garrett D'Amore <garrett@dmaore.org>
.\"
! .Dd Jul 16, 2014
.Dt MDOC 5
.Os
.Sh NAME
.Nm mdoc
.Nd semantic markup language for formatting manual pages
*** 146,155 ****
--- 147,162 ----
\&.\e\(dq .Sh EXAMPLES
\&.\e\(dq .Sh DIAGNOSTICS
\&.\e\(dq For sections 1, 1M, 5, 6, & 7 only.
\&.\e\(dq .Sh ERRORS
\&.\e\(dq For sections 2, 3, & 9 only.
+ \&.\e\(dq .Sh ARCHITECTURE
+ \&.\e\(dq .Sh CODE SET INDEPENDENCE
+ \&.\e\(dq For sections 1, 1M, & 3 only.
+ \&.\e\(dq .Sh INTERFACE STABILITY
+ \&.\e\(dq .Sh MT-LEVEL
+ \&.\e\(dq For sections 2 & 3 only.
\&.\e\(dq .Sh SEE ALSO
\&.\e\(dq .Xr foobar 1
\&.\e\(dq .Sh STANDARDS
\&.\e\(dq .Sh HISTORY
\&.\e\(dq .Sh AUTHORS
*** 370,379 ****
--- 377,498 ----
.It Em ERRORS
Documents error handling in sections 2, 3, and 9.
.Pp
See
.Sx \&Er .
+ .It Em ARCHITECTURE
+ This section is usually absent, but will be present when the
+ interface is specific to one or more architectures.
+ .It Em CODE SET INDEPENDENCE
+ Indicates whether the interface operates correctly with various different
+ code sets. True independent code sets will support not only ASCII and
+ Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
+ UTF-8 and GB2312.
+ .Pp
+ Generally there will be some limitations that are fairly standard. See
+ .Xr standards 5 for more information about some of these. Most interfaces
+ should support at least UTF-8 in addition to ASCII.
+ .It Em INTERFACE STABILITY
+ Indicates the level of commitment to the interface. Interfaces can be described
+ with in the following ways:
+ .Bl -tag
+ .It Nm Standard
+ Indicates that the interface is defined by one or more standards bodies.
+ Generally, changes to the interface will be carefully managed to conform
+ to the relevant standards. These interfaces are generally the most suitable
+ for use in portable programs.
+ .It Nm Committed
+ Indicates that the interface is intended to be preserved for the long-haul, and
+ will rarely, if ever change, and never without notification (barring
+ extraordinary and extenuating circumstances). These interfaces are
+ preferred over other interfaces with the exeception of
+ .Nm Standard
+ interfaces.
+ .It Nm Uncommitted
+ Indicates that the interface may change. Generally, changes to these interfaces
+ should be infrequent, and some effort will be made to address compatibility
+ considerations when changing or removing such interfaces. However, there is
+ no firm commitment to the preservation of the interface. Most often this
+ is applied to interfaces where operational experience with the interface
+ is still limited and some need to change may be anticipated.
+ .Pp
+ Consumers should expect to revalidate any
+ .Nm Uncommitted
+ interfaces when crossing release boundaries. Products intended for
+ use on many releases or intended to support compatibility with future
+ releases should avoid these interfaces.
+ .It Nm Volatile
+ The interface can change at any time for any reason. Often this relates to
+ interfaces that are part of external software components that are still evolving
+ rapidly. Consumers should not expect that the interface (either binary or
+ source level) will be unchanged from one release to the next.
+ .It Nm Not-an-Interface
+ Describes something that is specifically not intended for programmatic
+ consumption. For example, specific human-readable output, or the layout
+ of graphical items on a user interface, may be described this way. Generally
+ programmatic alternatives to these will be available, and should be used
+ when programmatic consumption is needed.
+ .It Nm Private
+ This is an internal interface. Generally these interfaces should only be
+ used within the project, and should not be used by other programs or modules.
+ The interface can and will change without notice as the project needs, at
+ any time.
+ .Pp
+ Most often, Private interfaces will lack any documentation whatsoever, and
+ generally any undocumented interface can be assumed to be Private.
+ .It Nm Obsolete
+ The interface is not intended for use in new projects or programs, and may
+ be removed at a future date. The
+ .Nm Obsolete
+ word is a modifier that can
+ be applied to other commitment levels. For example an
+ .Nm Obsolete Committed
+ interface is unlikely to be removed or changed, but nonetheless new use
+ is discouraged (perhaps a better newer alternative is present).
+ .El
+ .It Em MT-LEVEL
+ This section describes considerations for the interface when used within
+ programs that use multiple threads. More discussion of these considerations
+ is made in the MT-Level section of
+ .Xr attributes 5 .
+ The interface can be described in the following ways.
+ .Bl -tag
+ .It Nm Safe
+ Indicates the interface is safe for use within multiple threads. There
+ may be additional caveats that apply, in which case those will be
+ described. Note that some interfaces have semantics which may affect
+ other threads, but these should be an intrinsic part of the interface
+ rather than an unexpected side effect. For example, closing a file in
+ one thread will cause that file to be closed in all threads.
+ .It Nm Unsafe
+ Indicates the interface is unsuitable for concurrent use within multiple
+ threads. A threaded application may still make use of the interface, but
+ will be required to provide external synchronization means to ensure that
+ only a single thread calls the interface at a time.
+ .It Nm MT-Safe
+ Indicates that the interface is not only safe for concurrent use, but is
+ designed for such use. For example, a
+ .Nm Safe
+ interface may make use of a global lock to provide safety, but at reduced
+ internal concurrency, whereas an
+ .Nm MT-Safe
+ interface will be designed to be efficient even when used concurrently.
+ .It Nm Async-Signal-Safe
+ Indicates that the library is safe for use within a signal handler. An
+ .Nm MT-Safe
+ interface can be made
+ .Nm Async-Signal-Safe
+ by ensuring that it blocks signals when acquiring locks.
+ .It Nm Safe with Exections
+ As for
+ .Nm Safe
+ but with specific exceptions noted.
+ .It Nm MT-Safe with Exections
+ As for
+ .Nm MT-Safe
+ but with specific exceptions noted.
+ .El
.It Em SEE ALSO
References other manuals with related topics.
This section should exist for most manuals.
Cross-references should conventionally be ordered first by section, then
alphabetically.
*** 1231,1241 ****
This is formatted as literal text and is useful for commands and
invocations.
It is followed by a newline.
.Pp
Examples:
! .Dl \&.Dl % mandoc mdoc.7 \e(ba less
.Pp
See also
.Sx \&Bd
and
.Sx \&D1 .
--- 1350,1360 ----
This is formatted as literal text and is useful for commands and
invocations.
It is followed by a newline.
.Pp
Examples:
! .Dl \&.Dl % mandoc mdoc.5 \e(ba less
.Pp
See also
.Sx \&Bd
and
.Sx \&D1 .
*** 1416,1426 ****
for general constants.
.Ss \&Es
This macro is obsolete and not implemented.
.Ss \&Ev
Environmental variables such as those specified in
! .Xr environ 7 .
.Pp
Examples:
.Dl \&.Ev DISPLAY
.Dl \&.Ev PATH
.Pp
--- 1535,1545 ----
for general constants.
.Ss \&Es
This macro is obsolete and not implemented.
.Ss \&Ev
Environmental variables such as those specified in
! .Xr environ 5 .
.Pp
Examples:
.Dl \&.Ev DISPLAY
.Dl \&.Ev PATH
.Pp
*** 2030,2040 ****
.Sq \(ti
is used as a default.
.Pp
Examples:
.Dl \&.Pa /usr/bin/mandoc
! .Dl \&.Pa /usr/share/man/man7/mdoc.7
.Pp
See also
.Sx \&Lk .
.Ss \&Pc
Close parenthesised context opened by
--- 2149,2159 ----
.Sq \(ti
is used as a default.
.Pp
Examples:
.Dl \&.Pa /usr/bin/mandoc
! .Dl \&.Pa /usr/share/man/man5/mdoc.5
.Pp
See also
.Sx \&Lk .
.Ss \&Pc
Close parenthesised context opened by
*** 3081,3090 ****
--- 3200,3210 ----
in groff-1.17.
The standalone implementation that is part of the
.Xr mandoc 1
utility written by Kristaps Dzonsons appeared in
.Ox 4.6 .
+ in July, 2014.
.Sh AUTHORS
The
.Nm
reference was written by
.An Kristaps Dzonsons ,