bug#16439: [feature request] Highlighting of strings within Info buffers

bug#16439: [feature request] Highlighting of strings within Info buffers

[Sebastien Vauban]

Hello,

As an occasional reader of the Emacs Info files, I find that these are
much more readable when the strings are highlighted: we directly see
a couple of variables we should customize, or a couple of functions
which we have to call.

I do use Info+ to obtain http://screencast.com/t/p62ccMRqmjM:

--8<---------------cut here---------------start------------->8---
(require 'info+)

;; show breadcrumbs in the header line
(setq Info-breadcrumbs-in-header-flag t)

;; don't show breadcrumbs in the mode line
(setq Info-breadcrumbs-in-mode-line-mode nil)
--8<---------------cut here---------------end--------------->8---

But it'd be nice if the highlighting was in Emacs by default, to serve
all users who don't have such a customization.

Best regards,
  Seb

-- 
Sebastien Vauban

bug#16439: [feature request] Highlighting of strings within Info buffers

[Rüdiger Sonderfeld]

Hello,
that feature looks very useful to me.  I've just seen that info+ is developed 
by Drew Adams (I took the liberty to CC him).  Maybe he is willing to move 
info+ to GNU ELPA for now and after the feature freeze we could consider 
moving it or parts of it to Info mode.

http://www.emacswiki.org/emacs/info+.el

Regards,
Rüdiger

On Tuesday 14 January 2014 11:15:47 Sebastien Vauban wrote:
> Hello,
> 
> As an occasional reader of the Emacs Info files, I find that these are
> much more readable when the strings are highlighted: we directly see
> a couple of variables we should customize, or a couple of functions
> which we have to call.
> 
> I do use Info+ to obtain http://screencast.com/t/p62ccMRqmjM:
> 
> --8<---------------cut here---------------start------------->8---
> (require 'info+)
> 
> ;; show breadcrumbs in the header line
> (setq Info-breadcrumbs-in-header-flag t)
> 
> ;; don't show breadcrumbs in the mode line
> (setq Info-breadcrumbs-in-mode-line-mode nil)
> --8<---------------cut here---------------end--------------->8---
> 
> But it'd be nice if the highlighting was in Emacs by default, to serve
> all users who don't have such a customization.
> 
> Best regards,
>   Seb

bug#16439: [feature request] Highlighting of strings within Info buffers

[Drew Adams]

> that feature looks very useful to me.  I've just seen that info+ is
> developed by Drew Adams (I took the liberty to CC him).  Maybe he is
> willing to move info+ to GNU ELPA for now and after the feature freeze
> we could consider moving it or parts of it to Info mode.
> http://www.emacswiki.org/emacs/info+.el

I have offered to GNU Emacs any or all of the info+.el code in the past
- more than once.  I offered the `...' and "..." highlighting as a patch
a decade ago.  I detailed tests on the existing manuals (Emacs and Elisp),
showing which tiny minority of nodes were problematic for such highlighting
because of unmatching " etc.

The offer for GNU Emacs still stands, of course.  But so far the response
has been, "Sorry, not interested".

Wrt GNU ELPA, it is not clear to me how to get code accepted and
submitted there.  I will not be using BZR or GIT etc.  (This code, like
almost all of my code, is available at MELPA, however.)  I could also
submit a patch again for just the `...' etc. highlighting, as an email
attachment.  But again, so far the answer from Emacs Dev has been no.

bug#16439: [feature request] Highlighting of strings within Info buffers

[Juri Linkov]

>> that feature looks very useful to me.  I've just seen that info+ is
>> developed by Drew Adams (I took the liberty to CC him).  Maybe he is
>> willing to move info+ to GNU ELPA for now and after the feature freeze
>> we could consider moving it or parts of it to Info mode.
>> http://www.emacswiki.org/emacs/info+.el
>
> I offered the `...' and "..." highlighting as a patch a decade ago.

The problem is how to highlight strings only in code samples
because in other places highlighting "..." makes no sense.
Look for example in the node (info "(emacs) Package Keywords"):

  Most optional features in Emacs are grouped into "packages".

Should "packages" be highlighted as a string.  Of course not.
There is no additional emphasis on quotations in books.

bug#16439: [feature request] Highlighting of strings within Info buffers

[Stefan Monnier]

> The problem is how to highlight strings only in code samples
> because in other places highlighting "..." makes no sense.
> Look for example in the node (info "(emacs) Package Keywords"):
>   Most optional features in Emacs are grouped into "packages".
> Should "packages" be highlighted as a string.  Of course not.
> There is no additional emphasis on quotations in books.

Indeed.  The "right answer" is to move away from the Info format and
rely on something more structured that we could render in a much more
pretty way, using bold, italics, and friends.
In the mean time, I use the patch below.


        Stefan


--- lisp/info.el	2014-01-17 20:33:22 +0000
+++ lisp/info.el	2014-01-17 22:51:46 +0000
@@ -4193,5 +4192,12 @@
     st)
   "Syntax table used in `Info-mode'.")
 
+(defface Info-quoted
+  '((t :family "courier"))
+  "Face used for quoted elements.")
+
+(defvar Info-mode-font-lock-keywords
+  '(("‘\\([^’]*\\)’" (1 'Info-quoted))))
+
 ;; Autoload cookie needed by desktop.el
 ;;;###autoload
@@ -4296,1 +4291,2 @@
+  (setq-local font-lock-defaults '(Info-mode-font-lock-keywords t t))
   (Info-set-mode-line)

bug#16439: [feature request] Highlighting of strings within Info buffers

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> The problem is how to highlight strings only in code samples
>> because in other places highlighting "..." makes no sense.
>> Look for example in the node (info "(emacs) Package Keywords"):
>>   Most optional features in Emacs are grouped into "packages".
>> Should "packages" be highlighted as a string.  Of course not.
>> There is no additional emphasis on quotations in books.
>
> Indeed.  The "right answer" is to move away from the Info format and
> rely on something more structured that we could render in a much more
> pretty way, using bold, italics, and friends.

Yup.  I don't think there's anything much that can be done here that
won't break other examples, so I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#16439: [feature request] Highlighting of strings within Info buffers

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Mon, 20 Jan 2014 11:18:20 +0200
> Cc: ruediger@c-plusplus.de, 16439@debbugs.gnu.org, sva-news@mygooglest.com
> 
> > I offered the `...' and "..." highlighting as a patch a decade ago.
> 
> The problem is how to highlight strings only in code samples
> because in other places highlighting "..." makes no sense.
> Look for example in the node (info "(emacs) Package Keywords"):
> 
>   Most optional features in Emacs are grouped into "packages".
> 
> Should "packages" be highlighted as a string.  Of course not.

Why not?  This particular example is produced from @dfn in Texinfo,
which should emphasize its argument.  In the printed version
"packages" is typeset in slanted typeface (and without the quotes).

> There is no additional emphasis on quotations in books.

But we are not talking about books, are we?  We are talking about Info
manuals, which are mostly documentation of software.

bug#16439: [feature request] Highlighting of strings within Info buffers

[Juri Linkov]

>>   Most optional features in Emacs are grouped into "packages".
>>
>> Should "packages" be highlighted as a string.  Of course not.
>
> Why not?  This particular example is produced from @dfn in Texinfo,
> which should emphasize its argument.  In the printed version
> "packages" is typeset in slanted typeface (and without the quotes).

It makes sense to emphasize either 1) using quotes and no additional
highlighting or 2) using italic without the quotes, but not both styles
(italic and quotes) at the same time.

>> There is no additional emphasis on quotations in books.
>
> But we are not talking about books, are we?  We are talking about Info
> manuals, which are mostly documentation of software.

Ideally, the look of on-line documentation should not differ from
the printed version.  How this could be achieved is a difficult
question.  In the comments of http://esr.ibiblio.org/?p=5211
someone suggested using Markdown for Emacs documentation,
but ESR strongly disagreed.  Maybe using the natively
supported Org format would be better.

But actually I see no much need in replacing Texinfo as the source format.
As for the output format, we could try to migrate in the direction of HTML.
However, HTML has its own problems (no index, slow rendering, etc.)

bug#16439: [feature request] Highlighting of strings within Info buffers

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Cc: drew.adams@oracle.com,  ruediger@c-plusplus.de,  16439@debbugs.gnu.org,  sva-news@mygooglest.com
> Date: Tue, 21 Jan 2014 09:54:39 +0200
> 
> >>   Most optional features in Emacs are grouped into "packages".
> >>
> >> Should "packages" be highlighted as a string.  Of course not.
> >
> > Why not?  This particular example is produced from @dfn in Texinfo,
> > which should emphasize its argument.  In the printed version
> > "packages" is typeset in slanted typeface (and without the quotes).
> 
> It makes sense to emphasize either 1) using quotes and no additional
> highlighting or 2) using italic without the quotes, but not both styles
> (italic and quotes) at the same time.

I agree, and didn't say anything to the contrary.  I told about the
slant typeface as an evidence that what came out of @dfn should be
emphasized in some way.

> >> There is no additional emphasis on quotations in books.
> >
> > But we are not talking about books, are we?  We are talking about Info
> > manuals, which are mostly documentation of software.
> 
> Ideally, the look of on-line documentation should not differ from
> the printed version.

We are not talking about ideals.

> But actually I see no much need in replacing Texinfo as the source format.
> As for the output format, we could try to migrate in the direction of HTML.
> However, HTML has its own problems (no index, slow rendering, etc.)

Indeed, and I wasn't asking to switch.

This was only about emphasizing quoted strings in Info manuals.

bug#16439: [feature request] Highlighting of strings within Info buffers

[Juri Linkov]

> I agree, and didn't say anything to the contrary.  I told about the
> slant typeface as an evidence that what came out of @dfn should be
> emphasized in some way.

I don't understand the difference between using @dfn and double quotes,
e.g. why in the source of the chapter "The Organization of the Screen":

    The main area of the frame, below the tool bar (if one exists) and
  above the echo area, is called @dfn{the window}.  Henceforth in this
  manual, we will use the word ``window'' in this sense.

the different styles are used for @dfn{the window} and ``window''?

But if both were written in the Info output using DOUBLE QUOTATION MARK
as “window”, then in the Info browser we could emphasize such terms
using the slant typeface and put invisible properties on quote characters.

Then if code blocks such as e.g. in @code{("/foo" "/bar" @dots{})}
were written using simple quotation marks e.g. ("/foo" "/bar" …)
then it would make sense to highlight quoted strings in Info
in code samples using `font-lock-string-face'.

This problem doesn't exist in HTML output that keeps all different source
styles unambiguous, e.g.:

     <p>The main area of the frame, below the tool bar (if one exists) and
  above the echo area, is called <dfn>the window</dfn>.  Henceforth in this
  manual, we will use the word &ldquo;window&rdquo; in this sense.

  <code>(&quot;/foo&quot; &quot;/bar&quot; &hellip;)</code>

where only strings in &quot; inside <code> makes sense
to highlight using `font-lock-string-face'.

bug#16439: [feature request] Highlighting of strings within Info buffers

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Cc: drew.adams@oracle.com,  ruediger@c-plusplus.de,  16439@debbugs.gnu.org,  sva-news@mygooglest.com
> Date: Wed, 22 Jan 2014 10:09:19 +0200
> 
> > I agree, and didn't say anything to the contrary.  I told about the
> > slant typeface as an evidence that what came out of @dfn should be
> > emphasized in some way.
> 
> I don't understand the difference between using @dfn and double quotes,
> e.g. why in the source of the chapter "The Organization of the Screen":
> 
>     The main area of the frame, below the tool bar (if one exists) and
>   above the echo area, is called @dfn{the window}.  Henceforth in this
>   manual, we will use the word ``window'' in this sense.
> 
> the different styles are used for @dfn{the window} and ``window''?

The former is terminology, the latter is just a word.

> But if both were written in the Info output using DOUBLE QUOTATION MARK
> as “window”, then in the Info browser we could emphasize such terms
> using the slant typeface and put invisible properties on quote characters.

That should be OK, I think.

> Then if code blocks such as e.g. in @code{("/foo" "/bar" @dots{})}
> were written using simple quotation marks e.g. ("/foo" "/bar" …)
> then it would make sense to highlight quoted strings in Info
> in code samples using `font-lock-string-face'.

That'd be OK as well, IMO.

> This problem doesn't exist in HTML output that keeps all different source
> styles unambiguous, e.g.:

HTML is a markup language, Info is not.

bug#16439: [feature request] Highlighting of strings within Info buffers

[Drew Adams]

> The problem is how to highlight strings only in code samples
> because in other places highlighting "..." makes no sense.
> Look for example in the node (info "(emacs) Package Keywords"):
> 
>   Most optional features in Emacs are grouped into "packages".
> 
> Should "packages" be highlighted as a string.  Of course not.
> There is no additional emphasis on quotations in books.


1. That is not "the problem", IMO.  When I proposed this feature,
long ago, the complaints (against even providing it optionally,
via a user option) were that the highlighting is not foolproof,
in that there are some cases where ` or " is not matched (e.g.,
?").

For that, I tested each node of the Emacs and Elisp manuals (at
the time), and I showed that that problem is very rare.  And
making the highlighting optional and togglable, deals quite well
with that rarity - just hit a key in any of the very few nodes
where the highlighting is problematic, to get rid of it.  Or
turn the option off in your init file if you really prefer what
Emacs does now (no such highlighting).


2. Wrt the "problem" you bring up now -

Sorry, I don't agree.  I've used this feature for decades now,
and I can assure you that it is very helpful to have all "..."
highlighted.  Just my opinion, obviously.

It is also possible to separate the control over highlighting of
`...' and "...", e.g., by either having different user options
or giving the option more possible values.  I have not done that
in `info+.el', as I have not see the need for it.  (However, I
do have separate options for `...' and "...", on the one hand,
and <...>, on the other.)


3. More importantly, I'm hoping that Emacs will at some point
(soon) move to supporting different quoting methods for
semantically different constructs, as was discussed in this bug
thread: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16292.

I did not bring this up in that thread, because it had already
been decided what to do in the immediate, but there are some
very different uses of "..." in the Elisp and Emacs manuals.

And here I am with you to some extent: "..." to represent a
string is different in meaning from "..." to represent, say,
the introduction of a glossary term (in-place term definition),
which is yet again different from actual quotation (citation),
such as the FSF's Back-Cover Text.

Strings should be represented using straight " quotes, as
is done currently.  Actual quotations (citations) should be
represented using curly double-quotes.  And glossary terms
should be represented using either curly double-quotes or
another typographical convention (bold or italic is often
used for this, but it could also be a different color or
other convention).

If we do ever represent these different things in different
ways, instead of the single "..." notation, then your
problem will disappear.


4. During the one or two days that curly single-quotes were
actually used in Emacs, during the discussion of bug #16292,
I adjusted `info+.el' to DTRT for that, and it worked very
well.  Unfortunately, the builds for that did not also affect
double-quotes, so there was no test for that.  But taking
care of that in `info+.el' would be trivial also.

I'm not knowledgable about TexInfo etc., but I would guess
that the changes to support different appearances for what
are now handled as "..." would also be straightforward.

That is, I would expect that "..." as strings or as
term definitions might already be handled differently at
the TexInfo level, and are just being mapped to the same
Info representation, "...".  Just a guess.

I see no obstacle to providing helpful highlighting to
Emacs such as is provided by `info+.el', except the will
of Emacs Dev.

FWIW, `info+.el' also highlights <...> (controlled by a
separate user option).  Thus keys represented using this
syntax are highlighted the same as other keys.


5. Note, BTW, that there is no real difference between
"..." and `...' wrt "the problem" you cite.  Look at the
`Top' node of the Emacs manual, for example, and you will
see this:

  This is the `GNU Emacs Manual', updated for

That use of `...' is semantically different from its use in
`forward-char' or `C-x 4 f' or `.emacs'.