From d149835038f31ecf0427d98e92657bb3746e1dd0 Mon Sep 17 00:00:00 2001 From: Kristaps Dzonsons Date: Tue, 4 Jan 2011 23:32:21 +0000 Subject: Moved table stuff from roff.7 into the new tbl.7 (suggested by Jason McIntyre). Added cross-links to tbl.7 from other manuals. --- Makefile | 17 ++-- man.7 | 4 +- mandoc.1 | 4 +- mdoc.7 | 3 + roff.7 | 207 +----------------------------------------- tbl.7 | 312 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 335 insertions(+), 212 deletions(-) create mode 100644 tbl.7 diff --git a/Makefile b/Makefile index 13cb9e3e..20416b85 100644 --- a/Makefile +++ b/Makefile @@ -99,30 +99,30 @@ HEADS = mdoc.h libmdoc.h man.h libman.h term.h \ GSGMLS = mandoc.1.sgml mdoc.3.sgml mdoc.7.sgml \ mandoc_char.7.sgml man.7.sgml man.3.sgml roff.7.sgml \ - roff.3.sgml + roff.3.sgml tbl.7.sgml SGMLS = index.sgml XHTMLS = mandoc.1.xhtml mdoc.3.xhtml \ man.3.xhtml mdoc.7.xhtml man.7.xhtml mandoc_char.7.xhtml \ - roff.7.xhtml roff.3.xhtml + roff.7.xhtml roff.3.xhtml tbl.7.xhtml HTMLS = ChangeLog.html index.html man.h.html mdoc.h.html \ mandoc.h.html roff.h.html mandoc.1.html mdoc.3.html \ man.3.html mdoc.7.html man.7.html mandoc_char.7.html \ - roff.7.html roff.3.html + roff.7.html roff.3.html tbl.7.html PSS = mandoc.1.ps mdoc.3.ps man.3.ps mdoc.7.ps man.7.ps \ - mandoc_char.7.ps roff.7.ps roff.3.ps + mandoc_char.7.ps roff.7.ps roff.3.ps tbl.7.ps PDFS = mandoc.1.pdf mdoc.3.pdf man.3.pdf mdoc.7.pdf man.7.pdf \ - mandoc_char.7.pdf roff.7.pdf roff.3.pdf + mandoc_char.7.pdf roff.7.pdf roff.3.pdf tbl.7.pdf XSLS = ChangeLog.xsl TEXTS = mandoc.1.txt mdoc.3.txt man.3.txt mdoc.7.txt man.7.txt \ mandoc_char.7.txt ChangeLog.txt \ - roff.7.txt roff.3.txt + roff.7.txt roff.3.txt tbl.7.txt EXAMPLES = example.style.css @@ -135,7 +135,7 @@ MD5S = mdocml-$(VERSION).md5 TARGZS = mdocml-$(VERSION).tar.gz MANS = mandoc.1 mdoc.3 mdoc.7 mandoc_char.7 man.7 \ - man.3 roff.7 roff.3 + man.3 roff.7 roff.3 tbl.7 BINS = mandoc @@ -179,7 +179,7 @@ install: mkdir -p $(DESTDIR)$(MANDIR)/man7 $(INSTALL_PROGRAM) mandoc $(DESTDIR)$(BINDIR) $(INSTALL_MAN) mandoc.1 $(DESTDIR)$(MANDIR)/man1 - $(INSTALL_MAN) man.7 mdoc.7 roff.7 mandoc_char.7 $(DESTDIR)$(MANDIR)/man7 + $(INSTALL_MAN) man.7 mdoc.7 roff.7 tbl.7 mandoc_char.7 $(DESTDIR)$(MANDIR)/man7 $(INSTALL_DATA) example.style.css $(DESTDIR)$(EXAMPLEDIR) uninstall: @@ -187,6 +187,7 @@ uninstall: rm -f $(DESTDIR)$(MANDIR)/man1/mandoc.1 rm -f $(DESTDIR)$(MANDIR)/man7/mdoc.7 rm -f $(DESTDIR)$(MANDIR)/man7/roff.7 + rm -f $(DESTDIR)$(MANDIR)/man7/tbl.7 rm -f $(DESTDIR)$(MANDIR)/man7/man.7 rm -f $(DESTDIR)$(MANDIR)/man7/mandoc_char.7 rm -f $(DESTDIR)$(EXAMPLEDIR)/example.style.css diff --git a/man.7 b/man.7 index 52391b90..be88f6bb 100644 --- a/man.7 +++ b/man.7 @@ -913,7 +913,9 @@ In GNU troff, this would result in strange behaviour. .Xr man 1 , .Xr mandoc 1 , .Xr mandoc_char 7 , -.Xr mdoc 7 +.Xr mdoc 7 , +.Xr roff 7 , +.Xr tbl 7 .Sh HISTORY The .Nm diff --git a/mandoc.1 b/mandoc.1 index aef520fb..902085f1 100644 --- a/mandoc.1 +++ b/mandoc.1 @@ -531,7 +531,9 @@ lists render similarly. .Sh SEE ALSO .Xr man 7 , .Xr mandoc_char 7 , -.Xr mdoc 7 +.Xr mdoc 7 , +.Xr roff 7 , +.Xr tbl 7 .Sh AUTHORS The .Nm diff --git a/mdoc.7 b/mdoc.7 index c7d230f1..e927c18e 100644 --- a/mdoc.7 +++ b/mdoc.7 @@ -2903,7 +2903,10 @@ This is not supported by mandoc. .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 , +.Xr man 7 , .Xr mandoc_char 7 +.Xr roff 7 , +.Xr tbl 7 .Sh HISTORY The .Nm diff --git a/roff.7 b/roff.7 index 12a709d7..134bae5e 100644 --- a/roff.7 +++ b/roff.7 @@ -546,201 +546,9 @@ See .Sx \&TS . .Ss \&TS Begin a table, which formats input in aligned rows and columns. -A table consists of an optional single line of table options terminated -by a semicolon, followed by one or more lines of layout specification -terminated by a period, then table data. -A table block may also include -.Nm , -.Xr mdoc 7 , -or -.Xr man 7 -macros. -Example: -.Bd -literal -offset indent -\&.TS -box tab(:); \e" Table-wide options. -c | c \e" Layout for first line. -| c | c. \e" Layout for all subsequent lines. -1:2 \e" Data... -3:4 -\&.TE -.Ed -.Pp -Table data is -.Em pre-processed , -that is, data rows are parsed then inserted into the underlying stream -of input data. -This allows data rows to be interspersed by arbitrary macros, such as -.Bd -literal -offset indent -\&.TS -tab(:); -c c c. -1:2:3 -\&.Ao -3:2:1 -\&.Ac -\&.TE -.Ed -.Pp -in the case of -.Xr mdoc 7 -or -.Bd -literal -offset indent -\&.TS -tab(:); -c c c. -\&.ds ab 2 -1:\e*(ab:3 -\&.I -3:2:1 -\&.TE -.Ed -.Pp -in the case of -.Xr man 7 . -.Pp -The first line of a table consists of its options, which consists of -space-separated keys and modifiers terminated by a semicolon. -If the first line does not have a terminating semicolon, it is assumed -that no options are specified and instead a layout is processed. -Some options accept arguments enclosed by paranthesis. -The following case-insensitive options are available: -.Bl -tag -width Ds -.It Cm center -This option is not supported by -.Xr mandoc 1 . -This may also be invoked with -.Cm centre . -.It Cm delim -Accepts a two-character argument. -This option is not supported by -.Xr mandoc 1 . -.It Cm expand -This option is not supported by -.Xr mandoc 1 . -.It Cm box -Draw a single-line box around the table. -This may also be invoked with -.Cm frame . -.It Cm doublebox -Draw a double-line box around the table. -This may also be invoked with -.Cm doubleframe . -.It Cm allbox -This option is not supported by -.Xr mandoc 1 . -.It Cm tab -Accepts a single-character argument. -This character is used a delimiter between data cells, which otherwise -defaults to the tab character. -.It Cm linesize -Accepts a natural number (all digits). -This option is not supported by -.Xr mandoc 1 . -.It Cm nokeep -This option is not supported by -.Xr mandoc 1 . -.It Cm decimalpoint -Accepts a single-character argument. -This character will be used as the decimal point with the -.Cm n -layout key. -This option is not supported by -.Xr mandoc 1 . -.It Cm nospaces -This option is not supported by -.Xr mandoc 1 . -.El -.Pp -The table layout follows table options, except in the case of -.Sx \&T& , -where it immediately procedes invocation. -Layout specifies how data rows are displayed on output. -Each layout line corresponds to a line of data; the last layout line -applies to all remaining data lines. -Layout lines may also be separated by a comma. -Each layout cell consists of one of the following case-insensitive keys: -.Bl -tag -width Ds -.It Cm c -Centre a literal string within its column. -.It Cm r -Right-justify a literal string within its column. -.It Cm l -Left-justify a literal string within its column. -.It Cm n -Justify a number around its decimal point. -If the decimal point is not found on the number, it's assumed to trail -the number. -.It Cm s -This option is not supported by -.Xr mandoc 1 . -.It Cm a -This option is not supported by -.Xr mandoc 1 . -.It Cm ^ -This option is not supported by -.Xr mandoc 1 . -.It Cm \- -Replace the data cell (its contents will be lost) with a single -horizontal line. -This may also be invoked with -.Cm _ . -.It Cm = -Replace the data cell (its contents will be lost) with a double -horizontal line. -.It Cm \(ba -Emit a vertical bar instead of data. -.It Cm \(ba\(ba -Emit a double-vertical bar instead of data. -.El -.Pp -For example, following layout specifies a centre-justified column of -minimum width 10, followed by vertical bar, followed by a left-justified -column of minimum width 10, another vertical bar, then a column -justified about the decimal point in numbers: -.Pp -.Dl c10 | l10 | n -.Pp -Keys may be followed by a set of modifiers. -A modifier is either a modifier key or a natural number for specifying -spacing. -The following case-insensitive modifier keys are available: -.Cm z , -.Cm u , -.Cm e , -.Cm t , -.Cm d , -.Cm f , -.Cm b , -.Cm i , -.Cm b , -and -.Cm i . -All of these are ignored by -.Xr mandoc 1 . -.Pp -The data section follows the last layout row. -By default, cells in a data section are delimited by a tab. -This behaviour may be changed with the -.Cm tab -option. -If -.Cm _ -or -.Cm = -is specified, a single or double line, respectively, is drawn across the -data field. -If -.Cm \e- -or -.Cm \e= -is specified, a line is drawn within the data field (i.e., terminating -within the cell and not draw to the border). -If the last cell of a line is -.Cm T{ , -all subsequent lines are included as part of the cell until -.Cm T} -is specified on its own line. +See +.Xr tbl 7 +for a description of the tbl language. .Sh COMPATIBILITY This section documents compatibility between mandoc and other other .Nm @@ -771,13 +579,8 @@ using the next-line syntax. .Xr mandoc 1 , .Xr man 7 , .Xr mandoc_char 7 , -.Xr mdoc 7 -.Rs -.%A M. E. Lesk -.%T Tbl\(emA Program to Format Tables -.%D June 11, 1976 -.%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps -.Re +.Xr mdoc 7 , +.Xr tbl 7 .Rs .%A Joseph F. Ossanna .%A Brian W. Kernighan diff --git a/tbl.7 b/tbl.7 new file mode 100644 index 00000000..ec37fea7 --- /dev/null +++ b/tbl.7 @@ -0,0 +1,312 @@ +.\" $Id$ +.\" +.\" Copyright (c) 2010 Kristaps Dzonsons +.\" +.\" 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$ +.Dt TBL 7 +.Os +.Sh NAME +.Nm tbl +.Nd tbl language reference for mandoc +.Sh DESCRIPTION +The +.Nm tbl +language is a table-formatting language. +It is used within +.Xr mdoc 7 +and +.Xr man 7 +.Ux +manual pages. +This manual describes the subset of the +.Nm +language accepted by the +.Xr mandoc 1 +utility. +.Pp +Tables within +.Xr mdoc 7 +or +.Xr man 7 +are enclosed by the +.Sq TS +and +.Sq TE +macro tags, whose precise syntax is documented in +.Xr roff 7 . +Tables consist of a series of options on a single line, followed by the +table layout, followed by data. +.Pp +For example, the following creates a boxed table with digits centered in +the cells. +.Bd -literal -offset indent +\&.TS +tab(:) box; +c5 c5 c5. +1:2:3 +4:5:6 +\&.TE +.Ed +.Pp +When formatted, the following output is produced: +.Bd -filled -offset indent -compact +.TS +tab(:) box; +c5 c5 c5. +1:2:3 +4:5:6 +.TE +.Ed +.Sh TABLE STRUCTURE +Tables are enclosed by the +.Sq TS +and +.Sq TE +.Xr roff 7 +macros. +A table consists of an optional single line of table options terminated +by a semicolon, followed by one or more lines of layout specification +terminated by a period, then table data. +All input must be 7-bit ASCII. +Example: +.Bd -literal -offset indent +\&.TS +box tab(:); +c | c +| c | c. +1:2 +3:4 +\&.TE +.Ed +.Pp +Table data is +.Em pre-processed , +that is, data rows are parsed then inserted into the underlying stream +of input data. +This allows data rows to be interspersed by arbitrary +.Xr roff 7 , +.Xr mdoc 7 , +and +.Xr man 7 +macros such as +.Bd -literal -offset indent +\&.TS +tab(:); +c c c. +1:2:3 +\&.Ao +3:2:1 +\&.Ac +\&.TE +.Ed +.Pp +in the case of +.Xr mdoc 7 +or +.Bd -literal -offset indent +\&.TS +tab(:); +c c c. +\&.ds ab 2 +1:\e*(ab:3 +\&.I +3:2:1 +\&.TE +.Ed +.Pp +in the case of +.Xr man 7 . +.Ss Table Options +The first line of a table consists of its options, which consists of +space-separated keys and modifiers terminated by a semicolon. +If the first line does not have a terminating semicolon, it is assumed +that no options are specified and instead a layout is processed. +Some options accept arguments enclosed by paranthesis. +The following case-insensitive options are available: +.Bl -tag -width Ds +.It Cm center +This option is not supported by +.Xr mandoc 1 . +This may also be invoked with +.Cm centre . +.It Cm delim +Accepts a two-character argument. +This option is not supported by +.Xr mandoc 1 . +.It Cm expand +This option is not supported by +.Xr mandoc 1 . +.It Cm box +Draw a single-line box around the table. +This may also be invoked with +.Cm frame . +.It Cm doublebox +Draw a double-line box around the table. +This may also be invoked with +.Cm doubleframe . +.It Cm allbox +This option is not supported by +.Xr mandoc 1 . +.It Cm tab +Accepts a single-character argument. +This character is used a delimiter between data cells, which otherwise +defaults to the tab character. +.It Cm linesize +Accepts a natural number (all digits). +This option is not supported by +.Xr mandoc 1 . +.It Cm nokeep +This option is not supported by +.Xr mandoc 1 . +.It Cm decimalpoint +Accepts a single-character argument. +This character will be used as the decimal point with the +.Cm n +layout key. +This option is not supported by +.Xr mandoc 1 . +.It Cm nospaces +This option is not supported by +.Xr mandoc 1 . +.El +.Ss Table Layout +The table layout follows table options, except in the case of +.Sx \&T& , +where it immediately procedes invocation. +Layout specifies how data rows are displayed on output. +Each layout line corresponds to a line of data; the last layout line +applies to all remaining data lines. +Layout lines may also be separated by a comma. +Each layout cell consists of one of the following case-insensitive keys: +.Bl -tag -width Ds +.It Cm c +Centre a literal string within its column. +.It Cm r +Right-justify a literal string within its column. +.It Cm l +Left-justify a literal string within its column. +.It Cm n +Justify a number around its decimal point. +If the decimal point is not found on the number, it's assumed to trail +the number. +.It Cm s +This option is not supported by +.Xr mandoc 1 . +.It Cm a +This option is not supported by +.Xr mandoc 1 . +.It Cm ^ +This option is not supported by +.Xr mandoc 1 . +.It Cm \- +Replace the data cell (its contents will be lost) with a single +horizontal line. +This may also be invoked with +.Cm _ . +.It Cm = +Replace the data cell (its contents will be lost) with a double +horizontal line. +.It Cm \(ba +Emit a vertical bar instead of data. +.It Cm \(ba\(ba +Emit a double-vertical bar instead of data. +.El +.Pp +For example, following layout specifies a centre-justified column of +minimum width 10, followed by vertical bar, followed by a left-justified +column of minimum width 10, another vertical bar, then a column +justified about the decimal point in numbers: +.Pp +.Dl c10 | l10 | n +.Pp +Keys may be followed by a set of modifiers. +A modifier is either a modifier key or a natural number for specifying +spacing. +The following case-insensitive modifier keys are available: +.Cm z , +.Cm u , +.Cm e , +.Cm t , +.Cm d , +.Cm f , +.Cm b , +.Cm i , +.Cm b , +and +.Cm i . +All of these are ignored by +.Xr mandoc 1 . +.Ss Table Data +The data section follows the last layout row. +By default, cells in a data section are delimited by a tab. +This behaviour may be changed with the +.Cm tab +option. +If +.Cm _ +or +.Cm = +is specified, a single or double line, respectively, is drawn across the +data field. +If +.Cm \e- +or +.Cm \e= +is specified, a line is drawn within the data field (i.e., terminating +within the cell and not draw to the border). +If the last cell of a line is +.Cm T{ , +all subsequent lines are included as part of the cell until +.Cm T} +is specified on its own line. +.Sh COMPATIBILITY +This section documents compatibility between mandoc and other +.Nm +implementations, at this time limited to GNU tbl. +.Pp +.Bl -dash -compact +.It +In GNU tbl, comments and macros are disallowed prior to the data block +of a table. +The +.Xr mandoc 1 +implementation allows them. +.El +.Sh SEE ALSO +.Xr mandoc 1 , +.Xr mandoc_char 7 , +.Xr roff 7 , +.Xr man 7 , +.Xr mdoc 7 +.Rs +.%A M. E. Lesk +.%T Tbl\(emA Program to Format Tables +.%D June 11, 1976 +.Re +.Sh HISTORY +The tbl utility, a preprocessor for troff, was originally written by M. +E. Lesk at Bell Labs in 1975. +The GNU reimplementation of tbl, part of the groff package, was released +in 1990 by James Clark. +A standalone tbl implementation was written by Kristaps Dzonsons in +2010. +This formed the basis of the implementation that is part of the +.Xr mandoc 1 +utility. +.Sh AUTHORS +This partial +.Nm +reference was written by +.An Kristaps Dzonsons Aq kristaps@bsd.lv . -- cgit