=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.105 retrieving revision 1.114 diff -u -p -r1.105 -r1.114 --- mandoc/mdoc.7 2010/05/14 16:02:29 1.105 +++ mandoc/mdoc.7 2010/06/03 14:29:52 1.114 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.105 2010/05/14 16:02:29 kristaps Exp $ +.\" $Id: mdoc.7,v 1.114 2010/06/03 14:29:52 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 14 2010 $ +.Dd $Mdocdate: June 3 2010 $ .Dt MDOC 7 .Os .Sh NAME @@ -301,10 +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. +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 @@ -335,18 +343,15 @@ file: \&.Dd $\&Mdocdate$ \&.Dt mdoc 7 \&.Os -\&. \&.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 \&.Nm foo \&.Op Fl options \&.Ar -\&. \&.Sh DESCRIPTION The \&.Nm @@ -401,7 +406,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 @@ -723,7 +728,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 @@ -1129,22 +1136,18 @@ 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. +If the initial macro of a +.Fl column +list is not an +.Sx \&It , +an +.Sx \&It +context spanning each line is implied until an +.Sx \&It +line macro is encountered, at which point list bodies are interpreted as +described in the +.Sx \&It +documentation. .It Fl dash A list offset by a dash (hyphen). The head of list entries must be empty. @@ -1199,6 +1202,9 @@ after the head as specified by the .Fl width argument. .El +.Pp +See also +.Sx \&It . .Ss \&Bo Begins a block enclosed by square brackets. Does not have any head arguments. @@ -1398,13 +1404,15 @@ This is the mandatory second macro of any file. Its calling syntax is as follows: .Pp -.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch +.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch .Pp Its arguments are as follows: .Bl -tag -width Ds -offset Ds .It Cm title -The document's title (name). -This should be capitalised and is required. +The document's title (name), defaulting to +.Qq UNKNOWN +if unspecified. +It should be capitalised. .It Cm section The manual section. This may be one of @@ -1441,8 +1449,9 @@ This may be one of or .Ar paper .Pq paper . -It is also required and should correspond to the manual's filename -suffix. +It should correspond to the manual's filename suffix and defaults to +.Qq 1 +if unspecified. .It Cm volume This overrides the volume inferred from .Ar section . @@ -1514,7 +1523,6 @@ Examples: .D1 \&.Dt FOO 1 .D1 \&.Dt FOO 4 KM .D1 \&.Dt FOO 9 i386 -.D1 \&.Dt FOO 9 KM i386 .Pp See also .Sx \&Dd @@ -1635,7 +1643,109 @@ and .Ss \&Ic .Ss \&In .Ss \&It +A list item. The syntax of this macro depends on the list type. +.Pp +Lists +of type +.Fl hang , +.Fl ohang , +.Fl inset , +and +.Fl diag +have the following calling syntax: +.Pp +.D1 \. Ns Sx \&It Cm args +.Pp +Lists of type +.Fl bullet , +.Fl dash , +.Fl enum , +.Fl hyphen +and +.Fl item +have the following calling syntax: +.Pp +.D1 \. Ns Sx \&It +.Pp +with subsequent lines interpreted within the scope of the +.Sx \&It +until either a closing +.Sx \&El +or another +.Sx \&It . +.Pp +The +.Fl tag +list has syntax +.Pp +.D1 \. Ns Sx \&It Op Cm args +.Pp +with subsequent lines interpreted as with +.Fl bullet +and family. +The line arguments correspond to the list's left-hand side; body +arguments correspond to the list's contents. +.Pp +The +.Fl column +list is the most complicated. +Its syntax is +.Pp +.D1 \. Ns Sx \&It Op Cm args +.Pp +where +.Cm args +are phrases, a mix of macros and text corresponding to a line column, +delimited by tabs or the special +.Sq \&Ta +pseudo-macro. +Lines subsequent the +.Sx \&It +are interpreted within the scope of the last phrase. +Calling the pseudo-macro +.Sq \&Ta +will open a new phrase scope (this must occur on a macro line to be +interpreted as a macro). Note that the tab phrase delimiter may only be +used within the +.Sx \&It +line itself. +Subsequent this, only the +.Sq \&Ta +pseudo-macro may be used to delimit phrases. +Furthermore, note that quoted sections propogate over tab-delimited +phrases on an +.Sx \&It , +for example, +.Pp +.D1 .It \(dqcol1 ; col2 ;\(dq ; +.Pp +will preserve the semicolon whitespace except for the last. +.Pp +See also +.Sx \&Bl . .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. @@ -1788,6 +1898,8 @@ line. .Ss \&Sy .Ss \&Tn .Ss \&Ud +Prints out +.Dq currently under development. .Ss \&Ux Format the UNIX name. Accepts no argument. @@ -1956,8 +2068,9 @@ 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