Texinfo Mode: node-based movement functions.

Texinfo Mode: node-based movement functions.

[Alan Mackenzie]

Hi, Emacs!

In Texinfo Mode we have functions for moving to the beginning and end of
a "page" (i.e. a @chapter) and for narrowing to a @chapter (together with
its @sections).

I think there should also be functions for moving to the beginning and
end of an individual @node, and for narrowing to it.  "Obviously", a
@node in a file.texi is analogous to a defun in a file.el.  So the
natural key bindings are C-M-a, C-M-e, and C-x n d.

The following code is a first shot at implementing this functionality.
It is currently not bullet proof - in particular, it doesn't take account
of @ignore commands.  That would not, however, be hard to remedy.

Should I develop this into a production quality patch, complete with an
amendment to texinfo.txi, ChangeLog entry, etc.?

########################################################################
(defconst acm-texinfo-node-start "^@node .")
(defun acm-texinfo-beginning-of-node (&optional count)
  "Move backward to the beginning of a node.
With COUNT, do it that many times.  A negative COUNT will move forward.

A node starts at the \"@node\" command."
  (interactive "p")
  (if (< count 0)
      (acm-texinfo-end-of-node (- count))
    (unless (bolp) (end-of-line))       ; in case we're already inside "@node"
    (search-backward-regexp acm-texinfo-node-start nil 'limit count)))

(defun acm-texinfo-end-of-node (&optional count)
  "Move forward to the end of the current node.
With COUNT, do it that many times.  A negative COUNT will move backwards.

The end of a node is the \"@node\" which begins the next node or EOF."
  (interactive "p")
  (if (< count 0)
      (acm-texinfo-beginning-of-node (- count))
    (end-of-line)                       ; to make sure we move.
    (search-forward-regexp acm-texinfo-node-start nil 'limit count)
    (beginning-of-line)))

(defun acm-texinfo-narrow-to-node ()
  "Make the text outside the current node invisible.
This node is the one that contains point or follows point."
  (interactive)
  (widen)
  (save-excursion
    (let ((start
           (progn
             (unless (looking-at acm-texinfo-node-start)
               (end-of-line)
               (search-backward-regexp acm-texinfo-node-start nil 'limit))
             (point))))
      (end-of-line)
      (search-forward-regexp acm-texinfo-node-start nil 'limit)
      (beginning-of-line)
      (narrow-to-region start (point)))))

(eval-after-load "texinfo"
  '(progn
     (define-key texinfo-mode-map "\C-\M-a" 'acm-texinfo-beginning-of-node)
     (define-key texinfo-mode-map "\C-\M-e" 'acm-texinfo-end-of-node)
     (define-key texinfo-mode-map "\C-xnd" 'acm-texinfo-narrow-to-node)))

#########################################################################

-- 
Alan Mackenzie (Munich, Germany)

Re: Texinfo Mode: node-based movement functions.

[Alan Mackenzie]

Sorry!

I forgot to save the match data.  Here's a corrected version of the code.

On Sat, 6 Nov 2004, Alan Mackenzie wrote:

>Hi, Emacs!
>
>In Texinfo Mode we have functions for moving to the beginning and end of
>a "page" (i.e. a @chapter) and for narrowing to a @chapter (together with
>its @sections).
>
>I think there should also be functions for moving to the beginning and
>end of an individual @node, and for narrowing to it.  "Obviously", a
>@node in a file.texi is analogous to a defun in a file.el.  So the
>natural key bindings are C-M-a, C-M-e, and C-x n d.
>
>The following code is a first shot at implementing this functionality.
>It is currently not bullet proof - in particular, it doesn't take account
>of @ignore commands.  That would not, however, be hard to remedy.
>
>Should I develop this into a production quality patch, complete with an
>amendment to texinfo.txi, ChangeLog entry, etc.?

Corrected code:
########################################################################
(defconst acm-texinfo-node-start "^@node .")

(defun acm-texinfo-beginning-of-node (&optional count)
  "Move backward to the beginning of a node.
With COUNT, do it that many times.  A negative COUNT will move forward.

A node starts at the \"@node\" command."
  (interactive "p")
  (if (< count 0)
      (acm-texinfo-end-of-node (- count))
    (save-match-data
      (unless (bolp) (end-of-line))     ; in case we're already inside "@node"
      (search-backward-regexp acm-texinfo-node-start nil 'limit count))))

(defun acm-texinfo-end-of-node (&optional count)
  "Move forward to the end of the current node.
With COUNT, do it that many times.  A negative COUNT will move backwards.

The end of a node is the \"@node\" which begins the next node or EOF."
  (interactive "p")
  (if (< count 0)
      (acm-texinfo-beginning-of-node (- count))
    (save-match-data
      (end-of-line)                     ; to make sure we move.
      (search-forward-regexp acm-texinfo-node-start nil 'limit count)
      (beginning-of-line))))

(defun acm-texinfo-narrow-to-node ()
  "Make the text outside the current node invisible.
This node is the one that contains point or follows point."
  (interactive)
  (widen)
  (save-excursion
    (save-match-data
      (let ((start
             (progn
               (end-of-line)
               (search-backward-regexp acm-texinfo-node-start nil 'limit)
               (point))))
        (end-of-line)
        (if (search-forward-regexp acm-texinfo-node-start nil 'limit)
            (beginning-of-line))
        (narrow-to-region start (point))))))

(eval-after-load "texinfo"
  '(progn
     (define-key texinfo-mode-map "\C-\M-a" 'acm-texinfo-beginning-of-node)
     (define-key texinfo-mode-map "\C-\M-e" 'acm-texinfo-end-of-node)
     (define-key texinfo-mode-map "\C-xnd" 'acm-texinfo-narrow-to-node)))

#########################################################################

-- 
Alan Mackenzie (Munich, Germany)

Re: Texinfo Mode: node-based movement functions.

[Robert J. Chassell]

   In Texinfo Mode we have functions for moving to the beginning and end of
   a "page" (i.e. a @chapter) and for narrowing to a @chapter (together with
   its @sections).

   I think there should also be functions for moving to the beginning and
   end of an individual @node, and for narrowing to it.  ....

Why do you give a _node_ such relevance?  I am curious.  The reason is
that I have written many Texinfo documents over the past 18 years (or
more) and never needed a `goto Texinfo node command'.  If I had to go
to the node in Texinfo mode, I did a `C-s @no' or `C-r @no' and got
there.  (The search also brings up `@noindent' lines, but I ignore
them.  And clearly, most of my node-based movements have been to a
nearby node.)  Mostly, I have had to go to (and sometimes change)
content, which means going to chapters or sections.

Are you thinking of the other surface expressions besides Info that
Texinfo enables?  Certainly, nodes are published in Info, which is one
of the surface expressions.  They may be published in HTML -- I don't
know.  They are not published in a printed copy, whether using DVI,
PDF, XML, or PS.  I know that for sure, since I have to get rid of
nodes==sections that are too close to the first section of a chapter,
but should be in an Info file. (I keep the node but get rid of the
published section.)

However, a surface expression is not relevant to writing the deep
representation.  So perhaps the `goto Texinfo node commands' will be
useful to some writers.  (Fourteen ago, I wrote some
`texinfo-insert-...' commands that too few people cared about so they
were not included in the standard distribution.  However, they have
remained part of my .emacs file ever since.  I found the lack of
inclusion really weird since I use them.  Moreover, I always thought
of myself as an exemplar of the average so others should use them,
too.  Evidentally I am not such an exemplar.  Are your node movement
commands the same or are they useful by many other people?)

In any event, if you continue to develop the commands, please take
account of @ignore and the rest; they are used often by everyone.

Thank you.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Texinfo Mode: node-based movement functions.

[Alan Mackenzie]

Hi, Robert!

On Sat, 6 Nov 2004, Robert J. Chassell wrote:

>
>   In Texinfo Mode we have functions for moving to the beginning and end of
>   a "page" (i.e. a @chapter) and for narrowing to a @chapter (together with
>   its @sections).
>
>   I think there should also be functions for moving to the beginning and
>   end of an individual @node, and for narrowing to it.  ....

>Why do you give a _node_ such relevance?  I am curious.  The reason is
>that I have written many Texinfo documents over the past 18 years (or
>more) and never needed a `goto Texinfo node command'.  If I had to go
>to the node in Texinfo mode, I did a `C-s @no' or `C-r @no' and got
>there.  (The search also brings up `@noindent' lines, but I ignore
>them.  And clearly, most of my node-based movements have been to a
>nearby node.)  Mostly, I have had to go to (and sometimes change)
>content, which means going to chapters or sections.

I have edited only very few Texinfo files, and all of these have been in
the heierarchical style encouraged by Texinfo Mode (i.e. every @section
etc. is a @node, @chapters "contain" @sections, ....).  I am currently
refurbishing cc-mode.texi.  This has involved a lot of shifting of
nodes from one place to another.  Up until yesterday I'd been using
`C-M-[rs] ^@node' and it'd got on my nerves to the point where I couldn't
stand it any more. ;-)

Why do I focus so much on nodes?  It seems to me that a node is a
coherent whole, much like a defun in other languages.  It is, after all,
exactly the unit that is displayed by Info.  I often narrow to a node,
then search through it or scan through it to make sure all the pertinent
material is in that node.  Or I quickly scroll through the (narrowed)
node to get a feel for its size.

>Are you thinking of the other surface expressions besides Info that
>Texinfo enables?  Certainly, nodes are published in Info, which is one
>of the surface expressions.  They may be published in HTML -- I don't
>know.  They are not published in a printed copy, whether using DVI,
>PDF, XML, or PS.  I know that for sure, since I have to get rid of
>nodes==sections that are too close to the first section of a chapter,
>but should be in an Info file. (I keep the node but get rid of the
>published section.)

I've never seen a printed form of a Texinfo manual.  What do you mean by
"too close" here?  What blemish does this closeness cause?  By "get rid
of", you mean with @ifinfo, or the like?

>However, a surface expression is not relevant to writing the deep
>representation.  So perhaps the `goto Texinfo node commands' will be
>useful to some writers.  (Fourteen ago, I wrote some
>`texinfo-insert-...' commands that too few people cared about so they
>were not included in the standard distribution.  However, they have
>remained part of my .emacs file ever since.  I found the lack of
>inclusion really weird since I use them.  Moreover, I always thought
>of myself as an exemplar of the average so others should use them,
>too.  Evidentally I am not such an exemplar.  Are your node movement
>commands the same or are they useful by many other people?)

I feel that I am a typical Texinfo user.  Then again, I feel I'm a
typical C and C++ programmer, too.  I've little objective evidence to
back these feelings up, and quite a bit to refute them.  ;-(  I think I
posted the code as a working idea, rather than a completed patch, to test
for a general want of @node functionality.  So far, there hasn't been any
resonance from anybody else, so the commands will probably just stay in
my .emacs. 

>In any event, if you continue to develop the commands, please take
>account of @ignore and the rest; they are used often by everyone.

I certainly will.  Thanks for the feedback!

>    Robert J. Chassell                         

-- 
Alan Mackenzie (Munich, Germany)

Re: Texinfo Mode: node-based movement functions.

[Robert J. Chassell]

   Why do I focus so much on nodes?  

What do you think of `C-c C-s' (texinfo-show-structure), especially
when called with a prefix arg, so it lists the @node lines, too?

   I've never seen a printed form of a Texinfo manual.  

Ah...  Even if you do not print it out, please run

    texi2dvi cc-mode.texi

to create a DVI version of the CC Mode manual, and look at it using 

    xdvi cc-mode.dvi &

Indeed, please put the following at the beginning of cc-mode.texi:

@end ignore

    ## Info output
    makeinfo --no-split --paragraph-indent=0 --verbose cc-mode.texi

    ## DVI output
    texi2dvi cc-mode.texi

    ## HTML output
    makeinfo --html --no-split --verbose cc-mode.texi

    ## Plain text output
    makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
    --verbose --no-headers --output=cc-mode.txt cc-mode.texi

    ## DocBook output
    makeinfo --docbook --no-split --paragraph-indent=0 \
    --verbose cc-mode.texi

    ## XML output
    makeinfo --xml --no-split --paragraph-indent=0 \
    --verbose cc-mode.texi

    #### (You must be in the same directory as the viewed file.)

      ## View DVI output
      xdvi cc-mode.dvi &

      ## View HTML output
      mozilla cc-mode.html

@end ignore

For an example, see 

    emacs/lispintro/emacs-lisp-intro.texi

in the Emacs distribution.

It is a good idea to run the commands to create the Info, HTML, and
DVI outputs frequently and to look at them.  That way, you can catch
errors early on.  (It is also a good idea to listen to the Info using
Emacspeak, as if you were driving a car or permanently blind.  If the
document makes sense when you listen to it, it is well written.  Now
that Emacspeak has good-enough, free software text-to-speech
synthesizers, anyone can do this.)


   What do you mean by "too close" here?  

Woops!  I was being old fashioned.  I had forgot about XML.  I had
meant to push you towards @heading but should direct you instead to
the less good @unnumberedsec.

As for being "too close" -- it is best to start a section within 24 or
so lines of the beginning of a chapter so that the section menu is
visible in Info.  However, in a printed book, that looks bad.  So, in
the old days, we hid that first section line by putting it in
`@ifinfo'.  But XML has come along, so instead the Texinfo manual
says:

    (texinfo)Menu Location

      In the past, we recommended using a `@heading' command within an
    `@ifinfo' conditional instead of the normal sectioning commands
    after a very short node with a menu.  This had the advantage of
    making the printed output look better, because there was no very
    short text between two headings on the page.  But aside from not
    working with `makeinfo''s implicit pointer creation, it also makes
    the XML output incorrect, since it does not reflect the true
    document structure.  So, unfortunately we can no longer recommend
    this.

One modern way to do the job is to use @unnumberedsec in place of
@section for the first subnode of a chapter (or lower level
construct).  This does not always produce the right output, but ....

For example, emacs/lispintro/emacs-lisp-intro.texi has this format
(leaving out the @node lines that a prefix arg to
texinfo-show-structure provides):

   1053:@chapter List Processing
   1083:    @section Lisp Lists
   1115:        @unnumberedsubsec Numbers, Lists inside of Lists
   1144:        @subsection Lisp Atoms
   1225:        @subsection Whitespace in Lists

Please compare the Info output with the DVI output.  That works out
well.

The table of contents for the HTML output, which is in 
    emacs/info/eintr.html
looks like this, which is a problem with this format, but not a big one:

    1.1 Lisp Lists
        * Numbers, Lists inside of Lists
        * 1.1.1 Lisp Atoms
        * 1.1.2 Whitespace in Lists 

Since Info and printed copies are the most efficient forms in which a
Texinfo document appears (and probably the most common, although many
people use the less efficient HTML format), the lack of a number for
the `unnumbered' HTML node is OK.  Someday, I must look at the XML but
since I fear the worst, I have not....

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Texinfo Mode: node-based movement functions.

[Richard Stallman]

    I think there should also be functions for moving to the beginning and
    end of an individual @node, and for narrowing to it.  "Obviously", a
    @node in a file.texi is analogous to a defun in a file.el.  So the
    natural key bindings are C-M-a, C-M-e, and C-x n d.

I think that smaller constructs such as @defun are comparable to
defuns.  A node is more comparable to a page.  So I think the page
commands should be changed to operate on individual nodes, rather than
entire chapters.  Do others agree?

Re: Texinfo Mode: node-based movement functions.

[Stefan]

> In Texinfo Mode we have functions for moving to the beginning and end of
> a "page" (i.e. a @chapter) and for narrowing to a @chapter (together with
> its @sections).

I agree with Richard, that chapter==page i pretty useless and we should
use node==page instead.

> I think there should also be functions for moving to the beginning and
> end of an individual @node, and for narrowing to it.  "Obviously", a
> @node in a file.texi is analogous to a defun in a file.el.  So the
> natural key bindings are C-M-a, C-M-e, and C-x n d.

Why worry about keybindings?  Why not just set beginning-of-defun-function
(or page-delimiter)?


        Stefan

Re: Texinfo Mode: node-based movement functions.

[Alan Mackenzie]

Hi, Stefan!

On Mon, 8 Nov 2004, Stefan wrote:

>> In Texinfo Mode we have functions for moving to the beginning and end
>> of a "page" (i.e. a @chapter) and for narrowing to a @chapter
>> (together with its @sections).

>I agree with Richard, that chapter==page is pretty useless and we should
>use node==page instead.

I don't find chapter==page useful either, but somebody probably does (the
person who implemented it?).  I don't think I'd personally find Richard's
suggestion of @def\(un\|fn\|mac\|spec\)==defun very useful, but I haven't
tried it out.

>> I think there should also be functions for moving to the beginning and
>> end of an individual @node, and for narrowing to it.  "Obviously", a
>> @node in a file.texi is analogous to a defun in a file.el.  So the
>> natural key bindings are C-M-a, C-M-e, and C-x n d.

>Why worry about keybindings?  Why not just set beginning-of-defun-function
>(or page-delimiter)?

(i) The beginning-of-defun-function mechanism is broken in 21.3 - the
COUNT argument is not passed through to b-o-d-f.

(ii) Do (setq page-delimiter "^@node").  C-x [ and C-x ] then leave point
after "@node" rather before it.  I find this irritating - "@node" is part
of and begins the @chaper/@section/@subsection/.... that follows it
rather than terminating the @c/@s/@ss that preceded it.

BRILLIANT IDEA COMING UP!!!!!

Why not enhance the meaning of page-delimiter?  It should be either a
regexp, as at present, or a cons cell like ("\\(^\\)@node" . 1), where
the "1" means "the page boundary is at (match-beginning 1)"?  Even
better, ("^@node" . 0) would leave point at (match-beginning 0), the
_start_ of the regexp.  Perhaps, even, (regexp . -1) could mean
(match-end 1).

Incidentally, why is page-delimiter defined in paragraphs.el (where it is
not used) rather than in page.el?

>        Stefan

-- 
Alan Mackenzie (Munich, Germany)

Re: Texinfo Mode: node-based movement functions.

[Stefan Monnier]

>> Why worry about keybindings?  Why not just set beginning-of-defun-function
>> (or page-delimiter)?
> (i) The beginning-of-defun-function mechanism is broken in 21.3 - the
> COUNT argument is not passed through to b-o-d-f.

But you won't retroactively change texinfo.el for Emacs-21.3 anyway, so this
shouldn't be a consideration.  Either it's fixed in Emacs-CVS and you can
use it for Emacs-CVS's texinfo.el or it's not fixed in which case you should
get it fixed first.  AFAIK it is fixed.

> Why not enhance the meaning of page-delimiter?  It should be either a
> regexp, as at present, or a cons cell like ("\\(^\\)@node" . 1), where
> the "1" means "the page boundary is at (match-beginning 1)"?  Even
> better, ("^@node" . 0) would leave point at (match-beginning 0), the
> _start_ of the regexp.  Perhaps, even, (regexp . -1) could mean
> (match-end 1).

And how do you specify the case of "\f\\|@node" ?
Nah... just make it possible to use a function and be done with it.


        Stefan

Re: Texinfo Mode: node-based movement functions.

[Richard Stallman]

    Why worry about keybindings?  Why not just set beginning-of-defun-function
    (or page-delimiter)?

That's what I had in mind.