From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id fd88b4f8 for ; Tue, 7 Jan 2020 13:32:27 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1ioteT-0003eC-6N; Tue, 07 Jan 2020 19:32:26 +0100 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1ioteS-0008Aq-5g; Tue, 07 Jan 2020 19:32:24 +0100 Received: from athene.asta.kit.edu ([141.3.145.60] helo=athene.usta.de) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1ioteR-0004SE-WC; Tue, 07 Jan 2020 19:32:24 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 4e07a189; Tue, 7 Jan 2020 19:32:23 +0100 (CET) Date: Tue, 7 Jan 2020 19:32:23 +0100 From: Ingo Schwarze To: "Anthony J. Bentley" Cc: tech@mandoc.bsd.lv Subject: Re: eqn(7) "delim" is undocumented (maybe) Message-ID: <20200107183223.GA59295@athene.usta.de> References: <38466-1575794557.527458@DkTY.Emny.Ld6w> X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <38466-1575794557.527458@DkTY.Emny.Ld6w> User-Agent: Mutt/1.12.2 (2019-09-21) 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()" > .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