[BACK]Return to roff.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

File: [cvsweb.bsd.lv] / mandoc / roff.7 (download)

Revision 1.2, Sun May 16 22:28:33 2010 UTC (13 years, 10 months ago) by kristaps
Branch: MAIN
Changes since 1.1: +67 -7 lines

`ig' support in all its glory.  Try

  .ig ig
  asdf
  .ig
  fdsa
  ..

or

  .ig if
  asdf
  .if n \
  foo

for a laugh.  It all works.  Lots of regression tests supporting this
and documentation for the same.

.\"	$Id: roff.7,v 1.2 2010/05/16 22:28:33 kristaps Exp $
.\"
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" 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 16 2010 $
.Dt ROFF 7
.Os
.Sh NAME
.Nm roff
.Nd roff language reference
.Sh DESCRIPTION
The
.Nm roff
language is a general-purpose text-formatting language.  The purpose of
this document is to consistently describe those language constructs
accepted by the
.Xr mandoc 1
utility.  It is a work in progress.
.Pp
An
.Nm
document follows simple rules:  lines beginning with the control
characters
.Sq \.
or
.Sq \(aq
are parsed for macros.  Other lines are interpreted within the scope of
prior macros:
.Bd -literal -offset indent
\&.xx Macro lines change control state.
Other lines are interpreted within the current state.
.Ed
.Sh LANGUAGE SYNTAX
.Nm
documents may contain only graphable 7-bit ASCII characters, the space
character, and, in certain circumstances, the tab character.  All
manuals must have
.Ux
line terminators.
.Sh MACRO SYNTAX
Macros are arbitrary in length and begin with a control character ,
.Sq \.
or
.Sq \(aq ,
at the beginning of the line.
An arbitrary amount of whitespace may sit between the control character
and the macro name.
Thus, the following are equivalent:
.Bd -literal -offset indent
\&.if
\&.\ \ \ \&if
.Ed
.Sh REFERENCE
This section is a canonical reference of all macros, arranged
alphabetically.
.Ss \&if
Begins a conditional.
Has the following syntax:
.Pp
.Bd -literal -offset indent -compact
\&.if COND \e{\e
BODY...
\&.\e}
.Ed
.Bd -literal -offset indent -compact
\&.if COND \e{ BODY
BODY... \e}
.Ed
.Bd -literal -offset indent -compact
\&.if COND \e{ BODY
BODY...
\&.\e}
.Ed
.Bd -literal -offset indent -compact
\&.if COND \e
BODY
.Ed
.Pp
COND is a conditional (TODO: document).
.Pp
If the BODY section is begun by an escaped brace
.Sq \e{ ,
scope continues until a closing-brace macro
.Sq \.\e} .
If the BODY is not enclosed in braces, scope continues until the next
macro or word.
If the COND is followed by a BODY on the same line, whether after a
brace or not, then macros
.Em must
begin with a control character.
It is generally more intuitive, in this case, to write
.Bd -literal -offset indent
\&.if COND \e{\e
\&.foo
bar
\&.\e}
.Ed
.Pp
than having the macro follow as
.Pp
.D1 \&.if COND \e{ .foo
.Pp
The scope of a conditional is always parsed, but only executed if the
conditional evaluates to true.
.Pp
Note that text subsequent a
.Sq \&.\e}
macro is discarded.
Furthermore, if an explicit closing sequence
.Sq \e}
is specified in a free-form line, the entire line is accepted within the
scope of the prior macro, not only the text preceding the close.
.Ss \&ig
Ignore input.
Accepts the following syntax:
.Pp
.Bd -literal -offset indent -compact
\&.ig
BODY...
\&..
.Ed
.Bd -literal -offset indent -compact
\&.ig END
BODY...
\&.END
.Ed
.Pp
In the first case, input is ignored until a
.Sq \&..
macro is encountered on its own line.
In the second case, input is ignored until a
.Sq \&.END
is encountered.
Text subsequent the
.Sq \&.END
or
.Sq \&..
is discarded.
.Pp
Do not use the escape
.Sq \e
anywhere in the definition of END.
It causes very strange behaviour.
Furthermore, if you redefine a
.Nm
macro, such as
.Pp
.D1 \&.ig if
.Pp
the subsequent invocation of
.Sx \&if
will first signify the end of comment, then be invoked as a macro.
This behaviour really shouldn't be counted upon.
.Sh COMPATIBILITY
This section documents compatibility between mandoc and other other
troff implementations, at this time limited to GNU troff
.Pq Qq groff .
The term
.Qq historic groff
refers to groff versions before the
.Pa doc.tmac
file re-write
.Pq somewhere between 1.15 and 1.19 .
.Pp
.Bl -dash -compact
.It
Historic groff did not accept white-space buffering the custom END tag
for the
.Sx \&ig
macro.
.El
.Sh AUTHORS
The
.Nm
reference was written by
.An Kristaps Dzonsons Aq kristaps@bsd.lv .