From: Drew Adams <drew.adams@oracle.com>
To: "emacs-devel@gnu.org" <emacs-devel@gnu.org>
Subject: Indentation conventions for Info manuals; recognizing code
Date: Sun, 7 Mar 2021 01:58:43 +0000 [thread overview]
Message-ID: <SA2PR10MB4474CB7322BEDE862DD42BBFF3949@SA2PR10MB4474.namprd10.prod.outlook.com> (raw)
I don't know what conventions/styles are defined for our Info manuals, if there are any. Is that documented somewhere?
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?
Code blocks, ASCII diagrams, and the like seem to be indented 10 chars in the Elisp manual.
That's a start. Based on that, I added an experimental option to Info+ to fontify text that's indented at least 10 chars (by default). The face used is fixed-pitch by default.
(There's also a minor mode that lets you use variable-pitch for the main text body - but that's independent. Being able to fontify code blocks is useful even when all of the text is fixed-pitch.)
For the Elisp manual this fontifying of indented text (>= 10 chars) works quite well.
My code also optionally highlights quoted sexps (`...', "...") with fixed-pitch faces (by default), so code is fixed-pitch pretty much everywhere in the Elisp manual, even if you choose to make the main text variable-pitch. Likewise, ASCII-art diagrams (they seem to be indented 10 chars also).
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?)
And the continuation lines of such bullets start at ... 10 chars, so they get fontified (incorrectly). Some bullets are even indented relative to indented paragraphs, in which case even the bullet line gets fontified (incorrectly). E.g. (ccmode) `Indentation Commands':
‘<TAB>’ (‘c-indent-command’)
This command indents the current line. That is all you need to
know about it for normal use...
...
-- User Option: c-tab-always-indent
This variable modifies how <TAB> operates.
• When it is ‘t’ (the default), <TAB> simply indents the
current line.
• When it is ‘nil’, <TAB> (re)indents the line only if
point is to the left of the first non-whitespace...
(5 levels of indentation.)
Maybe such a `User Option:' entry could/should really be at the left margin (1-char indent)? (That would also enable the highlighting I do for `User Option:' lines.) But this seems to be intentional - it's done in several places.
Ccmode also has subheadings of a sort, with the text that follows being indented 5 chars. And there can be nested text that's indented still further.
Using “Hungry Delete Mode” with ‘<DEL>’ and ‘C-d’
Here you toggle Hungry Delete minor mode with ‘M-x
c-toggle-hungry-state’(1) (*note Minor Modes::.) This makes
‘<DEL>’ and ‘C-d’ do backwards and forward hungry deletion.
‘<DEL>’ (‘c-electric-backspace’)
This command is run by default when you hit the ‘<DEL>’ key.
When hungry delete mode is enabled, it deletes any amount of
That last text is indented ... 10 chars. Similarly, these indented subheadings:
The display of the guessed style contains these elements:
Placeholder Name
You should replace this with a style name of your own.
Parent Style
The style current when the guessing began, from which the
guessed style inherits (*note Config Basics::) the settings
which weren’t guessed.
___
So given only an Info buffer, I know of no good way to distinguish code blocks and such meaningfully. Is there an indentation style/convention that has some kind of semantics in this regard? I'm guessing no.
My code that does this works only in an Info buffer - it can't see any Texinfo source. It just tweaks `Info-fontify-node' to optionally fontify some things. So like the rest of `Info-fontify-node', it can only distinguish what's distinct in the Info buffer. If displayed code isn't declared/recognized as such at the buffer level then we're out of luck I guess.
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? 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?
It would be handy to be able to somehow distinguish lines of code from other indented text.
___
To see what I mean, take a look at the Elisp manual, after loading info+.el. If you want to also see the main text with variable-pitch, then first turn on minor mode `Info-variable-pitch-text-mode'. (The fixed-pitch face used by default is ugly, unless you happen to have font Lucida Console. But you can of course customize it.) Then, to see the problems mentioned, try a manual such as Ccmode or Org.
https://www.emacswiki.org/emacs/download/info%2b.el
next reply other threads:[~2021-03-07 1:58 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-03-07 1:58 Drew Adams [this message]
2021-03-07 6:33 ` Indentation conventions for Info manuals; recognizing code Eli Zaretskii
2021-03-08 3:47 ` [External] : " Drew Adams
2021-03-08 5:49 ` Yuri Khan
2021-03-08 14:07 ` Eli Zaretskii
2021-03-08 15:33 ` Drew Adams
2021-03-08 5:37 ` Richard Stallman
2021-03-08 13:57 ` Eli Zaretskii
2021-03-08 15:33 ` [External] : " Drew Adams
-- strict thread matches above, loose matches on Subject: below --
2021-03-08 9:51 tydrdn
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=SA2PR10MB4474CB7322BEDE862DD42BBFF3949@SA2PR10MB4474.namprd10.prod.outlook.com \
--to=drew.adams@oracle.com \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.