allout mode patch for a few small bugs and cleanup of mode docstring

[Ken Manheimer]

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
address@hidden
http://myriadicity.net

2006-11-28  Ken Manheimer  <address@hidden>

        * 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.

allout-patch.txt
Description: Text document

ChangeLog-entry.txt
Description: Text document