[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: [External] : Re: Indentation conventions for Info manuals; recognizi
From: |
Drew Adams |
Subject: |
RE: [External] : Re: Indentation conventions for Info manuals; recognizing code |
Date: |
Mon, 8 Mar 2021 03:47:38 +0000 |
> > 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'.
throw-emacs-Info-code-block.png
Description: throw-emacs-Info-code-block.png
throw-emacs-Info-var-pitch+code-block.png
Description: throw-emacs-Info-var-pitch+code-block.png