Re: [AUCTeX-devel] Texinfo: mark environment and mark section/node

[Vincent Belaïche]

> Regarding the question about where to put documentation, I also failed
> to find a good place for it. Perhaps we need a new "Navigation"
> subsection below "Editing"?
> 
> In the LaTeX menu the functions for marking and jumping to the start
> or end of an environment are below "Formatting and Marking", together
> with the functions for filling. But in the manual we have
> "Commenting", "Indenting" and "Filling" which can all be related to a
> marked region.  So perhaps a separate section is in order.
> 
> And in that section one could describe both the functions for LaTeX
> and Texinfo mode.
> 
> -- 
> Ralf

Hi Ralf,

Battons le fer tant qu'il est encore chaud...

Here is attached the patch to documentation, and here follows the
ChangeLog entry:

-----------------------------------------------------------------------
2011-07-14  Vincent Belaïche  <address@hidden>

        * doc/auctex.texi: Add documentation for functions
        LaTeX-mark-section, LaTeX-mark-environment, Texinfo-mark-section,
        Texinfo-mark-environment and Texinfo-mark-node.
-----------------------------------------------------------------------

The added documentation is merely a cut & paste of the docstring, with
some Texinfo-izing.

Regards,
   Vincent

*** auctex.texi Thu Jul 14 16:09:38 2011
--- auctex.texi.new     Thu Jul 14 16:08:46 2011
***************
*** 321,326 ****
--- 321,327 ----
  * Environments::                Inserting Environment Templates
  * Mathematics::                 Entering Mathematics
  * Completion::                  Completion of macros
+ * Marking::                     Marking Environment, sections, or texinfo 
nodes
  * Commenting::                  Commenting text
  * Indenting::                   Reflecting syntactic constructs with 
whitespace
  * Filling::                     Automatic and manual line breaking
***************
*** 1051,1056 ****
--- 1052,1147 ----
  automatic parsing on save, and that the basename of the address@hidden file
  does not conflict with the basename of one of @TeX{} files.
  
+ @node Marking
+ @section Marking Environment, Sections, or Texinfo nodes
+ 
+ You can set the region over the current environment with the @kbd{C-c .}
+ command, or over the current section with the @kbd{C-c *} command.
+ 
+ For Texinfo documents there is an additional command @kbd{M-C-h} to set
+ the region over the current node.
+ 
+ When the region is set, the point is moved to its beginning and the mark
+ at its end.
+ 
+ @menu
+ * MakingLaTeX:: LaTeX Commands for marking Environment and Sections
+ * MakingTexinfo:: Texinfo Commands for marking Environment, Sections, and 
Nodes
+ @end menu
+ 
+ @node MakingLaTeX
+ @subsection LaTeX Commands for marking Environment and Sections
+ 
+ @deffn Command LaTeX-mark-section &optional @var{no-subsections}
+ @kindex C-c *
+ (@kbd{C-c *}) Mark current section, with inclusion of any containing node.
+ 
+ The current section is detected as starting by any of the structuring
+ commands matched by regexp in variable @code{outline-regexp} which in
+ turn is a regexp matching any element of variable
+ @code{texinfo-section-list}.
+ 
+ If optional argument @var{no-subsection} is set to any integer or is a
+ non nil empty argument (i.e. @kbd{C-u C-c *}), then mark the current
+ section with exclusion of any subsections.
+ 
+ Otherwise, any included subsections are also marked along with current
+ section.
+ 
+ Note that when current section is starting immediatley after a node
+ commande, then the node command is also marked as part as the section.
+ @end deffn
+ 
+ @deffn Command LaTeX-mark-environment &optional @var{count}
+ @kindex C-c .
+ (@kbd{C-c .}) Set mark to end of current environment and point to the
+ matching begin.  If prefix argument @var{count} is given, mark the
+ respective number of enclosing environments.  The command will not work
+ properly if there are unbalanced begin-end pairs in comments and
+ verbatim environments.
+ @end deffn
+ 
+ @node MakingTexinfo
+ @subsection Texinfo Commands for marking Environment and Sections
+ 
+ @deffn Command Texinfo-mark-section &optional @var{no-subsection}
+ @kindex C-c *
+ (@kbd{C-c *}) Mark current section, with inclusion of any containing
+ node.
+ 
+ The current section is detected as starting by any of the structuring
+ commands matched by regexp in variable @code{outline-regexp} which in
+ turn is a regexp matching any element of variable
+ @code{texinfo-section-list}.
+ 
+ If optional argument @var{no-subsection} is set to any integer or is a
+ non @code{nil} empty argument (i.e. @kbd{C-u C-c *}), then mark the
+ current section with exclusion of any subsections.
+ 
+ Otherwise, any included subsections are also marked along with
+ current section.
+ 
+ Note that when current section is starting immediatley after a
+ node commande, then the node command is also marked as part as
+ the section.
+ @end deffn
+ 
+ @deffn Command Texinfo-mark-environment &optional @var{count}
+ @kindex C-c .
+ (@kbd{C-c .}) Set mark to end of current environment and point to the matching
+ beginning.  If prefix argument @var{count} is given, mark the respective
+ number of enclosing environments.  The command will not work properly if
+ there are unbalanced begin-end pairs in comments and verbatim
+ environments.
+ @end deffn
+ 
+ @deffn Command Texinfo-mark-node
+ @kindex M-C-h
+ (@kbd{M-C-h}) Mark the current node.  This is the node in which the
+ point is.  It is starting at previous beginning of keyword @code{@@node}
+ and ending at next beginning of keyword @code{@@node} or @code{@@bye}.
+ @end deffn
+ 
  @node Commenting
  @section Commenting