* eqn(7) "delim" is undocumented (maybe)
@ 2019-12-08 8:42 Anthony J. Bentley
2020-01-07 18:32 ` Ingo Schwarze
2020-01-08 12:21 ` Ingo Schwarze
0 siblings, 2 replies; 4+ messages in thread
From: Anthony J. Bentley @ 2019-12-08 8:42 UTC (permalink / raw)
To: tech
Hi,
I can't find anyplace that documents eqn(7)'s "delim" statement (even
groff's eqn(1) doesn't really). This is widely used in the X11 manuals
and others for inline math. For example, glTexGenfv(3):
.EQ
delim $$
.EN
...
This function can be used, for example, to texture-map terrain using sea level
as a reference plane
(defined by $p sub 1$, $p sub 2$, $p sub 3$, and $p sub 4$).
I gave a shot at documenting it in the diff below... of course, open to
improvements in both correctness and clarity.
As an aside, I expected these two examples to render the same, but they
don't. Should they look the same, or am I misunderstanding how eqn(7)
works?
.\" "delim off sin(<pi>)"
.EQ
delim $$
delim off
.EN
$sin { pi }$
.\" "$sin { pi }$"
.EQ
delim $$
.EN
.EQ
delim off
.EN
$sin { pi }$
Index: eqn.7
===================================================================
RCS file: /cvs/src/share/man/man7/eqn.7,v
retrieving revision 1.11
diff -u -p -r1.11 eqn.7
--- eqn.7 23 Apr 2019 17:52:12 -0000 1.11
+++ eqn.7 8 Dec 2019 08:41:25 -0000
@@ -67,6 +67,10 @@ these are not the same as
macros, and may only be invoked as
.Sq \&.EQ .
.Pp
+Inline equations are delimited by characters set by a
+.Cm delim
+statement.
+.Pp
The equation grammar is as follows, where quoted strings are
case-sensitive literals in the input:
.Bd -literal -offset indent
@@ -178,6 +182,23 @@ statement is a synonym for
while
.Cm tdefine
is discarded.
+.It Cm delim
+Set the two characters used to delimit inline equations.
+Its syntax is as follows:
+.Pp
+.D1 Cm delim Ar param
+.Pp
+.Ar param
+is a two-character string,
+the first and second character of which delimit the start and end of inline
+equations throughout the document.
+Alternately,
+.Ar param
+may be the special string
+.Cm off ,
+which disables any previously declared delimiters, or
+.Cm on ,
+which reenables previously defined delimiters that have been turned off.
.It Cm gfont
Set the default font of subsequent output.
Its syntax is as follows:
--
To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: eqn(7) "delim" is undocumented (maybe)
2019-12-08 8:42 eqn(7) "delim" is undocumented (maybe) Anthony J. Bentley
@ 2020-01-07 18:32 ` Ingo Schwarze
2020-01-10 10:53 ` Anthony J. Bentley
2020-01-08 12:21 ` Ingo Schwarze
1 sibling, 1 reply; 4+ messages in thread
From: Ingo Schwarze @ 2020-01-07 18:32 UTC (permalink / raw)
To: Anthony J. Bentley; +Cc: tech
Hi Anthony,
Anthony J. Bentley wrote on Sun, Dec 08, 2019 at 01:42:37AM -0700:
> I can't find anyplace that documents eqn(7)'s "delim" statement
Brian W. Kernighan and Lorinda L. Cherry:
Typesetting Mathematics - User's Guide (Second Edition)
August 15, 1978
page 8, chapter 19: Shorthand for In-line Equations
> (even groff's eqn(1) doesn't really).
I think you have a point.
> This is widely used in the X11 manuals
> and others for inline math.
Definitely.
> I gave a shot at documenting it in the diff below... of course, open to
> improvements in both correctness and clarity.
>
> As an aside, I expected these two examples to render the same, but they
> don't. Should they look the same, or am I misunderstanding how eqn(7)
> works?
>
> .\" "delim off sin(<pi>)"
> .EQ
> delim $$
> delim off
> .EN
> $sin { pi }$
On first sight, that looks like a bug in mandoc.
I need to have a closer look.
Regarding your documentation patch, i'd like to do it slightly
differently.
- Let's avoid the term "inline equation". Conventionally, an
equation is called "inline" when it appears in the middle of
an *output* line. The opposite is a displayed equation.
But here, we are talking about an equation in the middle of
a (text) *input* line.
In mdoc(7) and man(7), .EQ/.EN vs. $$ has nothing to do with
inline vs. displayed. Both input forms create inline equations
by default. Both forms can be wrapped in display macros, for
example .Bd -unfilled, to achieve a display.
Admittelly, Kernighan/Cherry also talked about "in-line equations".
But that happened only because they focussed on the context of
the -ms macros, and for -ms, .EQ/.EN does indeed generate a
display by default. However, even in that context, they were
careful enough to not call $$ an "in-line equation" outright,
but rather a "shorthand for in-line equations".
- The beginning of the eqn(7) manual page is a mess. The second
and third paragraphs say about the same, and the non-standard
.Sh macro between them is completely useless. So let's delete
the section header, combine the two paragraphs, and add the
new information to it.
- I don't see the point in ".D1 Cm delim Ar param".
It says nothing new: the fact the "delim" needs to take an
argument is already obvious from the verb "set".
- But i would like to stress the conventional form "delim $$"
by giving an explicit example.
OK?
Ingo
Index: eqn.7
===================================================================
RCS file: /cvs/src/share/man/man7/eqn.7,v
retrieving revision 1.11
diff -u -p -r1.11 eqn.7
--- eqn.7 23 Apr 2019 17:52:12 -0000 1.11
+++ eqn.7 7 Jan 2020 18:27:00 -0000
@@ -44,28 +44,16 @@ specification (see
.Sx SEE ALSO
for references).
.Pp
-Equations within
-.Xr mdoc 7
-or
-.Xr man 7
-documents are enclosed by the standalone
-.Sq \&.EQ
-and
-.Sq \&.EN
-tags.
-Equations are multi-line blocks consisting of formulas and control
-statements.
-.Sh EQUATION STRUCTURE
-Each equation is bracketed by
-.Sq \&.EQ
-and
-.Sq \&.EN
-strings.
-.Em Note :
-these are not the same as
-.Xr roff 7
-macros, and may only be invoked as
-.Sq \&.EQ .
+An equation starts with an input line containing exactly the characters
+.Sq \&.EQ ,
+may contain multiple input lines, and ends with an input line
+containing exactly the characters
+.Sq \&.EN .
+Equivalently, an equation can be given in the middle of a single
+text input line by surrounding it with the equation delimiters
+defined with the
+.Cm delim
+statement.
.Pp
The equation grammar is as follows, where quoted strings are
case-sensitive literals in the input:
@@ -178,6 +166,25 @@ statement is a synonym for
while
.Cm tdefine
is discarded.
+.It Cm delim
+This statement takes a string argument consisting of two bytes,
+to be used as the opening and closing delimiters for equations
+in the middle of text input lines.
+Conventionally, the dollar sign is used for both delimiters,
+as follows:
+.Bd -literal -offset indent
+\&.EQ
+delim $$
+\&.EN
+An equation like $sin pi = 0$ can now be entered
+in the middle of a text input line.
+.Ed
+.Pp
+The special statement
+.Cm delim off
+temporarily disables previously declared delimiters and
+.Cm delim on
+reenables them.
.It Cm gfont
Set the default font of subsequent output.
Its syntax is as follows:
--
To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: eqn(7) "delim" is undocumented (maybe)
2019-12-08 8:42 eqn(7) "delim" is undocumented (maybe) Anthony J. Bentley
2020-01-07 18:32 ` Ingo Schwarze
@ 2020-01-08 12:21 ` Ingo Schwarze
1 sibling, 0 replies; 4+ messages in thread
From: Ingo Schwarze @ 2020-01-08 12:21 UTC (permalink / raw)
To: Anthony J. Bentley; +Cc: tech
Hi Anthony,
Anthony J. Bentley wrote on Sun, Dec 08, 2019 at 01:42:37AM -0700:
> As an aside, I expected these two examples to render the same, but they
> don't. Should they look the same, or am I misunderstanding how eqn(7)
> works?
>
> .\" "delim off sin(<pi>)"
> .EQ
> delim $$
> delim off
> .EN
> $sin { pi }$
This was is indeed misparsed and consequently misrendered
by mandoc(1); fixed by the following commit.
> .\" "$sin { pi }$"
> .EQ
> delim $$
> .EN
> .EQ
> delim off
> .EN
> $sin { pi }$
Thanks for reporting,
Ingo
Log Message:
-----------
Skip whitespace before tokens, too.
Bug found by bentley@ with input like "delim $$ delim off".
Modified Files:
--------------
mandoc:
eqn.c
mandoc/regress/eqn/delim:
Makefile
basic.in
basic.out_ascii
Added Files:
-----------
mandoc/regress/eqn/delim:
basic.out_utf8
Revision Data
-------------
Index: eqn.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/eqn.c,v
retrieving revision 1.83
retrieving revision 1.84
diff -Leqn.c -Leqn.c -u -p -r1.83 -r1.84
--- eqn.c
+++ eqn.c
@@ -1,7 +1,7 @@
/* $Id$ */
/*
* Copyright (c) 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2014, 2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2014,2015,2017,2018,2020 Ingo Schwarze <schwarze@openbsd.org>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
@@ -399,6 +399,14 @@ eqn_next(struct eqn_node *ep, enum parse
case '"':
quoted = 1;
break;
+ case ' ':
+ case '\t':
+ case '~':
+ case '^':
+ if (quoted)
+ break;
+ ep->start++;
+ continue;
default:
break;
}
@@ -669,7 +677,7 @@ eqn_parse(struct eqn_node *ep)
if (ep->data == NULL)
return;
- ep->start = ep->end = ep->data + strspn(ep->data, " ^~");
+ ep->start = ep->end = ep->data;
next_tok:
tok = eqn_next(ep, MODE_TOK);
Index: Makefile
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/eqn/delim/Makefile,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lregress/eqn/delim/Makefile -Lregress/eqn/delim/Makefile -u -p -r1.2 -r1.3
--- regress/eqn/delim/Makefile
+++ regress/eqn/delim/Makefile
@@ -1,6 +1,7 @@
-# $OpenBSD: Makefile,v 1.2 2020/01/08 10:50:54 schwarze Exp $
+# $OpenBSD: Makefile,v 1.3 2020/01/08 12:09:14 schwarze Exp $
REGRESS_TARGETS = basic
+UTF8_TARGETS = basic
GOPTS = -e
SKIP_GROFF =
--- /dev/null
+++ regress/eqn/delim/basic.out_utf8
@@ -0,0 +1,10 @@
+DELIM-BASIC(1) General Commands Manual DELIM-BASIC(1)
+
+N\bNA\bAM\bME\bE
+ d\bde\bel\bli\bim\bm-\b-b\bba\bas\bsi\bic\bc – inline eqn delimiters
+
+D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
+ initial text α inline β γ inline [delta] ε inline ζ inline $eta$ inline θ
+ final text
+
+OpenBSD January 8, 2020 OpenBSD
Index: basic.out_ascii
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/eqn/delim/basic.out_ascii,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lregress/eqn/delim/basic.out_ascii -Lregress/eqn/delim/basic.out_ascii -u -p -r1.4 -r1.5
--- regress/eqn/delim/basic.out_ascii
+++ regress/eqn/delim/basic.out_ascii
@@ -5,6 +5,6 @@ N\bNA\bAM\bME\bE
D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
initial text <alpha> inline <beta> <gamma> inline [delta] <epsilon>
- inline <zeta> final text
+ inline <zeta> inline $eta$ inline <theta> final text
OpenBSD January 8, 2020 OpenBSD
Index: basic.in
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/eqn/delim/basic.in,v
retrieving revision 1.3
retrieving revision 1.4
diff -Lregress/eqn/delim/basic.in -Lregress/eqn/delim/basic.in -u -p -r1.3 -r1.4
--- regress/eqn/delim/basic.in
+++ regress/eqn/delim/basic.in
@@ -1,4 +1,4 @@
-.\" $OpenBSD: basic.in,v 1.3 2020/01/08 10:58:09 schwarze Exp $
+.\" $OpenBSD: basic.in,v 1.4 2020/01/08 12:09:14 schwarze Exp $
.Dd $Mdocdate$
.Dt DELIM-BASIC 1
.Os
@@ -19,4 +19,13 @@ inline [delta]
delim onepsilon
.EN
inline [zeta]
+.EQ
+delim $$
+delim off
+.EN
+inline $eta$
+.EQ
+delim on
+.EN
+inline $theta$
final text
--
To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: eqn(7) "delim" is undocumented (maybe)
2020-01-07 18:32 ` Ingo Schwarze
@ 2020-01-10 10:53 ` Anthony J. Bentley
0 siblings, 0 replies; 4+ messages in thread
From: Anthony J. Bentley @ 2020-01-10 10:53 UTC (permalink / raw)
To: Ingo Schwarze; +Cc: tech
Hi Ingo,
Ingo Schwarze writes:
> Regarding your documentation patch, i'd like to do it slightly
> differently.
Your points make sense, and your patch is ok with me.
--
Anthony J. Bentley
--
To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2020-01-10 10:53 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-12-08 8:42 eqn(7) "delim" is undocumented (maybe) Anthony J. Bentley
2020-01-07 18:32 ` Ingo Schwarze
2020-01-10 10:53 ` Anthony J. Bentley
2020-01-08 12:21 ` Ingo Schwarze
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).