feedback from Hans

@@ -13,12 +13,13 @@
 .\"
 .\"
 .\" 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 Jan 3, 2012
+.Dd Jul 16, 2014
 .Dt MDOC 5
 .Os
 .Sh NAME
 .Nm mdoc
 .Nd semantic markup language for formatting manual pages

@@ -146,10 +147,16 @@
 \&.\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,10 +377,122 @@
 .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,11 +1350,11 @@
 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
+.Dl \&.Dl % mandoc mdoc.5 \e(ba less
 .Pp
 See also
 .Sx \&Bd
 and
 .Sx \&D1 .

@@ -1416,11 +1535,11 @@
 for general constants.
 .Ss \&Es
 This macro is obsolete and not implemented.
 .Ss \&Ev
 Environmental variables such as those specified in
-.Xr environ 7 .
+.Xr environ 5 .
 .Pp
 Examples:
 .Dl \&.Ev DISPLAY
 .Dl \&.Ev PATH
 .Pp

@@ -2030,11 +2149,11 @@
 .Sq \(ti
 is used as a default.
 .Pp
 Examples:
 .Dl \&.Pa /usr/bin/mandoc
-.Dl \&.Pa /usr/share/man/man7/mdoc.7
+.Dl \&.Pa /usr/share/man/man5/mdoc.5
 .Pp
 See also
 .Sx \&Lk .
 .Ss \&Pc
 Close parenthesised context opened by

@@ -3081,10 +3200,11 @@
 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 ,