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 ,