Print this page 
feedback from Hans
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man5/mdoc.5
          +++ new/usr/src/man/man5/mdoc.5
↓ open down ↓ 7 lines elided ↑ open up ↑ 
   8    8  .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   9    9  .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  10   10  .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  11   11  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  12   12  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  13   13  .\"
  14   14  .\"
  15   15  .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  16   16  .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
  17   17  .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
       18 +.\" Copyright 2014 Garrett D'Amore <garrett@dmaore.org>
  18   19  .\"
  19      -.Dd Jan 3, 2012
       20 +.Dd Jul 16, 2014
  20   21  .Dt MDOC 5
  21   22  .Os
  22   23  .Sh NAME
  23   24  .Nm mdoc
  24   25  .Nd semantic markup language for formatting manual pages
  25   26  .Sh DESCRIPTION
  26   27  The
  27   28  .Nm mdoc
  28   29  language supports authoring of manual pages for the
  29   30  .Xr man 1
↓ open down ↓ 111 lines elided ↑ open up ↑ 
 141  142  \&.\e\(dq .Sh ENVIRONMENT
 142  143  \&.\e\(dq For sections 1, 1M, 5, & 6 only.
 143  144  \&.\e\(dq .Sh FILES
 144  145  \&.\e\(dq .Sh EXIT STATUS
 145  146  \&.\e\(dq For sections 1, 1M, & 6 only.
 146  147  \&.\e\(dq .Sh EXAMPLES
 147  148  \&.\e\(dq .Sh DIAGNOSTICS
 148  149  \&.\e\(dq For sections 1, 1M, 5, 6, & 7 only.
 149  150  \&.\e\(dq .Sh ERRORS
 150  151  \&.\e\(dq For sections 2, 3, & 9 only.
      152 +\&.\e\(dq .Sh ARCHITECTURE
      153 +\&.\e\(dq .Sh CODE SET INDEPENDENCE
      154 +\&.\e\(dq For sections 1, 1M, & 3 only.
      155 +\&.\e\(dq .Sh INTERFACE STABILITY
      156 +\&.\e\(dq .Sh MT-LEVEL
      157 +\&.\e\(dq For sections 2 & 3 only.
 151  158  \&.\e\(dq .Sh SEE ALSO
 152  159  \&.\e\(dq .Xr foobar 1
 153  160  \&.\e\(dq .Sh STANDARDS
 154  161  \&.\e\(dq .Sh HISTORY
 155  162  \&.\e\(dq .Sh AUTHORS
 156  163  \&.\e\(dq .Sh CAVEATS
 157  164  \&.\e\(dq .Sh BUGS
 158  165  \&.\e\(dq .Sh SECURITY CONSIDERATIONS
 159  166  \&.\e\(dq Not used in OpenBSD.
 160  167  .Ed
↓ open down ↓ 204 lines elided ↑ open up ↑ 
 365  372  discouraged.
 366  373  .Pp
 367  374  See
 368  375  .Sx \&Bl
 369  376  .Fl diag .
 370  377  .It Em ERRORS
 371  378  Documents error handling in sections 2, 3, and 9.
 372  379  .Pp
 373  380  See
 374  381  .Sx \&Er .
      382 +.It Em ARCHITECTURE
      383 +This section is usually absent, but will be present when the
      384 +interface is specific to one or more architectures.
      385 +.It Em CODE SET INDEPENDENCE
      386 +Indicates whether the interface operates correctly with various different
      387 +code sets.  True independent code sets will support not only ASCII and
      388 +Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
      389 +UTF-8 and GB2312.
      390 +.Pp
      391 +Generally there will be some limitations that are fairly standard.  See
      392 +.Xr standards 5 for more information about some of these.  Most interfaces
      393 +should support at least UTF-8 in addition to ASCII.
      394 +.It Em INTERFACE STABILITY
      395 +Indicates the level of commitment to the interface. Interfaces can be described
      396 +with in the following ways:
      397 +.Bl -tag
      398 +.It Nm Standard
      399 +Indicates that the interface is defined by one or more standards bodies.
      400 +Generally, changes to the interface will be carefully managed to conform
      401 +to the relevant standards.  These interfaces are generally the most suitable
      402 +for use in portable programs.
      403 +.It Nm Committed
      404 +Indicates that the interface is intended to be preserved for the long-haul, and
      405 +will rarely, if ever change, and never without notification (barring
      406 +extraordinary and extenuating circumstances). These interfaces are 
      407 +preferred over other interfaces with the exeception of
      408 +.Nm Standard
      409 +interfaces.
      410 +.It Nm Uncommitted
      411 +Indicates that the interface may change.  Generally, changes to these interfaces
      412 +should be infrequent, and some effort will be made to address compatibility
      413 +considerations when changing or removing such interfaces.  However, there is
      414 +no firm commitment to the preservation of the interface.  Most often this
      415 +is applied to interfaces where operational experience with the interface
      416 +is still limited and some need to change may be anticipated.
      417 +.Pp
      418 +Consumers should expect to revalidate any
      419 +.Nm Uncommitted
      420 +interfaces when crossing release boundaries.  Products intended for
      421 +use on many releases or intended to support compatibility with future
      422 +releases should avoid these interfaces.
      423 +.It Nm Volatile
      424 +The interface can change at any time for any reason. Often this relates to
      425 +interfaces that are part of external software components that are still evolving
      426 +rapidly.  Consumers should not expect that the interface (either binary or
      427 +source level) will be unchanged from one release to the next.
      428 +.It Nm Not-an-Interface
      429 +Describes something that is specifically not intended for programmatic
      430 +consumption.  For example, specific human-readable output, or the layout
      431 +of graphical items on a user interface, may be described this way.  Generally
      432 +programmatic alternatives to these will be available, and should be used
      433 +when programmatic consumption is needed.
      434 +.It Nm Private
      435 +This is an internal interface.  Generally these interfaces should only be
      436 +used within the project, and should not be used by other programs or modules.
      437 +The interface can and will change without notice as the project needs, at
      438 +any time.
      439 +.Pp
      440 +Most often, Private interfaces will lack any documentation whatsoever, and
      441 +generally any undocumented interface can be assumed to be Private.
      442 +.It Nm Obsolete
      443 +The interface is not intended for use in new projects or programs, and may
      444 +be removed at a future date.  The
      445 +.Nm Obsolete
      446 +word is a modifier that can
      447 +be applied to other commitment levels. For example an
      448 +.Nm Obsolete Committed
      449 +interface is unlikely to be removed or changed, but nonetheless new use
      450 +is discouraged (perhaps a better newer alternative is present).
      451 +.El
      452 +.It Em MT-LEVEL
      453 +This section describes considerations for the interface when used within
      454 +programs that use multiple threads.  More discussion of these considerations
      455 +is made in the MT-Level section of
      456 +.Xr attributes 5 .
      457 +The interface can be described in the following ways.
      458 +.Bl -tag
      459 +.It Nm Safe
      460 +Indicates the interface is safe for use within multiple threads.  There
      461 +may be additional caveats that apply, in which case those will be
      462 +described.  Note that some interfaces have semantics which may affect
      463 +other threads, but these should be an intrinsic part of the interface
      464 +rather than an unexpected side effect.  For example, closing a file in
      465 +one thread will cause that file to be closed in all threads.
      466 +.It Nm Unsafe
      467 +Indicates the interface is unsuitable for concurrent use within multiple
      468 +threads.  A threaded application may still make use of the interface, but
      469 +will be required to provide external synchronization means to ensure that
      470 +only a single thread calls the interface at a time.
      471 +.It Nm MT-Safe
      472 +Indicates that the interface is not only safe for concurrent use, but is
      473 +designed for such use.  For example, a
      474 +.Nm Safe
      475 +interface may make use of a global lock to provide safety, but at reduced
      476 +internal concurrency, whereas an
      477 +.Nm MT-Safe
      478 +interface will be designed to be efficient even when used concurrently.
      479 +.It Nm Async-Signal-Safe
      480 +Indicates that the library is safe for use within a signal handler.  An
      481 +.Nm MT-Safe
      482 +interface can be made
      483 +.Nm Async-Signal-Safe
      484 +by ensuring that it blocks signals when acquiring locks.
      485 +.It Nm Safe with Exections
      486 +As for
      487 +.Nm Safe
      488 +but with specific exceptions noted.
      489 +.It Nm MT-Safe with Exections
      490 +As for
      491 +.Nm MT-Safe
      492 +but with specific exceptions noted.
      493 +.El
 375  494  .It Em SEE ALSO
 376  495  References other manuals with related topics.
 377  496  This section should exist for most manuals.
 378  497  Cross-references should conventionally be ordered first by section, then
 379  498  alphabetically.
 380  499  .Pp
 381  500  References to other documentation concerning the topic of the manual page,
 382  501  for example authoritative books or journal articles, may also be
 383  502  provided in this section.
 384  503  .Pp
↓ open down ↓ 841 lines elided ↑ open up ↑ 
1226 1345  .Sx \&Dt
1227 1346  and
1228 1347  .Sx \&Os .
1229 1348  .Ss \&Dl
1230 1349  One-line intended display.
1231 1350  This is formatted as literal text and is useful for commands and
1232 1351  invocations.
1233 1352  It is followed by a newline.
1234 1353  .Pp
1235 1354  Examples:
1236      -.Dl \&.Dl % mandoc mdoc.7 \e(ba less
     1355 +.Dl \&.Dl % mandoc mdoc.5 \e(ba less
1237 1356  .Pp
1238 1357  See also
1239 1358  .Sx \&Bd
1240 1359  and
1241 1360  .Sx \&D1 .
1242 1361  .Ss \&Do
1243 1362  Begin a block enclosed by double quotes.
1244 1363  Does not have any head arguments.
1245 1364  .Pp
1246 1365  Examples:
↓ open down ↓ 164 lines elided ↑ open up ↑ 
1411 1530  .Dl \&.Er EPERM
1412 1531  .Dl \&.Er ENOENT
1413 1532  .Pp
1414 1533  See also
1415 1534  .Sx \&Dv
1416 1535  for general constants.
1417 1536  .Ss \&Es
1418 1537  This macro is obsolete and not implemented.
1419 1538  .Ss \&Ev
1420 1539  Environmental variables such as those specified in
1421      -.Xr environ 7 .
     1540 +.Xr environ 5 .
1422 1541  .Pp
1423 1542  Examples:
1424 1543  .Dl \&.Ev DISPLAY
1425 1544  .Dl \&.Ev PATH
1426 1545  .Pp
1427 1546  See also
1428 1547  .Sx \&Dv
1429 1548  for general constants.
1430 1549  .Ss \&Ex
1431 1550  Insert a standard sentence regarding command exit values of 0 on success
↓ open down ↓ 593 lines elided ↑ open up ↑ 
2025 2144  and
2026 2145  .Sx \&Ux .
2027 2146  .Ss \&Pa
2028 2147  An absolute or relative file system path, or a file or directory name.
2029 2148  If an argument is not provided, the character
2030 2149  .Sq \(ti
2031 2150  is used as a default.
2032 2151  .Pp
2033 2152  Examples:
2034 2153  .Dl \&.Pa /usr/bin/mandoc
2035      -.Dl \&.Pa /usr/share/man/man7/mdoc.7
     2154 +.Dl \&.Pa /usr/share/man/man5/mdoc.5
2036 2155  .Pp
2037 2156  See also
2038 2157  .Sx \&Lk .
2039 2158  .Ss \&Pc
2040 2159  Close parenthesised context opened by
2041 2160  .Sx \&Po .
2042 2161  .Ss \&Pf
2043 2162  Removes the space between its argument
2044 2163  .Pq Dq prefix
2045 2164  and the following macro.
↓ open down ↓ 1030 lines elided ↑ open up ↑ 
3076 3195  The
3077 3196  .Nm
3078 3197  language first appeared as a troff macro package in
3079 3198  .Bx 4.4 .
3080 3199  It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3081 3200  in groff-1.17.
3082 3201  The standalone implementation that is part of the
3083 3202  .Xr mandoc 1
3084 3203  utility written by Kristaps Dzonsons appeared in
3085 3204  .Ox 4.6 .
     3205 +in July, 2014.
3086 3206  .Sh AUTHORS
3087 3207  The
3088 3208  .Nm
3089 3209  reference was written by
3090 3210  .An Kristaps Dzonsons ,
3091 3211  .Mt kristaps@bsd.lv .
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX