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 ,