RE: [External] : Re: Indentation conventions for Info manuals; recognizing code

[Drew Adams <drew.adams@oracle.com>]

[-- Attachment #1: Type: text/plain, Size: 3896 bytes --]

> > 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.

I don't see any possible heuristics.  It could be
any kind of code.  And not just code.  Shell input
and output, ASCII art,...  Really anything that it
makes sense to put in a fixed-pitch font.  The kind
of thing that usually gets something like an HTML
<code> tag.

> 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.

Yeah, I've discovered as much.

> > 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.

Is what `makeinfo' produces for them for Info
hard-coded, or can it be modified in some ways?

Or even if hard-coded, is it possible for the
resulting Info text to be somehow distinguished
as such - e.g., as we get '...' in the Info text,
resulting from some Texinfo @ construct?  (I
don't have a Texinfo or `makeinfo' manual.)

I don't see any way to recognize this in the Info
output we currently get, but is there perhaps
some way to get some indication there, e.g., to
define what Info output `makeinfo' produces for
something like @example or @lisp?

> > 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.

Too bad the translation has to be lossy.  The
effect of showing <code>-like stuff is helpful
(and is common in technical doc).

And something will be needed if we ever hope to
allow for variable-pitch text for most regular
text while using fixed-pitch for places it makes
sense (e.g. code).

With the `...' quoting there's no problem
recognizing (most) code (and key) bits embedded
in ordinary text, and using a fixed-pitch font
on the former.

I don't suppose it's feasible to have another
such construct to indicate the equivalent of
<code>...</code>?  We already have some Texinfo
markup or whatever that gets converted to '...'.
Is there some existing Texinfo construct that
could be leveraged for @lisp etc.?

See attached screenshots, for an idea of the
usefulness.  They're the same node - the only
difference is toggling minor mode
`Info-variable-pitch-text-mode'.

[-- Attachment #2: throw-emacs-Info-code-block.png --]
[-- Type: image/png, Size: 95468 bytes --]

[-- Attachment #3: throw-emacs-Info-var-pitch+code-block.png --]
[-- Type: image/png, Size: 95836 bytes --]