From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Indentation conventions for Info manuals; recognizing code Date: Sun, 07 Mar 2021 08:33:37 +0200 Message-ID: <83pn0btqv2.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7517"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Mar 07 07:34:26 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lImzh-0001pz-Tf for ged-emacs-devel@m.gmane-mx.org; Sun, 07 Mar 2021 07:34:25 +0100 Original-Received: from localhost ([::1]:54140 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lImzh-0005EU-07 for ged-emacs-devel@m.gmane-mx.org; Sun, 07 Mar 2021 01:34:25 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57544) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lImz7-0004oh-52 for emacs-devel@gnu.org; Sun, 07 Mar 2021 01:33:49 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:53778) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lImz6-0002iu-HJ; Sun, 07 Mar 2021 01:33:48 -0500 Original-Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:4394 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1lImz5-0005sd-SO; Sun, 07 Mar 2021 01:33:48 -0500 In-Reply-To: (message from Drew Adams on Sun, 7 Mar 2021 01:58:43 +0000) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:266110 Archived-At: > From: Drew Adams > Date: Sun, 7 Mar 2021 01:58:43 +0000 > > I don't know what conventions/styles are defined for our Info manuals, if there are any. Is that documented somewhere? It's documented in the Texinfo manual. > Given only an Info buffer, i.e., not Texinfo source code but its output that's used by Emacs users, is there a convention wrt indentation of, say code blocks? Or is there some other way (e.g. a text property) to recognize code or similar text that really deserves a fixed-pitch font? No, I don't think so. Not from examining the indentation, anyway. You could try some heuristics to detect code from the contents, perhaps. > But other manuals don't seem to use the same indentation. Several (org, eintr, ccmode, efaq(-w32),...) indent code (including Elisp) 5 spaces - which is the same amount that other, non-code text is indented. > > (There are also lines in the Emacs manual and ccmode represent user input or program output. Those too are indented only 5 chars, so they won't appear in fixed-pitch font.) > > And if a code block is indented only 5 chars, but some of its lines are indented at least 10 chars, then this optional fontifying kicks in for those latter lines - not great, obviously. > > The CC-Mode manual is somewhat like the Elisp manual - it too indents many code blocks 10 chars, but others are indented 5 chars. > > Ccmode also has some bullets that are, themselves, indented under indented paragraphs. (Why is the bullet itself indented wrt the preceding paragraph? Same thing for numbered lists - why indent the number itself?) I think it's hopeless to rely on indentation for such a feature. As you discovered, the indentation can vary if the code block is inside some other "environment", like a table (this is what causes multi-level indentation in CC Mode manual). Moreover, there's a (rarely used) Texinfo directive that changes the default indentation of a code block, even if it is not nested inside some other indented text. If, for example, such a directive is used in the ELisp manual, it will immediately ruin the results for your feature. > I know that the use of Texinfo output (what ends up as Info buffer text) is wider than just Emacs Info. But is there, at the Texinfo level at least, some semantic markup that distinguishes something like code? Yes, the @example, @smallexample, @lisp, and @smallisp are such markup in Texinfo. > If there is, could that info be maintained - transferred to Info buffers in some way, or does the translation just have to be lossy in this way? The conversion to Info is performed by 'makeinfo', a program that is part of the Texinfo package. Its output must be mostly plain text, and the format of that file must be understood by the various Info readers out there. So if some kind of "code" marker would be retained in the Info output, it would need to be implemented in the 2 or 3 other Info readers out there, not just in Emacs. The chances of such a change in the Info output format, just for the sake of some fancy display in a single Emacs-related package sound small -- but you need to talk about this with the Texinfo developers, not with us.