From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from krisdoz.my.domain (kristaps@localhost [127.0.0.1]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p7HMGW14012941 for ; Wed, 17 Aug 2011 18:16:33 -0400 (EDT) Received: (from kristaps@localhost) by krisdoz.my.domain (8.14.3/8.14.3/Submit) id p7HMGW2p032073; Wed, 17 Aug 2011 18:16:32 -0400 (EDT) Date: Wed, 17 Aug 2011 18:16:32 -0400 (EDT) Message-Id: <201108172216.p7HMGW2p032073@krisdoz.my.domain> X-Mailinglist: mdocml-source Reply-To: source@mdocml.bsd.lv MIME-Version: 1.0 From: kristaps@mdocml.bsd.lv To: source@mdocml.bsd.lv Subject: mdocml: Sync man.7's LANGUAGE SYNTAX (was INPUT ENCODING) with mdoc.7. X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Log Message: ----------- Sync man.7's LANGUAGE SYNTAX (was INPUT ENCODING) with mdoc.7. While here, fix the scaling widths example that incorrectly used `br' (it now correctly uses `sp'). Modified Files: -------------- mdocml: man.7 Revision Data ------------- Index: man.7 =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man.7,v retrieving revision 1.102 retrieving revision 1.103 diff -Lman.7 -Lman.7 -u -p -r1.102 -r1.103 --- man.7 +++ man.7 @@ -49,28 +49,33 @@ prior macros: \&.SH Macro lines change control state. Other lines are interpreted within the current state. .Ed -.Sh INPUT ENCODING +.Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space character, and the tab character. -.Pp -Blank lines are acceptable; where found, the output will assert a -vertical space. -.Pp -If the first character of a line is a space, that line is printed -with a leading newline. +The back-space character +.Sq \e +indicates the start of an escape sequence for +.Sx Comments , +.Sx Predefined Strings , +and +.Sx Special Characters . .Ss Comments -Text following a +Text following an escaped double-quote .Sq \e\*q , -whether in a macro or free-form text line, is ignored to the end of +whether in a macro or text line, is ignored to the end of line. -A macro line with only a control character and comment escape, -.Sq \&.\e\*q , +A macro line beginning with a control character and comment escape +.Sq \&.\e\*q is also ignored. -Macro lines with only a control character and optionally whitespace are +Furthermore, +macro lines with only a control character and optional trailing +whitespace are stripped from input. .Ss Special Characters -Special characters may occur in both macro and free-form lines. +Special characters are used to encode special glyphs and are rendered +differently across output media. +They may occur in both macro and text lines. Sequences begin with the escape character .Sq \e followed by either an open-parenthesis @@ -79,25 +84,25 @@ for two-character sequences; an open-bra .Sq \&[ for n-character sequences (terminated at a close-bracket .Sq \&] ) ; -or a single one-character sequence. +or a single one character sequence. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \e(em +em dash +.It \ee +backslash +.El +.Pp See .Xr mandoc_char 7 for a complete list. -Examples include -.Sq \e(em -.Pq em-dash -and -.Sq \ee -.Pq back-slash . .Ss Text Decoration Terms may be text-decorated using the .Sq \ef -escape followed by an indicator: B (bold), I (italic), R (Roman), or P +escape followed by an indicator: B (bold), I (italic), R (regular), or P (revert to previous mode): -.Pp -.D1 \efBbold\efR \efIitalic\efP -.Pp -A numerical representation 3, 2, or 1 (bold, italic, and Roman, +A numerical representation 3, 2, or 1 (bold, italic, and regular, respectively) may be used instead. A text decoration is only valid, if specified in free-form text, until the next macro invocation; if specified within a macro, it's only valid @@ -109,26 +114,80 @@ open and close a font scope with each ar The .Sq \ef attribute is forgotten when entering or exiting a macro block. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \efBbold\efR +write in bold, then switch to regular +.It \efIitalic\efP +write in italic, then return to previous +.El +.Ss Predefined Strings +Predefined strings, like +.Sx Special Characters , +mark special output glyphs. +Predefined strings are escaped with the slash-asterisk, +.Sq \e* : +single-character +.Sq \e*X , +two-character +.Sq \e*(XX , +and N-character +.Sq \e*[N] . +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \e*(Am +ampersand +.It \e*(Ba +vertical bar +.El +.Pp +These strings are set using +.Xr roff 7 , +although +.Nm +consists of several pre-set escapes listed in +.Xr mandoc_char 7 . .Ss Whitespace Whitespace consists of the space character. -In free-form lines, whitespace is preserved within a line; unescaped -trailing spaces are stripped from input (unless in a literal context). -Blank free-form lines, which may include spaces, are permitted and -rendered as an empty line. -.Pp +In text lines, whitespace is preserved within a line. In macro lines, whitespace delimits arguments and is discarded. -If arguments are quoted, whitespace within the quotes is retained. -.Ss Scaling Widths -Many macros support scaled widths for their arguments, such as -stipulating a two-inch paragraph indentation with the following: -.Bd -literal -offset indent -\&.HP 2i -.Ed .Pp -The syntax for scaled widths is -.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? , +Unescaped trailing spaces are stripped from text line input unless in a +literal context. +In general, trailing whitespace on any input line is discouraged for +reasons of portability. +In the rare case that a blank character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . +.Pp +If the first character of a text line is a space, that line is printed +with a leading newline. +.Ss Quotation +Macro arguments may be quoted with double-quotes; in this case, +whitespace within the quotes is retained as part of the argument. +.Pp +A quoted argument begins with a double-quote preceded by whitespace. +The next double-quote not pairwise adjacent to another double-quote +terminates the literal, regardless of surrounding whitespace. +.Pp +In unquoted arguments, space characters can alternatively be included +by preceding them with a backslash +.Pq Sq \e\~ , +but quoting is usually better for clarity. +.Pp +Note that any quoted text, even if it would cause a macro invocation +when unquoted, is considered literal text. +.Pp +In text lines, quotes are regarded as opaque text. +.Ss Scaling Widths +Many macros support scaled widths for their arguments. +The syntax for a scaled width is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , where a decimal must be preceded or proceeded by at least one digit. Negative numbers, while accepted, are truncated to zero. +.Pp The following scaling units are accepted: .Pp .Bl -tag -width Ds -offset indent -compact @@ -168,6 +227,8 @@ Using anything other than or .Sq v is necessarily non-portable across output media. +See +.Sx COMPATIBILITY . .Pp If a scaling unit is not provided, the numerical value is interpreted under the default rules of @@ -175,15 +236,19 @@ under the default rules of for vertical spaces and .Sq u for horizontal ones. -.Em Note : -this differs from -.Xr mdoc 7 , -which, if a unit is not provided, will instead interpret the string as -literal text. +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It \&.HP 2i +two-inch tagged list indentation +.Pq see Sx \&HP +.It \&.sp 2v +two vertical spaces +.Pq see Sx \&sp +.El .Ss Sentence Spacing -When composing a manual, make sure that sentences end at the end of -a line. -By doing so, front-ends will be able to apply the proper amount of +Sentences should terminate at the end of an input line. +By doing this, a formatter will be able to apply the proper amount of spacing after the end of sentence (unescaped) period, exclamation mark, or question mark followed by zero or more non-sentence closing delimiters @@ -193,6 +258,13 @@ delimiters .Sq \&' , .Sq \&" .Pc . +.Pp +Examples: +.Bd -literal -offset indent -compact +Do not end sentences mid-line like this. Instead, +end a sentence like this. +A new sentence gets a new line. +.Ed .Sh MANUAL STRUCTURE Each .Nm -- To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv