bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 879 bytes --]

The attached patch adds movement commands for texinfo-mode that move
between the start and end of single-level environments (things that
end with an @end line), e.g. @table.

    (define-key map "\C-c."        'texinfo-to-environment-bounds) -
when within an environment, moves between the start and end lines

    (define-key map "\C-c\C-c\C-f" 'texinfo-next-environment-end) -
from anywhere, moves to the next end line of an environment

    (define-key map "\C-c\C-c\C-b" 'texinfo-previous-environment-end)
- from anywhere, moves to the previous end line of an environment

    (define-key map "\C-c\C-c\C-n" 'texinfo-next-environment-start) -
from anywhere, moves to the next start line of an environment

    (define-key map "\C-c\C-c\C-p"
'texinfo-previous-environment-start) - from anywhere, moves to the
previous start line of an environment

See attached for the patch.

[-- Attachment #2: texinfo.el.patch --]
[-- Type: application/octet-stream, Size: 3508 bytes --]

*** texinfo-orig.el	2016-07-14 12:06:08.000000000 -0400
--- texinfo.el		2016-07-14 12:06:08.000000000 -0400
***************
*** 480,485 ****
--- 480,492 ----
      (define-key map "\C-c\C-ce"    'texinfo-insert-@end)
      (define-key map "\C-c\C-cd"    'texinfo-insert-@dfn)
      (define-key map "\C-c\C-cc"    'texinfo-insert-@code)
+ 
+     ;; bindings for environment movement
+     (define-key map "\C-c."        'texinfo-to-environment-bounds)
+     (define-key map "\C-c\C-c\C-f" 'texinfo-next-environment-end)
+     (define-key map "\C-c\C-c\C-b" 'texinfo-previous-environment-end)
+     (define-key map "\C-c\C-c\C-n" 'texinfo-next-environment-start)
+     (define-key map "\C-c\C-c\C-p" 'texinfo-previous-environment-start)
      map))
  
  (easy-menu-define texinfo-mode-menu
***************
*** 1032,1037 ****
--- 1039,1111 ----
    ;;               job-number"\n"))
    (tex-recenter-output-buffer nil))
  
+ ;;; Texinfo environment, e.g. @table, movement commands
+ ;; Author: Bob Weiner <rsw@gnu.org>, Orig-Date: 7/14/2016
+ ;; Copyright (C) 2016  Free Software Foundation, Inc.
+ 
+ (defun texinfo-to-environment-bounds ()
+   "If within a Texinfo environment with an @end, move point first to its starting line and then to its ending line.
+ Do nothing when outside of an environment; this does not handle nested environments."
+   (interactive)
+   (cond ((save-excursion
+ 	   (forward-line 0)
+ 	   (looking-at texinfo-environment-regexp))
+ 	 (if (save-excursion
+ 	       (forward-line 0)
+ 	       (looking-at "^@end"))
+ 	     (texinfo-previous-environment-start)
+ 	   (texinfo-next-environment-end)))
+ 	((save-excursion
+ 	   (and (re-search-backward texinfo-environment-regexp nil t)
+ 		(not (looking-at "^@end"))))
+ 	 (texinfo-previous-environment-start))
+ 	;; Otherwise, point is outside of an environment, so do nothing.
+ 	))
+ 
+ (defun texinfo-next-environment-start ()
+   "Move forward to the beginning of a Texinfo environment that ends with an @end."
+   (interactive)
+   (if (looking-at texinfo-environment-regexp)
+       (forward-line 1))
+   (while (and (re-search-forward texinfo-environment-regexp nil t)
+ 	      (save-excursion
+ 		(goto-char (match-beginning 0))
+ 		(looking-at "@end"))))
+   (if (save-excursion
+ 	(forward-line 0)
+ 	(looking-at texinfo-environment-regexp))
+       (forward-line 0)))
+ 
+ (defun texinfo-previous-environment-start ()
+   "Move back to the beginning of the previous Texinfo environment that ends with an @end."
+   (interactive)
+   (while (and (re-search-backward texinfo-environment-regexp nil t)
+ 	      (save-excursion
+ 		(goto-char (match-beginning 0))
+ 		(looking-at "@end")))))
+ 
+ (defun texinfo-next-environment-end ()
+   "Move forward to the beginning of the next @end line of a Texinfo environment."
+   (interactive)
+   (if (looking-at "^@end")
+       (forward-line 1))
+   (while (and (re-search-forward texinfo-environment-regexp nil t)
+ 	      (save-excursion
+ 		(goto-char (match-beginning 0))
+ 		(not (looking-at "^@end")))))
+   (if (save-excursion
+ 	(forward-line 0)
+ 	(looking-at "^@end"))
+       (forward-line 0)))
+ 
+ (defun texinfo-previous-environment-end ()
+   "Move backward to the beginning of the next @end line of a Texinfo environment."
+   (interactive)
+   (while (and (re-search-backward texinfo-environment-regexp nil t)
+ 	      (save-excursion
+ 		(goto-char (match-beginning 0))
+ 		(not (looking-at "@end"))))))
+ 
  (provide 'texinfo)
  
  ;;; texinfo.el ends here

bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1103 bytes --]

Neat! What about C-c C-f/b/n/p insteaf of C-c C-c C-f/b/n/p, though? Org-mode uses these, IIRC.

Clément.

On 2016-07-14 18:19, Robert Weiner wrote:
> The attached patch adds movement commands for texinfo-mode that move
> between the start and end of single-level environments (things that
> end with an @end line), e.g. @table.
> 
>     (define-key map "\C-c."        'texinfo-to-environment-bounds) -
> when within an environment, moves between the start and end lines
> 
>     (define-key map "\C-c\C-c\C-f" 'texinfo-next-environment-end) -
> from anywhere, moves to the next end line of an environment
> 
>     (define-key map "\C-c\C-c\C-b" 'texinfo-previous-environment-end)
> - from anywhere, moves to the previous end line of an environment
> 
>     (define-key map "\C-c\C-c\C-n" 'texinfo-next-environment-start) -
> from anywhere, moves to the next start line of an environment
> 
>     (define-key map "\C-c\C-c\C-p"
> 'texinfo-previous-environment-start) - from anywhere, moves to the
> previous start line of an environment
> 
> See attached for the patch.
> 


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Thu, 14 Jul 2016 12:19:46 -0400
> 
> The attached patch adds movement commands for texinfo-mode that move
> between the start and end of single-level environments (things that
> end with an @end line), e.g. @table.

Thanks.  Allow me a few comments.

> + ;;; Texinfo environment, e.g. @table, movement commands
> + ;; Author: Bob Weiner <rsw@gnu.org>, Orig-Date: 7/14/2016
> + ;; Copyright (C) 2016  Free Software Foundation, Inc.

We don't put such comments into the code, the log entry and AUTHORS
serve this purpose.

> + (defun texinfo-to-environment-bounds ()
> +   "If within a Texinfo environment with an @end, move point first to its starting line and then to its ending line.

The first line of a doc string should not be wider than 67 characters,
certainly not more than 78, and it should still be a complete sentence
that summarizes what the function does.

> + Do nothing when outside of an environment; this does not handle nested environments."

Other lines should also be broken at character 70.

I think these additions should be also reflected in NEWS.

bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

[Robert Weiner]

On Thu, Jul 14, 2016 at 3:19 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> Thanks.  Allow me a few comments.

Thanks for the feedback.

>
>> + ;;; Texinfo environment, e.g. @table, movement commands
>> + ;; Author: Bob Weiner <rsw@gnu.org>, Orig-Date: 7/14/2016
>> + ;; Copyright (C) 2016  Free Software Foundation, Inc.

>
> We don't put such comments into the code, the log entry and AUTHORS
> serve this purpose.

I just put that in there for the reference of whoever actually patches
the Emacs sources, not to be kept in there.

>
>> + (defun texinfo-to-environment-bounds ()
>> +   "If within a Texinfo environment with an @end, move point first to its starting line and then to its ending line.
>
> The first line of a doc string should not be wider than 67 characters,
> certainly not more than 78, and it should still be a complete sentence
> that summarizes what the function does.

It is a sentence and I always make the first line of a doc string
stand alone but often the complexity makes these first lines long.
I then wrap further lines at 78 or less.  I will keep this advice in
mind but will no doubt find it hard to be clear and complete with
in such a short space.

>
>> + Do nothing when outside of an environment; this does not handle nested environments."
>
> Other lines should also be broken at character 70.

Is that really done throughout Emacs?  With today's wider screens, I
would think some relaxation would be permitted.

> I think these additions should be also reflected in NEWS.

Yes.

Bob

bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 983 bytes --]

On 2016-07-14 21:43, Robert Weiner wrote:
>>> >> + (defun texinfo-to-environment-bounds ()
>>> >> +   "If within a Texinfo environment with an @end, move point first to its starting line and then to its ending line.
>> >
>> > The first line of a doc string should not be wider than 67 characters,
>> > certainly not more than 78, and it should still be a complete sentence
>> > that summarizes what the function does.
>
> It is a sentence and I always make the first line of a doc string
> stand alone but often the complexity makes these first lines long.
> I then wrap further lines at 78 or less.  I will keep this advice in
> mind but will no doubt find it hard to be clear and complete with
> in such a short space.

What about ‘Move to first line of current environment, then to last.’? Does that describe the behaviour of the function accurately?

(In fact, there's even space for ‘Move to first line of current Texinfo environment, then to last.’)


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

[Eli Zaretskii]

> From: Robert Weiner <rsw@gnu.org>
> Date: Thu, 14 Jul 2016 15:43:44 -0400
> Cc: 23985@debbugs.gnu.org, bug-texinfo@gnu.org
> 
> On Thu, Jul 14, 2016 at 3:19 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> > Thanks.  Allow me a few comments.
> 
> Thanks for the feedback.
> 
> >
> >> + ;;; Texinfo environment, e.g. @table, movement commands
> >> + ;; Author: Bob Weiner <rsw@gnu.org>, Orig-Date: 7/14/2016
> >> + ;; Copyright (C) 2016  Free Software Foundation, Inc.
> 
> >
> > We don't put such comments into the code, the log entry and AUTHORS
> > serve this purpose.
> 
> I just put that in there for the reference of whoever actually patches
> the Emacs sources, not to be kept in there.

If you send the patch in the form of git-format-patch, those details
are taken care for you by Git.

> >> + (defun texinfo-to-environment-bounds ()
> >> +   "If within a Texinfo environment with an @end, move point first to its starting line and then to its ending line.
> >
> > The first line of a doc string should not be wider than 67 characters,
> > certainly not more than 78, and it should still be a complete sentence
> > that summarizes what the function does.
> 
> It is a sentence and I always make the first line of a doc string
> stand alone but often the complexity makes these first lines long.
> I then wrap further lines at 78 or less.  I will keep this advice in
> mind but will no doubt find it hard to be clear and complete with
> in such a short space.

Clément suggested a shorter wording that would fit.  I can suggest
another:

  Go to the beginning or @end of the current Texinfo environment.

You don't have to say it all in the first sentence, only the main
point of the function.  The details are described in the rest of the
doc string.

> > Other lines should also be broken at character 70.
> 
> Is that really done throughout Emacs?  With today's wider screens, I
> would think some relaxation would be permitted.

Maybe so, but the current guidelines still say the above.  Feel free
to raise this issue on emacs-devel.

Thanks.

bug#23985: Emacs 25.0.94: FEATURE ADDITION: Texinfo environment movement commands

[Lars Ingebrigtsen]

Robert Weiner <rsw@gnu.org> writes:

> The attached patch adds movement commands for texinfo-mode that move
> between the start and end of single-level environments (things that
> end with an @end line), e.g. @table.

Thanks; looks like quite useful commands to me, so I went ahead and
applied this to Emacs 28.  I adjusted the doc strings to adhere to the
normal style first.

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