From: Ingo Schwarze <schwarze@usta.de>
To: "Anthony J. Bentley" <anthony@anjbe.name>
Cc: tech@mandoc.bsd.lv
Subject: Re: eqn(7) "delim" is undocumented (maybe)
Date: Tue, 7 Jan 2020 19:32:23 +0100 [thread overview]
Message-ID: <20200107183223.GA59295@athene.usta.de> (raw)
In-Reply-To: <38466-1575794557.527458@DkTY.Emny.Ld6w>
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
next prev parent reply other threads:[~2020-01-07 18:32 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-12-08 8:42 Anthony J. Bentley
2020-01-07 18:32 ` Ingo Schwarze [this message]
2020-01-10 10:53 ` Anthony J. Bentley
2020-01-08 12:21 ` Ingo Schwarze
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200107183223.GA59295@athene.usta.de \
--to=schwarze@usta.de \
--cc=anthony@anjbe.name \
--cc=tech@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).