* allout mode patch for a few small bugs and cleanup of mode docstring
@ 2006-11-29 20:51 Ken Manheimer
2006-11-29 23:27 ` Kim F. Storm
0 siblings, 1 reply; 4+ messages in thread
From: Ken Manheimer @ 2006-11-29 20:51 UTC (permalink / raw)
[-- Attachment #1: Type: text/plain, Size: 1247 bytes --]
the attached patch resolves a few stray bugs and provides a much
needed cleanup of the allout-mode docstring, which is the central
documentation for the mode. (the bug fixes are small - more than 4/5
of the patch is for the allout-mode docstring changes.)
the bugs resolved:
- depth accommodation for yanks containing multiple topics was broken
- viewing the mode docstring before the mode was first invoked
would fail to find any keybindings
the changelog is below and attached.
--
ken
ken.manheimer@gmail.com
http://myriadicity.net
2006-11-28 Ken Manheimer <ken.manheimer@gmail.com>
* allout.el (allout-ascend): Add an optional argument to preserve
original position of point when unsuccessful. Also, fix a
docstring error.
(allout-yank-processing): Fix depth shift of multiple-topic yanks
work again, using allout-ascend's new option.
(allout-setup-mode-map): Extracted from allout-mode to initialize
allout-mode-map. Call this function on file load, so the mode
docstring substitutions work even if allout mode has not yet been
invoked.
(allout-mode): Use new allout-setup-mode-map to track any
keybinding customizations since the map was last processed. Also,
refine the docstring so it's ship-shape for release.
[-- Attachment #2: allout-patch.txt --]
[-- Type: text/plain, Size: 24464 bytes --]
Index: allout.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/allout.el,v
retrieving revision 1.89
diff -u -u -r1.89 allout.el
--- allout.el 15 Nov 2006 16:34:20 -0000 1.89
+++ allout.el 29 Nov 2006 20:40:25 -0000
@@ -1651,90 +1651,109 @@
navigation and exposure. It also is specifically aimed at
accommodating syntax-sensitive text like programming languages. \(For
an example, see the allout code itself, which is organized as an allout
-outline.)
+outline.\)
-In addition to outline navigation and exposure, allout includes:
+In addition to typical outline navigation and exposure, allout includes:
- - topic-oriented repositioning, promotion/demotion, cut, and paste
- - integral outline exposure-layout
+ - topic-oriented authoring, including keystroke-based topic creation,
+ repositioning, promotion/demotion, cut, and paste
- incremental search with dynamic exposure and reconcealment of hidden text
- - automatic topic-number maintenance
+ - adjustable format, so programming code can be developed in outline-structure
- easy topic encryption and decryption
- - \"Hot-spot\" operation, for single-keystroke maneuvering and
- exposure control. \(See the allout-mode docstring.)
+ - \"Hot-spot\" operation, for single-keystroke maneuvering and exposure control
+ - integral outline layout, for automatic initial exposure when visiting a file
+ - independent extensibility, using comprehensive exposure and authoring hooks
and many other features.
-Below is a description of the bindings, and then explanation of
+Below is a description of the key bindings, and then explanation of
special `allout-mode' features and terminology. See also the outline
menubar additions for quick reference to many of the features, and see
the docstring of the function `allout-init' for instructions on
priming your emacs session for automatic activation of `allout-mode'.
-
-The bindings are dictated by the `allout-keybindings-list' and
-`allout-command-prefix' variables.
-
- Navigation: Exposure Control:
- ---------- ----------------
-\\[allout-next-visible-heading] allout-next-visible-heading | \\[allout-hide-current-subtree] allout-hide-current-subtree
-\\[allout-previous-visible-heading] allout-previous-visible-heading | \\[allout-show-children] allout-show-children
-\\[allout-up-current-level] allout-up-current-level | \\[allout-show-current-subtree] allout-show-current-subtree
-\\[allout-forward-current-level] allout-forward-current-level | \\[allout-show-current-entry] allout-show-current-entry
-\\[allout-backward-current-level] allout-backward-current-level | \\[allout-show-all] allout-show-all
-\\[allout-end-of-entry] allout-end-of-entry
-\\[allout-beginning-of-current-entry] allout-beginning-of-current-entry, alternately, goes to hot-spot
-
- Topic Header Production:
- -----------------------
-\\[allout-open-sibtopic] allout-open-sibtopic Create a new sibling after current topic.
-\\[allout-open-subtopic] allout-open-subtopic ... an offspring of current topic.
-\\[allout-open-supertopic] allout-open-supertopic ... a sibling of the current topic's parent.
-
- Topic Level and Prefix Adjustment:
- ---------------------------------
-\\[allout-shift-in] allout-shift-in Shift current topic and all offspring deeper.
-\\[allout-shift-out] allout-shift-out ... less deep.
-\\[allout-rebullet-current-heading] allout-rebullet-current-heading Prompt for alternate bullet for
- current topic.
-\\[allout-rebullet-topic] allout-rebullet-topic Reconcile bullets of topic and its offspring
- - distinctive bullets are not changed, others
- alternated according to nesting depth.
-\\[allout-number-siblings] allout-number-siblings Number bullets of topic and siblings - the
- offspring are not affected. With repeat
- count, revoke numbering.
-
- Topic-oriented Killing and Yanking:
- ----------------------------------
-\\[allout-kill-topic] allout-kill-topic Kill current topic, including offspring.
-\\[allout-copy-topic-as-kill] allout-copy-topic-as-kill Copy current topic, including offspring.
-\\[allout-kill-line] allout-kill-line kill-line, attending to outline structure.
-\\[allout-copy-line-as-kill] allout-copy-line-as-kill Copy line but don't delete it.
-\\[allout-yank] allout-yank Yank, adjusting depth of yanked topic to
- depth of heading if yanking into bare topic
- heading (ie, prefix sans text).
-\\[allout-yank-pop] allout-yank-pop Is to allout-yank as yank-pop is to yank
-
- Topic-oriented Encryption:
- -------------------------
-\\[allout-toggle-current-subtree-encryption] allout-toggle-current-subtree-encryption Encrypt/Decrypt topic content
-
- Misc commands:
- -------------
-M-x outlineify-sticky Activate outline mode for current buffer,
- and establish a default file-var setting
- for `allout-layout'.
-\\[allout-mark-topic] allout-mark-topic
-\\[allout-copy-exposed-to-buffer] allout-copy-exposed-to-buffer
- Duplicate outline, sans concealed text, to
- buffer with name derived from derived from that
- of current buffer - \"*BUFFERNAME exposed*\".
-\\[allout-flatten-exposed-to-buffer] allout-flatten-exposed-to-buffer
- Like above 'copy-exposed', but convert topic
- prefixes to section.subsection... numeric
- format.
-\\[eval-expression] (allout-init t) Setup Emacs session for outline mode
- auto-activation.
+The bindings are dictated by the customizable `allout-keybindings-list'
+variable. We recommend customizing `allout-command-prefix' to use just
+`\\C-c' as the command prefix, if the allout bindings don't conflict with
+any personal bindings you have on \\C-c. In any case, outline structure
+navigation and authoring is simplified by positioning the cursor on an
+item's bullet character, the \"hot-spot\" - then you can invoke allout
+commands with just the un-prefixed, un-control-shifted command letters.
+This is described further in the HOT-SPOT Operation section.
+
+ Exposure Control:
+ ----------------
+\\[allout-hide-current-subtree] `allout-hide-current-subtree'
+\\[allout-show-children] `allout-show-children'
+\\[allout-show-current-subtree] `allout-show-current-subtree'
+\\[allout-show-current-entry] `allout-show-current-entry'
+\\[allout-show-all] `allout-show-all'
+
+ Navigation:
+ ----------
+\\[allout-next-visible-heading] `allout-next-visible-heading'
+\\[allout-previous-visible-heading] `allout-previous-visible-heading'
+\\[allout-up-current-level] `allout-up-current-level'
+\\[allout-forward-current-level] `allout-forward-current-level'
+\\[allout-backward-current-level] `allout-backward-current-level'
+\\[allout-end-of-entry] `allout-end-of-entry'
+\\[allout-beginning-of-current-entry] `allout-beginning-of-current-entry' \(alternately, goes to hot-spot\)
+\\[allout-beginning-of-line] `allout-beginning-of-line' - like regular beginning-of-line, but
+ if immediately repeated cycles to the beginning of the current item
+ and then to the hot-spot \(if `allout-beginning-of-line-cycles' is set\).
+
+
+ Topic Header Production:
+ -----------------------
+\\[allout-open-sibtopic] `allout-open-sibtopic' Create a new sibling after current topic.
+\\[allout-open-subtopic] `allout-open-subtopic' ... an offspring of current topic.
+\\[allout-open-supertopic] `allout-open-supertopic' ... a sibling of the current topic's parent.
+
+ Topic Level and Prefix Adjustment:
+ ---------------------------------
+\\[allout-shift-in] `allout-shift-in' Shift current topic and all offspring deeper
+\\[allout-shift-out] `allout-shift-out' ... less deep
+\\[allout-rebullet-current-heading] `allout-rebullet-current-heading' Prompt for alternate bullet for
+ current topic
+\\[allout-rebullet-topic] `allout-rebullet-topic' Reconcile bullets of topic and
+ its' offspring - distinctive bullets are not changed, others
+ are alternated according to nesting depth.
+\\[allout-number-siblings] `allout-number-siblings' Number bullets of topic and siblings -
+ the offspring are not affected.
+ With repeat count, revoke numbering.
+
+ Topic-oriented Killing and Yanking:
+ ----------------------------------
+\\[allout-kill-topic] `allout-kill-topic' Kill current topic, including offspring.
+\\[allout-copy-topic-as-kill] `allout-copy-topic-as-kill' Copy current topic, including offspring.
+\\[allout-kill-line] `allout-kill-line' kill-line, attending to outline structure.
+\\[allout-copy-line-as-kill] `allout-copy-line-as-kill' Copy line but don't delete it.
+\\[allout-yank] `allout-yank' Yank, adjusting depth of yanked topic to
+ depth of heading if yanking into bare topic
+ heading \(ie, prefix sans text\).
+\\[allout-yank-pop] `allout-yank-pop' Is to allout-yank as yank-pop is to yank
+
+ Topic-oriented Encryption:
+ -------------------------
+\\[allout-toggle-current-subtree-encryption] `allout-toggle-current-subtree-encryption'
+ Encrypt/Decrypt topic content
+
+ Misc commands:
+ -------------
+M-x outlineify-sticky Activate outline mode for current buffer,
+ and establish a default file-var setting
+ for `allout-layout'.
+\\[allout-mark-topic] `allout-mark-topic'
+\\[allout-copy-exposed-to-buffer] `allout-copy-exposed-to-buffer'
+ Duplicate outline, sans concealed text, to
+ buffer with name derived from derived from that
+ of current buffer - \"*BUFFERNAME exposed*\".
+\\[allout-flatten-exposed-to-buffer] `allout-flatten-exposed-to-buffer'
+ Like above 'copy-exposed', but convert topic
+ prefixes to section.subsection... numeric
+ format.
+\\[eval-expression] \(allout-init t\) Setup Emacs session for outline mode
+ auto-activation.
Topic Encryption
@@ -1742,108 +1761,136 @@
symmetric and key-pair modes, passphrase timeout, passphrase
consistency checking, user-provided hinting for symmetric key
mode, and auto-encryption of topics pending encryption on save.
-\(Topics pending encryption are, by default, automatically
-encrypted during file saves; if you're editing the contents of
-such a topic, it is automatically decrypted for continued
-editing.) The aim is reliable topic privacy while preventing
-accidents like neglected encryption before saves, forgetting
-which passphrase was used, and other practical pitfalls.
-See `allout-toggle-current-subtree-encryption' function docstring and
-`allout-encrypt-unencrypted-on-saves' customization variable for details.
+Topics pending encryption are, by default, automatically
+encrypted during file saves. If the contents of the topic
+containing the cursor was encrypted for a save, it is
+automatically decrypted for continued editing.
+
+The aim of these measures is reliable topic privacy while
+preventing accidents like neglected encryption before saves,
+forgetting which passphrase was used, and other practical
+pitfalls.
+
+See `allout-toggle-current-subtree-encryption' function docstring
+and `allout-encrypt-unencrypted-on-saves' customization variable
+for details.
- HOT-SPOT Operation
+ HOT-SPOT Operation
Hot-spot operation provides a means for easy, single-keystroke outline
navigation and exposure control.
When the text cursor is positioned directly on the bullet character of
-a topic, regular characters (a to z) invoke the commands of the
+a topic, regular characters \(a to z\) invoke the commands of the
corresponding allout-mode keymap control chars. For example, \"f\"
would invoke the command typically bound to \"C-c<space>C-f\"
-\(\\[allout-forward-current-level] `allout-forward-current-level').
+\(\\[allout-forward-current-level] `allout-forward-current-level'\).
Thus, by positioning the cursor on a topic bullet, you can
execute the outline navigation and manipulation commands with a
-single keystroke. Regular navigation keys (eg, \\[forward-char], \\[next-line]) never get
+single keystroke. Regular navigation keys \(eg, \\[forward-char], \\[next-line]\) don't get
this special translation, so you can use them to get out of the
-hot-spot and back to normal operation.
+hot-spot and back to normal editing operation.
-Note that the command `allout-beginning-of-current-entry' \(\\[allout-beginning-of-current-entry]\)
-will move to the hot-spot when the cursor is already located at the
-beginning of the current entry, so you usually can hit \\[allout-beginning-of-current-entry]
-twice in a row to get to the hot-spot.
+In allout-mode, the normal beginning-of-line command \(\\[allout-beginning-of-line]]\) is
+replaced with one that makes it easy to get to the hot-spot. If you
+repeat it immediately it cycles \(if `allout-beginning-of-line-cycles'
+is set\) to the beginning of the item and then, if you hit it again
+immediately, to the hot-spot. Similarly, `allout-beginning-of-current-entry'
+\(\\[allout-beginning-of-current-entry]\) moves to the hot-spot when the cursor is already located
+at the beginning of the current entry.
+
+ Extending Allout
+
+Allout exposure and authoring activites all have associated
+hooks, by which independent code can cooperate with allout
+without changes to the allout core. Here are key ones:
+
+`allout-mode-hook'
+`allout-mode-deactivate-hook'
+`allout-exposure-change-hook'
+`allout-structure-added-hook'
+`allout-structure-deleted-hook'
+`allout-structure-shifted-hook'
- Terminology
+ Terminology
Topic hierarchy constituents - TOPICS and SUBTOPICS:
-TOPIC: A basic, coherent component of an Emacs outline. It can
- contain and be contained by other topics.
-CURRENT topic:
- The visible topic most immediately containing the cursor.
-DEPTH: The degree of nesting of a topic; it increases with
- containment. Also called the:
-LEVEL: The same as DEPTH.
+ITEM: A unitary outline element, including the HEADER and ENTRY text.
+TOPIC: An ITEM and any ITEMs contained within it, ie having greater DEPTH
+ and with no intervening items of lower DEPTH than the container.
+CURRENT ITEM:
+ The visible ITEM most immediately containing the cursor.
+DEPTH: The degree of nesting of an ITEM; it increases with containment.
+ The DEPTH is determined by the HEADER PREFIX. The DEPTH is also
+ called the:
+LEVEL: The same as DEPTH.
ANCESTORS:
- The topics that contain a topic.
-PARENT: A topic's immediate ancestor. It has a depth one less than
- the topic.
+ Those ITEMs whose TOPICs contain an ITEM.
+PARENT: An ITEM's immediate ANCESTOR. It has a DEPTH one less than that
+ of the ITEM.
OFFSPRING:
- The topics contained by a topic;
+ The ITEMs contained within an ITEM's TOPIC.
SUBTOPIC:
- An immediate offspring of a topic;
-CHILDREN:
- The immediate offspring of a topic.
+ An OFFSPRING of its ANCESTOR TOPICs.
+CHILD:
+ An immediate SUBTOPIC of its PARENT.
SIBLINGS:
- Topics having the same parent and depth.
+ TOPICs having the same PARENT and DEPTH.
Topic text constituents:
-HEADER: The first line of a topic, include the topic PREFIX and header
- text.
-PREFIX: The leading text of a topic which distinguishes it from normal
- text. It has a strict form, which consists of a prefix-lead
- string, padding, and a bullet. The bullet may be followed by a
+HEADER: The first line of an ITEM, include the ITEM PREFIX and HEADER
+ text.
+ENTRY: The text content of an ITEM, before any OFFSPRING, but including
+ the HEADER text and distinct from the ITEM PREFIX.
+BODY: Same as ENTRY.
+PREFIX: The leading text of an ITEM which distinguishes it from normal
+ ENTRY text. Allout recognizes the outline structure according
+ to the strict PREFIX format. It consists of a PREFIX-LEAD string,
+ PREFIX-PADDING, and a BULLET. The BULLET might be followed by a
number, indicating the ordinal number of the topic among its
- siblings, a space, and then the header text.
+ siblings, or an asterisk indicating encryption, plus an optional
+ space. After that is the ITEM HEADER text, which is not part of
+ the PREFIX.
- The relative length of the PREFIX determines the nesting depth
- of the topic.
+ The relative length of the PREFIX determines the nesting DEPTH
+ of the ITEM.
PREFIX-LEAD:
- The string at the beginning of a topic prefix, normally a `.'.
- It can be customized by changing the setting of
- `allout-header-prefix' and then reinitializing `allout-mode'.
-
- By setting the prefix-lead to the comment-string of a
- programming language, you can embed outline structuring in
- program code without interfering with the language processing
- of that code. See `allout-use-mode-specific-leader'
- docstring for more detail.
+ The string at the beginning of a HEADER PREFIX, by default a `.'.
+ It can be customized by changing the setting of
+ `allout-header-prefix' and then reinitializing `allout-mode'.
+
+ When the PREFIX-LEAD is set to the comment-string of a
+ programming language, outline structuring can be embedded in
+ program code without interfering with processing of the text
+ \(by emacs or the language processor\) as program code. This
+ setting happens automatically when allout mode is used in
+ programming-mode buffers. See `allout-use-mode-specific-leader'
+ docstring for more detail.
PREFIX-PADDING:
- Spaces or asterisks which separate the prefix-lead and the
- bullet, determining the depth of the topic.
-BULLET: A character at the end of the topic prefix, it must be one of
- the characters listed on `allout-plain-bullets-string' or
- `allout-distinctive-bullets-string'. (See the documentation
- for these variables for more details.) The default choice of
- bullet when generating topics varies in a cycle with the depth of
- the topic.
-ENTRY: The text contained in a topic before any offspring.
-BODY: Same as ENTRY.
-
+ Spaces or asterisks which separate the PREFIX-LEAD and the
+ bullet, determining the ITEM's DEPTH.
+BULLET: A character at the end of the ITEM PREFIX, it must be one of
+ the characters listed on `allout-plain-bullets-string' or
+ `allout-distinctive-bullets-string'. \(See the documentation
+ for these variables for more details.\) The default choice of
+ BULLET when generating ITEMs varies in a cycle with the DEPTH of
+ the ITEM.
EXPOSURE:
- The state of a topic which determines the on-screen visibility
- of its offspring and contained text.
+ The state of a TOPIC which determines the on-screen visibility
+ of its OFFSPRING and contained ENTRY text.
CONCEALED:
- Topics and entry text whose display is inhibited. Contiguous
- units of concealed text is represented by `...' ellipses.
+ TOPICs and ENTRY text whose EXPOSURE is inhibited. Concealed
+ text is represented by \"...\" ellipses.
- Concealed topics are effectively collapsed within an ancestor.
-CLOSED: A topic whose immediate offspring and body-text is concealed.
-OPEN: A topic that is not closed, though its offspring or body may be."
+ CONCEALED TOPICs are effectively collapsed within an ANCESTOR.
+CLOSED: A TOPIC whose immediate OFFSPRING and body-text is CONCEALED.
+OPEN: A TOPIC that is not CLOSED, though its OFFSPRING or BODY may be."
;;;_ . Code
(interactive "P")
@@ -1934,22 +1981,8 @@
extend))
;; Produce map from current version of allout-keybindings-list:
- (setq allout-mode-map
- (produce-allout-mode-map allout-keybindings-list))
- (substitute-key-definition 'beginning-of-line
- 'allout-beginning-of-line
- allout-mode-map global-map)
- (substitute-key-definition 'move-beginning-of-line
- 'allout-beginning-of-line
- allout-mode-map global-map)
- (substitute-key-definition 'end-of-line
- 'allout-end-of-line
- allout-mode-map global-map)
- (substitute-key-definition 'move-end-of-line
- 'allout-end-of-line
- allout-mode-map global-map)
+ (allout-setup-mode-map)
(produce-allout-mode-menubar-entries)
- (fset 'allout-mode-map allout-mode-map)
;; Include on minor-mode-map-alist, if not already there:
(if (not (member '(allout-mode . allout-mode-map)
@@ -2039,6 +2072,28 @@
allout-mode
) ; let*
) ; defun
+(defun allout-setup-mode-map ()
+ "Establish allout-mode bindings."
+ (setq-default allout-mode-map
+ (produce-allout-mode-map allout-keybindings-list))
+ (setq allout-mode-map
+ (produce-allout-mode-map allout-keybindings-list))
+ (substitute-key-definition 'beginning-of-line
+ 'allout-beginning-of-line
+ allout-mode-map global-map)
+ (substitute-key-definition 'move-beginning-of-line
+ 'allout-beginning-of-line
+ allout-mode-map global-map)
+ (substitute-key-definition 'end-of-line
+ 'allout-end-of-line
+ allout-mode-map global-map)
+ (substitute-key-definition 'move-end-of-line
+ 'allout-end-of-line
+ allout-mode-map global-map)
+ (fset 'allout-mode-map allout-mode-map))
+;; ensure that allout-mode-map has some setting even if allout-mode hasn't
+;; been invoked:
+(allout-setup-mode-map)
;;;_ > allout-minor-mode
(defalias 'allout-minor-mode 'allout-mode)
@@ -2887,19 +2942,31 @@
(if (interactive-p) (allout-end-of-prefix))
(and last-ascended allout-recent-depth))))
;;;_ > allout-ascend ()
-(defun allout-ascend ()
- "Ascend one level, returning t if successful, nil if not."
+(defun allout-ascend (&optional dont-move-if-unsuccessful)
+ "Ascend one level, returning resulting depth if successful, nil if not.
+
+Point is left at the beginning of the level whether or not
+successful, unless optional DONT-MOVE-IF-UNSUCCESSFUL is set, in
+which case point is returned to its original starting location."
+ (if dont-move-if-unsuccessful
+ (setq dont-move-if-unsuccessful (point)))
(prog1
(if (allout-beginning-of-level)
(let ((bolevel (point))
(bolevel-depth allout-recent-depth))
(allout-previous-heading)
- (if (< allout-recent-depth bolevel-depth)
- allout-recent-depth
- ;; some topic after file's first is at lower depth than first:
- (goto-char bolevel)
- (allout-depth)
- nil)))
+ (cond ((< allout-recent-depth bolevel-depth)
+ allout-recent-depth)
+ ((= allout-recent-depth bolevel-depth)
+ (if dont-move-if-unsuccessful
+ (goto-char dont-move-if-unsuccessful))
+ (allout-depth)
+ nil)
+ (t
+ ;; some topic after very first is lower depth than first:
+ (goto-char bolevel)
+ (allout-depth)
+ nil))))
(if (interactive-p) (allout-end-of-prefix))))
;;;_ > allout-descend-to-depth (depth)
(defun allout-descend-to-depth (depth)
@@ -4445,7 +4512,7 @@
(while more
(allout-back-to-current-heading)
; go as high as we can in each bunch:
- (while (allout-ascend))
+ (while (allout-ascend t))
(save-excursion
(allout-unprotected
(allout-rebullet-topic-grunt (- adjust-to-depth
[-- Attachment #3: ChangeLog-entry.txt --]
[-- Type: text/plain, Size: 702 bytes --]
2006-11-28 Ken Manheimer <ken.manheimer@gmail.com>
* allout.el (allout-ascend): Add an optional argument to preserve
original position of point when unsuccessful. Also, fix a
docstring error.
(allout-yank-processing): Fix depth shift of multiple-topic yanks
work again, using allout-ascend's new option.
(allout-setup-mode-map): Extracted from allout-mode to initialize
allout-mode-map. Call this function on file load, so the mode
docstring substitutions work even if allout mode has not yet been
invoked.
(allout-mode): Use new allout-setup-mode-map to track any
keybinding customizations since the map was last processed. Also,
refine the docstring so it's ship-shape for release.
[-- Attachment #4: Type: text/plain, Size: 142 bytes --]
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: allout mode patch for a few small bugs and cleanup of mode docstring
2006-11-29 20:51 allout mode patch for a few small bugs and cleanup of mode docstring Ken Manheimer
@ 2006-11-29 23:27 ` Kim F. Storm
2006-11-30 0:04 ` Ken Manheimer
0 siblings, 1 reply; 4+ messages in thread
From: Kim F. Storm @ 2006-11-29 23:27 UTC (permalink / raw)
Cc: Emacs-Devel
"Ken Manheimer" <ken.manheimer@gmail.com> writes:
> the attached patch resolves a few stray bugs and provides a much
> needed cleanup of the allout-mode docstring, which is the central
> documentation for the mode. (the bug fixes are small - more than 4/5
> of the patch is for the allout-mode docstring changes.)
I see that you changed several occurrences of ... ( ... ) ... to
.. \( ... \) ... in the doc string.
You only need to quote a ( in the rare case that it occurs in
the first column of a line, and you never need to quote a ).
Appendix D.6 of the Emacs Lisp Reference Manual says:
* If a line in a documentation string begins with an
open-parenthesis, write a backslash before the open-parenthesis,
like this:
The argument FOO can be either a number
\(a buffer position) or a string (a file name).
This prevents the open-parenthesis from being treated as the start
of a defun (*note Defuns: (emacs)Defuns.).
--
Kim F. Storm <storm@cua.dk> http://www.cua.dk
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: allout mode patch for a few small bugs and cleanup of mode docstring
2006-11-29 23:27 ` Kim F. Storm
@ 2006-11-30 0:04 ` Ken Manheimer
2006-11-30 19:48 ` Richard Stallman
0 siblings, 1 reply; 4+ messages in thread
From: Ken Manheimer @ 2006-11-30 0:04 UTC (permalink / raw)
Cc: Emacs-Devel
On 11/29/06, Kim F. Storm <storm@cua.dk> wrote:
> I see that you changed several occurrences of ... ( ... ) ... to
> .. \( ... \) ... in the doc string.
>
> You only need to quote a ( in the rare case that it occurs in
> the first column of a line, and you never need to quote a ).
>
> Appendix D.6 of the Emacs Lisp Reference Manual says:
>
> * If a line in a documentation string begins with an
> open-parenthesis, write a backslash before the open-parenthesis,
> like this:
>
> The argument FOO can be either a number
> \(a buffer position) or a string (a file name).
>
> This prevents the open-parenthesis from being treated as the start
> of a defun (*note Defuns: (emacs)Defuns.).
thanks for the tip - i've wondered about a few nuances concerning
escaping parens, and i might as well ask, while the issue is raised.
first, does it hurt to escape open parens excessively? i ask because
i deliberately tend to quote all leading opens, so i can flow
docstring paragraphs without worry about surprises. it would not be a
hardship to be more discriminating, but still wonder if there's a
drawback beyond the increased mystery (onions-in-the-varnish wise) of
unnecessary escaping.
i'm pretty haphazard about escaping the close parens, but decided to
shoot for consistency in this last edit - apparently in the wrong
direction. (i don't see any prohibition against escaping the close
parens, but i suppose it's more onions-in-the-varnish noise.) it would
be nice if there were a way to get paren matching for an escaped open
paren, and i gather there currently is no provision for that. is that
right?
just curious, mostly.
--
ken
ken.manheimer@gmail.com
http://myriadicity.net
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: allout mode patch for a few small bugs and cleanup of mode docstring
2006-11-30 0:04 ` Ken Manheimer
@ 2006-11-30 19:48 ` Richard Stallman
0 siblings, 0 replies; 4+ messages in thread
From: Richard Stallman @ 2006-11-30 19:48 UTC (permalink / raw)
Cc: emacs-devel, storm
first, does it hurt to escape open parens excessively? i ask because
i deliberately tend to quote all leading opens, so i can flow
docstring paragraphs without worry about surprises.
It looks sort of ugly, and teaches other people that all open parens
need to be escaped. Aside from that, it does no harm.
i'm pretty haphazard about escaping the close parens, but decided to
shoot for consistency in this last edit - apparently in the wrong
direction.
There is never any reason to do that, so please don't.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2006-11-30 19:48 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2006-11-29 20:51 allout mode patch for a few small bugs and cleanup of mode docstring Ken Manheimer
2006-11-29 23:27 ` Kim F. Storm
2006-11-30 0:04 ` Ken Manheimer
2006-11-30 19:48 ` Richard Stallman
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).