=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.101 retrieving revision 1.109 diff -u -p -r1.101 -r1.109 --- mandoc/mdoc.7 2010/05/12 17:08:03 1.101 +++ mandoc/mdoc.7 2010/05/26 09:35:35 1.109 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.101 2010/05/12 17:08:03 kristaps Exp $ +.\" $Id: mdoc.7,v 1.109 2010/05/26 09:35:35 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: May 12 2010 $ +.Dd $Mdocdate: May 26 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -301,7 +301,18 @@ When composing a manual, make sure that your sentences a line. By doing so, front-ends will be able to apply the proper amount of spacing after the end of sentence (unescaped) period, exclamation mark, -or question mark. +or question mark followed by zero or more non-sentence closing +delimiters ( +.Ns Sq \&) , +.Sq \&] , +.Sq \&' , +.Sq \&" ) . +.Pp +The proper spacing is also intelligently preserved if a sentence ends at +the boundary of a macro line, e.g., +.Pp +.D1 \&Xr mandoc 1 \. +.D1 \&Fl T \&Ns \&Cm ascii \. .Sh MANUAL STRUCTURE A well-formed .Nm @@ -336,7 +347,7 @@ file: \&.Sh NAME \&.Nm foo \&.Nd a description goes here -\&.\e\*q The next is for sections 2 & 3 only. +\&.\e\*q The next is for sections 2, 3, & 9 only. \&.\e\*q .Sh LIBRARY \&. \&.Sh SYNOPSIS @@ -398,7 +409,7 @@ and .Sx \&Nd . .It Em LIBRARY The name of the library containing the documented material, which is -assumed to be a function in a section 2 or 3 manual. +assumed to be a function in a section 2, 3, or 9 manual. The syntax for this is as follows: .Bd -literal -offset indent \&.Lb libarm @@ -720,7 +731,9 @@ Note that the macro is a .Sx Block partial-implicit only when invoked as the first macro -in a SYNOPSIS section line, else it is +in a +.Em SYNOPSIS +section line, else it is .Sx In-line . .Ss In-line Closed by @@ -1089,60 +1102,113 @@ and .Ss \&Bf .Ss \&Bk .Ss \&Bl -.\" Begins a list composed of one or more list entries. A list entry is -.\" specified by the -.\" .Sx \&It -.\" macro, which consists of a head and optional body. By default, a list -.\" is preceded by a blank line. A list must specify one of the following -.\" list types: -.\" .Bl -tag -width 12n -.\" .It Fl bullet -.\" A list offset by a bullet. The head of list entries must be empty. -.\" List entry bodies are justified after the bullet. -.\" .It Fl column -.\" A columnated list. The number of columns is specified as arguments to -.\" the -.\" .Sx \&Bl -.\" macro (the deprecated form of following the invocation of -.\" .Fl column -.\" is also accepted). Arguments dictate the width of columns specified in -.\" list entries. List entry bodies must be left empty. Columns specified -.\" in the list entry head are justified to their position in the sequence -.\" of columns. -.\" .It Fl dash -.\" A list offset by a dash (hyphen). The head of list entries must be -.\" empty. List entry bodies are justified past the dash. -.\" .It Fl diag -.\" Like -.\" .Fl inset -.\" lists, but with additional formatting to the head. -.\" .It Fl enum -.\" A list offset by a number indicating list entry position. The head of -.\" list entries must be empty. List entry bodies are justified past the -.\" enumeration. -.\" .It Fl hang -.\" Like -.\" .Fl tag , -.\" but instead of list bodies justifying to the head on the first line, -.\" they trail the head text. -.\" .It Fl hyphen -.\" Synonym for -.\" .Fl dash . -.\" .It Fl inset -.\" Like -.\" .Fl tag , -.\" but list entry bodies aren't justified. -.\" .It Fl item -.\" An un-justified list. This produces blocks of text. -.\" .It Fl ohang -.\" List bodies are placed on the line following the head. -.\" .It Fl tag -.\" A list offset by list entry heads. List entry bodies are justified -.\" after the head. -.\" .El -.\" .Pp -.\" More... -.\" . +Begins a list composed of one or more list entries. +A list is associated with a type, which is a required argument. +Other arguments are +.Fl width , +defined per-type as accepting a literal or +.Sx Scaling Widths +value; +.Fl offset , +also accepting a literal or +.Sx Scaling Widths +value setting the list's global offset; and +.Fl compact , +suppressing the default vertical space printed before each list entry. +A list entry is specified by the +.Sx \&It +macro, which consists of a head and optional body (depending on the list +type). +A list must specify one of the following list types: +.Bl -tag -width 12n -offset indent +.It Fl bullet +A list offset by a bullet. +The head of list entries must be empty. +List entry bodies are positioned after the bullet. +The +.Fl width +argument varies the width of list bodies' left-margins. +.It Fl column +A columnated list. +The +.Fl width +argument has no effect. +The number of columns is specified as parameters to the +.Sx \&Bl +macro. +These dictate the width of columns either as +.Sx Scaling Widths +or literal text. +List entry bodies must be left empty. +Column bodies have the following syntax: +.Pp +.D1 .It col1 ... coln +.D1 .It col1 Ta ... coln +.D1 .It col1 col2 Ta coln +.Pp +where columns may be separated by tabs, the literal string +.Qq Ta , +or a mixture of both. +These are equivalent except that quoted sections propogate over tabs, +for example, +.Pp +.D1 .It \(dqcol1 ; col2 ;\(dq ; +.Pp +will preserve the semicolon whitespace except for the last. +.It Fl dash +A list offset by a dash (hyphen). +The head of list entries must be empty. +List entry bodies are positioned past the dash. +The +.Fl width +argument varies the width of list bodies' left-margins. +.It Fl diag +Like +.Fl inset , +but with additional formatting to the head. +The +.Fl width +argument varies the width of list bodies' left-margins. +.It Fl enum +An enumerated list offset by the enumeration from 1. +The head of list entries must be empty. +List entry bodies are positioned after the enumeration. +The +.Fl width +argument varies the width of list bodies' left-margins. +.It Fl hang +Like +.Fl tag , +but instead of list bodies positioned after the head, they trail the +head text. +The +.Fl width +argument varies the width of list bodies' left-margins. +.It Fl hyphen +Synonym for +.Fl dash . +.It Fl inset +List bodies follow the list head. +The +.Fl width +argument is ignored. +.It Fl item +This produces blocks of text. +The head of list entries must be empty. +The +.Fl width +argument is ignored. +.It Fl ohang +List bodies are positioned on the line following the head. +The +.Fl width +argument is ignored. +.It Fl tag +A list offset by list entry heads. List entry bodies are positioned +after the head as specified by the +.Fl width +argument. +.El .Ss \&Bo Begins a block enclosed by square brackets. Does not have any head arguments. @@ -1580,6 +1646,28 @@ and .Ss \&In .Ss \&It .Ss \&Lb +Specify a library. +The calling syntax is as follows: +.Pp +.D1 \. Ns Sx \&Lb Cm library +.Pp +The +.Cm library +parameter may be a system library, such as +.Cm libz +or +.Cm libpam , +in which case a small library description is printed next to the linker +invocation; or a custom library, in which case the library name is +printed in quotes. +This is most commonly used in the +.Em SYNOPSIS +section as described in +.Sx MANUAL STRUCTURE . +.Pp +Examples: +.D1 \&.Lb libz +.D1 \&.Lb mdoc .Ss \&Li .Ss \&Lk Format a hyperlink. @@ -1900,10 +1988,17 @@ This is not the case in mandoc. In groff, the .Sx \&Cd , .Sx \&Er , +.Sx \&Ex , and -.Sx \&Ex +.Sx \&Rv macros were stipulated only to occur in certain manual sections. mandoc does not have these restrictions. +.It +Newer groff and mandoc print +.Qq AT&T UNIX +prior to unknown arguments of +.Sx \&At ; +older groff did nothing. .El .Sh SEE ALSO .Xr mandoc 1 ,