Hiding *Note:: "tags" in info files

Hiding *Note:: "tags" in info files

[Kim F. Storm]

When I browse info files in emacs, I find all those visible 
*Note ... :: "tags" pretty annoying, given that the references
are already displayed in the info-xref face.

The following patch hides those superfluous decorations.

The result isn't perfect, since the wording around some of the nodes
become a bit sparse, e.g. (upper case indicates highlighting)

   *Note GETTING A PRINTED MANUAL::, if you would like a paper copy of
the Emacs manual.

(which isn't perfect English either) becomes

   GETTING A PRINTED MANUAL, if you would like a paper copy of
the Emacs manual.


But personally I don't think that is worse than the *Note stuff.

WDYT?



Index: info.el
===================================================================
RCS file: /cvs/emacs/lisp/info.el,v
retrieving revision 1.318
diff -c -r1.318 info.el
*** info.el	8 Oct 2002 04:57:27 -0000	1.318
--- info.el	29 Oct 2002 11:51:26 -0000
***************
*** 2712,2724 ****
  	    (add-text-properties (match-beginning 2) (1+ (match-end 2))
  				 '(invisible t intangible t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\*Note[ \n\t]+\\([^:]*\\):" nil t)
  	  (if (= (char-after (1- (match-beginning 0))) ?\") ; hack
  	      nil
  	    (add-text-properties (match-beginning 1) (match-end 1)
  				 '(font-lock-face info-xref
  				   mouse-face highlight
! 				   help-echo "mouse-2: go to this node"))))
  	(goto-char (point-min))
  	(if (and (search-forward "\n* Menu:" nil t)
  		 (not (string-match "\\<Index\\>" Info-current-node))
--- 2712,2729 ----
  	    (add-text-properties (match-beginning 2) (1+ (match-end 2))
  				 '(invisible t intangible t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \n\t]+\\)\\([^:]*\\)\\(:+\\)" nil t)
  	  (if (= (char-after (1- (match-beginning 0))) ?\") ; hack
  	      nil
  	    (add-text-properties (match-beginning 1) (match-end 1)
+ 				 '(invisible t))
+ 	    (add-text-properties (match-beginning 2) (match-end 2)
  				 '(font-lock-face info-xref
  				   mouse-face highlight
! 				   help-echo "mouse-2: go to this node"))
! 	    (add-text-properties (match-beginning 3) (match-end 3)
! 				 '(invisible t))))
! 
  	(goto-char (point-min))
  	(if (and (search-forward "\n* Menu:" nil t)
  		 (not (string-match "\\<Index\\>" Info-current-node))


-- 
Kim F. Storm  <storm@cua.dk>      http://www.cua.dk

Re: Hiding *Note:: "tags" in info files

[Francesco Potorti`]

>    *Note GETTING A PRINTED MANUAL::, if you would like a paper copy of
> the Emacs manual.
> 
> (which isn't perfect English either) becomes
> 
>    GETTING A PRINTED MANUAL, if you would like a paper copy of
> the Emacs manual.
> 
> WDYT?

A perfectly reasonable idea, IMO.

Re: Hiding *Note:: "tags" in info files

[Eli Zaretskii]

> From: "Kim F. Storm" <storm@cua.dk>
> Date: Tue, 29 Oct 2002 12:03:19 +0000 (GMT)
> 
> The result isn't perfect, since the wording around some of the nodes
> become a bit sparse, e.g. (upper case indicates highlighting)
> 
>    *Note GETTING A PRINTED MANUAL::, if you would like a paper copy of
> the Emacs manual.
> 
> (which isn't perfect English either) becomes
> 
>    GETTING A PRINTED MANUAL, if you would like a paper copy of
> the Emacs manual.

I suggest replacing "*Note" with "See" and removing "*note".

Re: Hiding *Note:: "tags" in info files

[Kim F. Storm]

Eli wrote:

> I suggest replacing "*Note" with "See" and removing "*note".

That would make sense in many places, but there are also places where
the *Notes are already in a "sensible" textual scope such as

	See *Note Some Topic:: for details.

Blindingly replacing *Note by See would change that to:

	See See Some Topic for details.


Perhaps we could look at the context and replace *Note by See
if the last non-whitespace character preceeding *Note
is a symbol (such as '.' or ',' or '('), and remove it otherwise.

I'll give it a try...

-- 
Kim F. Storm  <storm@cua.dk>      http://www.cua.dk

Re: Hiding *Note:: "tags" in info files

[Andreas Schwab]

"Kim F. Storm" <storm@cua.dk> writes:

|> Eli wrote:
|> 
|> > I suggest replacing "*Note" with "See" and removing "*note".
|> 
|> That would make sense in many places, but there are also places where
|> the *Notes are already in a "sensible" textual scope such as
|> 
|> 	See *Note Some Topic:: for details.

This is actually broken to begin with.  If used properly the xref commands
in texinfo never generate such an output.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Hiding *Note:: "tags" in info files

[Eli Zaretskii]

On Wed, 30 Oct 2002, Andreas Schwab wrote:

> |> That would make sense in many places, but there are also places where
> |> the *Notes are already in a "sensible" textual scope such as
> |> 
> |> 	See *Note Some Topic:: for details.
> 
> This is actually broken to begin with.  If used properly the xref commands
> in texinfo never generate such an output.

Right.  The correct usage ("See @ref...") produces "See *note...", with a 
lower-case `n'.

Re: Hiding *Note:: "tags" in info files

[Richard Stallman]

    The result isn't perfect, since the wording around some of the nodes
    become a bit sparse, e.g. (upper case indicates highlighting)

       *Note GETTING A PRINTED MANUAL::, if you would like a paper copy of
    the Emacs manual.

    (which isn't perfect English either) becomes

       GETTING A PRINTED MANUAL, if you would like a paper copy of
    the Emacs manual.

In the printed output, we would put "See " at the beginning".
Perhaps you can use a before-string to insert "See " before
the xref text.

Re: Hiding *Note:: "tags" in info files

[Andreas Schwab]

Eli Zaretskii <eliz@is.elta.co.il> writes:

|> On Wed, 30 Oct 2002, Andreas Schwab wrote:
|> 
|> > |> That would make sense in many places, but there are also places where
|> > |> the *Notes are already in a "sensible" textual scope such as
|> > |> 
|> > |> 	See *Note Some Topic:: for details.
|> > 
|> > This is actually broken to begin with.  If used properly the xref commands
|> > in texinfo never generate such an output.
|> 
|> Right.  The correct usage ("See @ref...") produces "See *note...", with a 
|> lower-case `n'.

The texinfo manual suggests to use @xref at start of sentence.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Hiding *Note:: "tags" in info files

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     The result isn't perfect, since the wording around some of the nodes
>     become a bit sparse, e.g. (upper case indicates highlighting)
> 
>        *Note GETTING A PRINTED MANUAL::, if you would like a paper copy of
>     the Emacs manual.
> 
>     (which isn't perfect English either) becomes
> 
>        GETTING A PRINTED MANUAL, if you would like a paper copy of
>     the Emacs manual.
> 
> In the printed output, we would put "See " at the beginning".
> Perhaps you can use a before-string to insert "See " before
> the xref text.

The following improved patch does that for *Note but not for *note.

BTW, should it handle *note Item: Section. differently from *note Item:: 
(e.g. by hiding the Section part)?

In any case, there are many incorrect uses of *Note: in the info files,
so you will still see a some "see See ..." occurrences.


Index: info.el
===================================================================
RCS file: /cvs/emacs/lisp/info.el,v
retrieving revision 1.318
diff -c -r1.318 info.el
*** info.el	8 Oct 2002 04:57:27 -0000	1.318
--- info.el	30 Oct 2002 15:47:22 -0000
***************
*** 2712,2724 ****
  	    (add-text-properties (match-beginning 2) (1+ (match-end 2))
  				 '(invisible t intangible t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\*Note[ \n\t]+\\([^:]*\\):" nil t)
  	  (if (= (char-after (1- (match-beginning 0))) ?\") ; hack
  	      nil
  	    (add-text-properties (match-beginning 1) (match-end 1)
  				 '(font-lock-face info-xref
  				   mouse-face highlight
! 				   help-echo "mouse-2: go to this node"))))
  	(goto-char (point-min))
  	(if (and (search-forward "\n* Menu:" nil t)
  		 (not (string-match "\\<Index\\>" Info-current-node))
--- 2712,2731 ----
  	    (add-text-properties (match-beginning 2) (1+ (match-end 2))
  				 '(invisible t intangible t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \n\t]+\\)\\([^:]*\\)\\(:+\\)" nil t)
  	  (if (= (char-after (1- (match-beginning 0))) ?\") ; hack
  	      nil
  	    (add-text-properties (match-beginning 1) (match-end 1)
+ 				 (if (= (char-after (1+ (match-beginning 1))) ?N)
+ 				     '(display "See ")
+ 				   '(invisible t)))
+ 	    (add-text-properties (match-beginning 2) (match-end 2)
  				 '(font-lock-face info-xref
  				   mouse-face highlight
! 				   help-echo "mouse-2: go to this node"))
! 	    (add-text-properties (match-beginning 3) (match-end 3)
! 				 '(invisible t))))
! 
  	(goto-char (point-min))
  	(if (and (search-forward "\n* Menu:" nil t)
  		 (not (string-match "\\<Index\\>" Info-current-node))


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Hiding *Note:: "tags" in info files

[Karl Eichwalder]

storm@cua.dk (Kim F. Storm) writes:

> The following improved patch does that for *Note but not for *note.

Please, don't touch this stuff well working; cf. Andreas' postings on
correct texinfo markup usage!

Seeing *Note or *note is very useful I you don't want to use font-lock.

If you want to improve Info think about implementing image support;
lately the lilypond maintainer asked for this feature.

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: Hiding *Note:: "tags" in info files

[Miles Bader]

Karl Eichwalder <keichwa@gmx.net> writes:
> Please, don't touch this stuff well working; cf. Andreas' postings on
> correct texinfo markup usage!
> 
> Seeing *Note or *note is very useful I you don't want to use font-lock.

It would be very simple to make the `invisible' parts be invisible only
when font-lock-mode is turned on.

[It could be done by having info use a `font-lock-invisible' property
instead of `invisible', and arranging for font-lock-mode to add an
appropriate mapping between the two to `char-property-alias-alist' when
font-lock-mode is turned on.  I'm not sure if this should be a feature
provided by font-lock-mode generally, or something info-specific.]

-Miles
-- 
"Most attacks seem to take place at night, during a rainstorm, uphill,
 where four map sheets join."   -- Anon. British Officer in WW I

Re: Hiding *Note:: "tags" in info files

[Eli Zaretskii]

On 31 Oct 2002, Kim F. Storm wrote:

> BTW, should it handle *note Item: Section. differently from *note Item:: 
> (e.g. by hiding the Section part)?

Perhaps we should go the TeX way here as well, i.e. remove the "*note" 
part and produce "Item [in Section]" instead.

Removing the "Section" part altogether is also a good idea.  It's there 
only for the browser to find the right node.

> In any case, there are many incorrect uses of *Note: in the info files,
> so you will still see a some "see See ..." occurrences.

Good!  Perhaps this will prompt users to report those places to the 
package maintainers.

Re: Hiding *Note:: "tags" in info files

[Richard Stallman]

    > This is actually broken to begin with.  If used properly the xref commands
    > in texinfo never generate such an output.

    Right.  The correct usage ("See @ref...") produces "See *note...", with a 
    lower-case `n'.

You should use @xref, not @ref, in a case like this.

Re: Hiding *Note:: "tags" in info files

[Richard Stallman]

    The following improved patch does that for *Note but not for *note.

    BTW, should it handle *note Item: Section. differently from *note Item:: 
    (e.g. by hiding the Section part)?

    In any case, there are many incorrect uses of *Note: in the info files,
    so you will still see a some "see See ..." occurrences.

How about checking for the presence of "see" in the buffer,
and putting in "See" only if there is no "see"?

Re: Hiding *Note:: "tags" in info files

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     The following improved patch does that for *Note but not for *note.
> 
>     BTW, should it handle *note Item: Section. differently from *note Item:: 
>     (e.g. by hiding the Section part)?
> 
>     In any case, there are many incorrect uses of *Note: in the info files,
>     so you will still see a some "see See ..." occurrences.
> 
> How about checking for the presence of "see" in the buffer,
> and putting in "See" only if there is no "see"?

There are also other contexts where it doesn't make sense to add "see"
instead of the *note or *Note.  

I have now committed a change which looks for preceeding punctuation
to determine whether it should add "See ", "see ", or nothing before
the note text.  This only happens when font-lock-mode is enabled.

It also hides the "Section" part of the *note:... links to further improve
readability.

Furthermore, it hides the Section part of menu items, and replaces it by
a suitable number of spaces to properly align (previously mis-aligned)
menus and sub-menus.

I used the intangible property to make moving around in the info
buffer with normal cursor motion act sensible; consequently, I had to
bind inhibit-point-motion-hooks to t in the functions which parses the
various cross references.

IMHO, the result looks quite good.  WDYT?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Hiding *Note:: "tags" in info files

[Karl Eichwalder]

storm@cua.dk (Kim F. Storm) writes:

> It also hides the "Section" part of the *note:... links to further improve
> readability.

This is from the gettext manual and it looks good to me:

   The command `_' (`po-undo') interfaces to the Emacs _undo_ facility.
*Note Undoing Changes: (emacs)Undo.

Do you intent to manipulate those pointers, too?  I don't want to loose
info, that following the reference I'll end up in the Emacs manual,
section "Undo".

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: Hiding *Note:: "tags" in info files

[Eli Zaretskii]

> From: Karl Eichwalder <keichwa@gmx.net>
> Date: Fri, 01 Nov 2002 03:24:06 +0100
> 
>    The command `_' (`po-undo') interfaces to the Emacs _undo_ facility.
> *Note Undoing Changes: (emacs)Undo.
> 
> Do you intent to manipulate those pointers, too?  I don't want to loose
> info, that following the reference I'll end up in the Emacs manual,
> section "Undo".

I don't see why this is important to know, but if it is, I guess we
could have a way to turn off the feature installed by Kim.

Or maybe we could do what the Web browsers do: show the node name in
the echo area or as a tooltip.

Re: Hiding *Note:: "tags" in info files

[Kim F. Storm]

Karl Eichwalder keichwa@gmx.net writes:

> > It also hides the "Section" part of the *note:... links to further improve
> > readability.
> 
> Do you intent to manipulate those pointers, too?  I don't want to loose
> info, that following the reference I'll end up in the Emacs manual,
> section "Undo".

The default is to hide those references (web pages are not
cluttered with the actual URLs for each link either, so I think this
what people would normally expect).

However, you can set Info-hide-note-references to nil to see them.

-- 
Kim F. Storm  <storm@cua.dk>      http://www.cua.dk

Re: Hiding *Note:: "tags" in info files

[Karl Eichwalder]

"Kim F. Storm" <storm@cua.dk> writes:

> The default is to hide those references (web pages are not
> cluttered with the actual URLs for each link either, so I think this
> what people would normally expect).

The status line usually shows them (e.g. lynx in expert mode).

-- 
ke@suse.de (work) / keichwa@gmx.net (home):              |
http://www.gnu.franken.de/ke/                            |      ,__o
Free Translation Project:                                |    _-\_<,
http://www.iro.umontreal.ca/contrib/po/HTML/             |   (*)/'(*)

Re: Hiding *Note:: "tags" in info files

[Stefan Monnier]

> I have now committed a change which looks for preceeding punctuation
> to determine whether it should add "See ", "see ", or nothing before
> the note text.  This only happens when font-lock-mode is enabled.

Am I the only one who finds that hardcoding english words is
very odd ?
I know this is done "pervasively" in info.el (and presumably makeinfo)...


	Stefan

Re: Hiding *Note:: "tags" in info files

[Kim F. Storm]

"Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> writes:

> > I have now committed a change which looks for preceeding punctuation
> > to determine whether it should add "See ", "see ", or nothing before
> > the note text.  This only happens when font-lock-mode is enabled.
> 
> Am I the only one who finds that hardcoding english words is
> very odd ?

No, you got a point there...  Any idea how to improve it?
I guess the proper thing would be to adapt to the language of the
info file, but that's probably too much guesswork...

> I know this is done "pervasively" in info.el (and presumably makeinfo)...

At least, Note and note are english words too...  :-)


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Hiding *Note:: "tags" in info files

[Eli Zaretskii]

> From: storm@cua.dk (Kim F. Storm)
> Date: 02 Nov 2002 00:22:34 +0100
> 
> > Am I the only one who finds that hardcoding english words is
> > very odd ?
> 
> No, you got a point there...  Any idea how to improve it?
> I guess the proper thing would be to adapt to the language of the
> info file

These keywords are in English because Info readers must recognize them.