Re: Indentation conventions for Info manuals; recognizing code

[Eli Zaretskii <eliz@gnu.org>]

> From: Drew Adams <drew.adams@oracle.com>
> 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.