mandoc/mdoc.7 - diff

Return to mdoc.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.32 and 1.36

-version 1.32, 2009/06/22 13:09:17
+version 1.36, 2009/07/04 11:04:07
 Line 28  The
 Line 28  The
 Line 28  The
  language is used to format
  .Bx
  .Ux
- manuals.  In this reference document, we describe the syntax, ontology
+ manuals.  In this reference document, we describe the syntax and
- and structure of the
+ structure of the
  .Nm
  language.  Our reference implementation is
  .Xr mandoc 1 .
 Line 136  or a single one-character sequence.
 Line 136  or a single one-character sequence.
 Line 136  or a single one-character sequence.
  .Pp
  Characters may alternatively be escaped by a slash-asterisk,
  .Sq \e* ,
- with the same combinations as described above.  This form is deprecated.
+ with the same combinations as described above.
+ .Pp
+ Terms may also be text-decorated using the
+ .Sq \ef
+ escape followed by a text-decoration letter: B (bold), I, (italic), or P
+ and R (Roman, or reset).  This form is not recommended.
+ .\" SUB-SECTION
+ .Ss Whitespace
+ Unless in literal mode or specifically escaped, consecutive blocks of
+ whitespace are pruned from input.  These are later re-added, if
+ applicable, by a front-end utility such as
+ .Xr mandoc 1 .
  .\" SECTION
  .Sh STRUCTURE
- Macros are classified in an ontology described by their scope rules.
+ Each
- Some macros are allowed to deviate from their classifications to
+ .Nm
- preserve backward-compatibility with old macro combinations still found
+ document must begin with the document prologue, containing, in order,
- in the manual corpus.  These are specifically noted on a per-macro
+ .Sq \&.Dd ,
- basis.
+ .Sq \&.Dt ,
+ and
+ .Sq \&.Os .
+ Following these, the document body must begin with the NAME section
+ containing at least one
+ .Sq \&.Nm
+ followed by a
+ .Sq \&.Nd
+ macro.
+ .Pp
+ At least one free-form or macro line must follow this prologue.
+ .\"
+ .Ss Classification
+ Macros are classified by their scope rules.  Some macros are allowed to
+ deviate from their classifications to preserve backward-compatibility
+ with old macro combinations still found in the manual corpus.  These are
+ specifically noted on a per-macro basis.
  .\" SUB-SECTION
  .Ss Scope
  .Bl -inset
-Line 279  In-lines have \(>=0 scoped arguments.
+Line 306  In-lines have \(>=0 scoped arguments.
 Line 279  In-lines have \(>=0 scoped arguments.
 Line 306  In-lines have \(>=0 scoped arguments.
  \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
  .Ed
  .\" SECTION
- .Sh STRUCTURE
- Each
- .Nm
- document must begin with the document prologue, containing, in order,
- .Sq \&.Dd ,
- .Sq \&.Dt ,
- and
- .Sq \&.Os .
- .Pp
- Following these, the document body must begin with the NAME section
- containing at least one
- .Sq \&.Nm
- followed by a
- .Sq \&.Nd
- macro.
- .\" SECTION
  .Sh MACROS
  This section contains a complete list of all
  .Nm
- macros, arranged ontologically.  A
+ macros, arranged by classification.  A
  .Qq callable
  macro is invoked subsequent to the initial macro-line macro.  A
  .Qq parsable
-Line 516  file re-write
+Line 527  file re-write
 Line 516  file re-write
 Line 527  file re-write
  .Bl -dash -compact
  .\" LIST-ITEM
  .It
+ The \-width argument to
+ .Sq \&.Bl
+ respects indent and indent-two (groff does too, but does not document
+ the fact).
+ .\" LIST-ITEM
+ .It
+ Some character sequences in groff are not handled depending on escape
+ style, e.g.,
+ .Sq \e(ba
+ and
+ .Sq \e*(Ba
+ may not be interchanged.  This is no longer the case: all character
+ sequences resolve to the same symbol, regardless the escape style.
+ .\" LIST-ITEM
+ .It
+ Blocks of whitespace are stripped from both macro and free-form text
+ lines (except when in literal mode), while groff would retain whitespace
+ in free-form text lines.
+ .\" LIST-ITEM
+ .It
  Historic groff has many un-callable macros.  Most of these (excluding
  some block-level macros) are now callable, conforming to the
  non-historic groff version.
  .\" LIST-ITEM
  .It
  The vertical bar
- .Sq \(Ba
+ .Sq \(ba
  made historic groff
  .Qq go orbital
  but is a proper delimiter in this implementation.
-Line 551  incorrectly by following it with a reserved character
+Line 582  incorrectly by following it with a reserved character
 Line 551  incorrectly by following it with a reserved character
 Line 582  incorrectly by following it with a reserved character
  delimiter to render.  This is not supported.
  .\" LIST-ITEM
  .It
- If an special-character control character
+ If an special-character control character is escaped
- .Sq \e
+ .Sq \e\e ,
- is escaped, it will
+ it will obviously not render the subsequent sequence.  Even newer
- obviously not render the sequence.  Even newer versions of groff seem to
+ versions of groff seem to dither on this.
- dither on this.
  .El
  .\" SECTION
  .Sh SEE ALSO

CVSweb