bug#23798: 25.0.90; Underscore for emphasis in Info?

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

C-h i h n

Why are there underscores surrounding the text "please don't"?

They don't cause that text to be rendered any differently.  Emacs has
had faces for quite some time now.  Why not use a specific face for
this?  Is this vestigial?  Does it really serve a purpose?




In GNU Emacs 25.0.90.4 (i686-w64-mingw32)
 of 2016-03-20
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-w64-mingw32 --without-dbus
 --without-compress-install CFLAGS=-static'

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Eli Zaretskii]

> Date: Sat, 18 Jun 2016 17:12:44 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> C-h i h n
> 
> Why are there underscores surrounding the text "please don't"?

That's how Info renders @emph.

> They don't cause that text to be rendered any differently.  Emacs has
> had faces for quite some time now.  Why not use a specific face for
> this?  Is this vestigial?  Does it really serve a purpose?

Because no one wrote code to implement that.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

> > C-h i h n
> > Why are there underscores surrounding the text "please don't"?
> 
> That's how Info renders @emph.
> 
> > They don't cause that text to be rendered any differently.  Emacs has
> > had faces for quite some time now.  Why not use a specific face for
> > this?  Is this vestigial?  Does it really serve a purpose?
> 
> Because no one wrote code to implement that.

Then please consider this report as an enhancement request for that.

Below is a patch for one simple possibility.  It uses face `info-emphasis'
to highlight emphasized single words, such as _foobar_.

Trying to emphasize more than single words can lead to trouble: there
are places where it won't do the right thing, and readers can lose
information (since the underscores are hidden).

If the regexp is "_\\([^_]+\\)_", for instance, then it can continue
across newlines and is more likely to cause trouble than if it is
"_\\([^_\n]+\\)_" (unrelated underscores are mistaken as emphasizing).

But even the latter causes trouble in a node such as (elisp) `Symbol
Type', where there is this line:

     +-*/_~!@$%^&=:<>{}  ; A symbol named `+-*/_~!@$%^&=:<>{}'.

Even just matching words possibly separated by whitespace can lead
to trouble.  E.g., for regexp "_\\(\\(\\sw\\|[[:space:]]\\)+\\)_"
node (elisp) `Sequence Functions' is screwed up because of this code
there:

    (seq-let (_ a _ b) '(1 2 3 4)
      (list a b))

Similarly, trying to fontifie emphasized symbol names instead of
just words can be problematic.

Whatever matching is used, even just single words, there could be
some Info text that is problematic.  For instance, a Lisp example
might use _foo_ and foo as symbol names.  The fontification hides
the underscores, so that both become the same name, foo.

Still, I think fontifying only single words is pretty good.  If you
are worried about this you could add an option for such highlighting.

Is there any other kind of emphasis that is used?  For example,
does Info use double underscore for stronger emphasis, e.g.,
__abc__?  I couldn't find any such in the Emacs or Elisp manuals.


diff -u info.el info-patched.el
--- info.el	2016-06-18 22:48:10.795523400 -0700
+++ info-patched.el	2016-06-18 23:26:36.084378400 -0700
@@ -132,6 +132,12 @@
   :version "22.1"
   :group 'info)
 
+(defface info-emphasis
+  '((t (:inherit italic)))
+  "*Face for emphasized text (enclosed with underscores)."
+  :version "25.1"
+  :group 'info)
+
 (defcustom Info-fontify-visited-nodes t
   "Non-nil to fontify references to visited nodes in `info-xref-visited' face."
   :version "22.1"
@@ -4717,6 +4723,16 @@
 		  (put-text-property (match-beginning 1) (match-end 1)
 				     'invisible t)))))))
 
+      ;; Fontify emphasis: _..._
+      (goto-char (point-min))
+      (when (and font-lock-mode  not-fontified-p)
+        (while (re-search-forward "_\\(\\sw+\\)_" nil t)
+          (add-text-properties (match-beginning 0) (1+ (match-beginning 0))
+                               '(invisible t front-sticky nil rear-nonsticky t))
+          (add-text-properties (1- (match-end 0)) (match-end 0)
+                               '(invisible t front-sticky nil rear-nonsticky t))
+          (put-text-property (match-beginning 1) (match-end 1) 'font-lock-face 'info-emphasis)))
+
       ;; Fontify titles
       (goto-char (point-min))
       (when (and font-lock-mode not-fontified-p)

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Eli Zaretskii]

> Date: Sat, 18 Jun 2016 23:53:17 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 23798@debbugs.gnu.org
> 
> > > C-h i h n
> > > Why are there underscores surrounding the text "please don't"?
> > 
> > That's how Info renders @emph.
> > 
> > > They don't cause that text to be rendered any differently.  Emacs has
> > > had faces for quite some time now.  Why not use a specific face for
> > > this?  Is this vestigial?  Does it really serve a purpose?
> > 
> > Because no one wrote code to implement that.
> 
> Then please consider this report as an enhancement request for that.
> 
> Below is a patch for one simple possibility.  It uses face `info-emphasis'
> to highlight emphasized single words, such as _foobar_.

Thanks.

> Is there any other kind of emphasis that is used?

Yes, there's @strong, rendered as *foo*.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

> > Is there any other kind of emphasis that is used?
> 
> Yes, there's @strong, rendered as *foo*.

I see.  I suspected that, so I searched for it (in the Emacs and
Elisp manuals).  I did not find any matches that would seem to
reflect that.

And I did find _lots_ of matches that instead mean something
else, such as a buffer name: *Messages* (with and without
enclosing single quotes - with quotes is not problematic).

So I don't think it is very feasible to try to render *...*
using, say, ... with a face `info-strong' (e.g. bold by default).
I think trying to do that would be too problematic.

It is unfortunate that Info "renders" what is clear markup, e.g.
@strong, by something that is not markup and not clearly
notational, and so is easily confused with ordinary text.  If
@strong were "rendered" as, say, **...**, the risk of confusion
would be greatly reduced.  (Is something like that a possibility,
or is this "rendering" a given?)

As it stands now, the case for fixing _..._ for single words is
reasonable, I think, but I don't think that's the case for *...*.

Maybe you have a better suggestion?

If you decide to do nothing wrt this enhancement request, perhaps
you would at least consider to have the Info help, for Info that
is displayed by Emacs, include a "notation" section that tells
users that "_..._" is emphasis and "*...*" is strong emphasis.
We already have node (info) `Help-Inv', which is along the same
lines, but the notation is not described anywhere, AFAICT. 

Whether or not we add a section for notation in general, if we
apply a patch such as I proposed, it might help to also point out
in `Help-Inv' that turning on `visible-mode' shows the underscores
that actually surround emphasized text.  IOW, `M-x visible-mode'
to turn it on shows emphasized text in `Help-Inv' as "_always_"
and "_default_" (with the words emphasized using face `italic' by
default).

The main problem this report points to is that these notational
things are not introduced/mentioned anywhere.  There should be
some place where the Info notation is introduced.  (Yes, few
readers will ever come across such a notation description, but it
would still be better to have it than not to have it, IMO.)

BTW, I see that (info) `Help-]' includes "_at the same level_"
and "_regardless of level_": multiple emphasized words.  These
phrases would not be fontified using the patch I included, which
acts only on single words.

On the other hand, since `visible-mode' can be used to show
hidden `_', maybe it would be OK to use a regexp that highlights
words possibly separated by whitespace?  IOW, it is very easy
to compensate for improper hiding of `_', just by turning on
`visible-mode'.

But (a) most users won't know about `visible-mode' and (b) more
importantly, they won't know whether something is hidden or not,
except by noticing that some text has been emphasized (which is
not super obvious with face `italic').  I fear that most users
would be misled by this.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Eli Zaretskii]

> Date: Sun, 19 Jun 2016 09:23:59 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 23798@debbugs.gnu.org
> 
> > > Is there any other kind of emphasis that is used?
> > 
> > Yes, there's @strong, rendered as *foo*.
> 
> I see.  I suspected that, so I searched for it (in the Emacs and
> Elisp manuals).  I did not find any matches that would seem to
> reflect that.

You have a few.  Here's one, from "Action Arguments" in the Emacs
manual:

     *Warning:* If previous command-line arguments have visited files,
     the current directory is the directory of the last file visited.

> It is unfortunate that Info "renders" what is clear markup, e.g.
> @strong, by something that is not markup and not clearly
> notational, and so is easily confused with ordinary text.

Info was designed to display on the dumbest text terminals out there.

> Maybe you have a better suggestion?

I hope others will chime in.

> If you decide to do nothing wrt this enhancement request, perhaps
> you would at least consider to have the Info help, for Info that
> is displayed by Emacs, include a "notation" section that tells
> users that "_..._" is emphasis and "*...*" is strong emphasis.
> We already have node (info) `Help-Inv', which is along the same
> lines, but the notation is not described anywhere, AFAICT. 

This is documented in the Texinfo manual.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

> > > Yes, there's @strong, rendered as *foo*.
> >
> > I see.  I suspected that, so I searched for it (in the Emacs and
> > Elisp manuals).  I did not find any matches that would seem to
> > reflect that.
> 
> You have a few.  Here's one, from "Action Arguments" in the Emacs
> manual:
> 
>      *Warning:* If previous command-line arguments have visited files,
>      the current directory is the directory of the last file visited.

I saw that, but looked too quickly and thought it was showing a
literal message. 

> > It is unfortunate that Info "renders" what is clear markup, e.g.
> > @strong, by something that is not markup and not clearly
> > notational, and so is easily confused with ordinary text.
> 
> Info was designed to display on the dumbest text terminals out there.

Yes, and it does a good job.

> > Maybe you have a better suggestion?
> 
> I hope others will chime in.
> 
> > If you decide to do nothing wrt this enhancement request, perhaps
> > you would at least consider to have the Info help, for Info that
> > is displayed by Emacs, include a "notation" section that tells
> > users that "_..._" is emphasis and "*...*" is strong emphasis.
> > We already have node (info) `Help-Inv', which is along the same
> > lines, but the notation is not described anywhere, AFAICT.
> 
> This is documented in the Texinfo manual.

I think it should be pointed out to _readers_ of the manuals,
not just to writers.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

Perhaps someone could tag this bug report with "patch"?  I don't
know how to do that.

(And perhaps the patch could be applied?  And perhaps the user doc
could be updated as suggested?)

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Eli Zaretskii]

> Date: Fri, 1 Jul 2016 09:36:25 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 23798@debbugs.gnu.org
> 
> Perhaps someone could tag this bug report with "patch"?  I don't
> know how to do that.

This is explained in admin/notes/bugtracker (search for"tags").

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

> > Perhaps someone could tag this bug report with "patch"?  I don't
> > know how to do that.
> 
> This is explained in admin/notes/bugtracker (search for"tags").

I don't see any "admin/notes/bugtracker" in my Emacs binary.
Please consider adding the patch tag.  Thx.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Eli Zaretskii]

> Date: Fri, 1 Jul 2016 10:30:47 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 23798@debbugs.gnu.org
> 
> > > Perhaps someone could tag this bug report with "patch"?  I don't
> > > know how to do that.
> > 
> > This is explained in admin/notes/bugtracker (search for"tags").
> 
> I don't see any "admin/notes/bugtracker" in my Emacs binary.

You can find it here:

  http://git.savannah.gnu.org/cgit/emacs.git/tree/admin/notes/bugtracker

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

> > > This is explained in admin/notes/bugtracker (search for"tags").
> You can find it here:
> http://git.savannah.gnu.org/cgit/emacs.git/tree/admin/notes/bugtracker

OK, thanks.  Done.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

FWIW -

In my own code I'm using this regexp now (by default - a user option):

"_\\(\\(\\sw\\(\\s-\\|\\sw\\|\\s.\\)*\\)\\|\\(\\(\\s-\\|\\sw\\|\\s.\\)\\sw*\\)\\)_"

It matches word, punctuation, and whitespace chars, plus hyphens,
with at least one word character.  Hyphen is included explicitly
because it generally has symbol syntax in Info.

This seems to work pretty will.  But there are of course some
places where it does not DTRT.

In my own code I also remove hiding of the enclosing `_' chars
when emphasis highlighting is turned off:

(while (re-search-forward Info-emphasis-regexp nil t)
  (let ((fn  (if Info-fontify-emphasis-flag
                 #'add-text-properties
               #'remove-text-properties)))
     (funcall fn (match-beginning 0) (1+ (match-beginning 0))
              '(invisible t front-sticky nil rear-nonsticky t))
     (funcall fn (1- (match-end 0)) (match-end 0)
              '(invisible t front-sticky nil rear-nonsticky t))
     (funcall fn (match-beginning 1) (match-end 1)
              '(font-lock-face info-emphasis))))

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Eli Zaretskii]

> Date: Sat, 2 Jul 2016 13:59:54 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 23798@debbugs.gnu.org
> 
> FWIW -
> 
> In my own code I'm using this regexp now (by default - a user option):
> 
> "_\\(\\(\\sw\\(\\s-\\|\\sw\\|\\s.\\)*\\)\\|\\(\\(\\s-\\|\\sw\\|\\s.\\)\\sw*\\)\\)_"
> 
> It matches word, punctuation, and whitespace chars, plus hyphens,
> with at least one word character.  Hyphen is included explicitly
> because it generally has symbol syntax in Info.
> 
> This seems to work pretty will.  But there are of course some
> places where it does not DTRT.
> 
> In my own code I also remove hiding of the enclosing `_' chars
> when emphasis highlighting is turned off:
> 
> (while (re-search-forward Info-emphasis-regexp nil t)
>   (let ((fn  (if Info-fontify-emphasis-flag
>                  #'add-text-properties
>                #'remove-text-properties)))
>      (funcall fn (match-beginning 0) (1+ (match-beginning 0))
>               '(invisible t front-sticky nil rear-nonsticky t))
>      (funcall fn (1- (match-end 0)) (match-end 0)
>               '(invisible t front-sticky nil rear-nonsticky t))
>      (funcall fn (match-beginning 1) (match-end 1)
>               '(font-lock-face info-emphasis))))

I hope one of the Info gurus will chime in at some point.

Thanks.

bug#23798: 25.0.90; Underscore for emphasis in Info?

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> I hope one of the Info gurus will chime in at some point.

I imagine a deep, rythmic chanting as they chime in, appearing robed and in
single file, ready to tell us about the latest source of new Info...

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Drew Adams]

> > I hope one of the Info gurus will chime in at some point.
> 
> I imagine a deep, rythmic chanting as they chime in, appearing robed and in
> single file, ready to tell us about the latest source of new Info...

Good one! Chime chime oohhhmmm chime chime.
I can feel it coming...

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> Below is a patch for one simple possibility.  It uses face `info-emphasis'
>> to highlight emphasized single words, such as _foobar_.
>
> Thanks.

I've now applied the patch to the Emacs trunk.

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

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Andy Moreton]

On Tue 25 Jun 2019, Lars Ingebrigtsen wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> Below is a patch for one simple possibility.  It uses face `info-emphasis'
>>> to highlight emphasized single words, such as _foobar_.
>>
>> Thanks.
>
> I've now applied the patch to the Emacs trunk.

The regexp used for emphasis does not match single words: it also
matches sequences within words.

For an example, see the "(gcc) Other Builtins" node, where C function
names are displayed incorrectly.

    AndyM

bug#23798: 25.0.90; Underscore for emphasis in Info?

[Lars Ingebrigtsen]

Andy Moreton <andrewjmoreton@gmail.com> writes:

> The regexp used for emphasis does not match single words: it also
> matches sequences within words.
>
> For an example, see the "(gcc) Other Builtins" node, where C function
> names are displayed incorrectly.

OK; I'll revert the patch.

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