# Macro for inserting subsection using AucTeX?

C-c C-s produces a dialog hook which says Level: (default section). The manual says that the code for subsection is supposed to be 3. But if one types 3 RET, after completing the remaining dialogs hooks for the section name and label, one gets

\3{title}
\label{label}


which obviously is not the expected or desired behavior.

Question: Is there a way to fix this behavior so that it behaves more like I expected?

Writing out the entire word subsection would seem to nullify the entire point of AucTeX macros. Do people commonly need to modify AucTeX's defaults substantially, like is done here? Any suggestions for how to change this, get use to this, or try a different solution for inserting sections, subsections, etc. into a document altogether would be appreciated.

User Option: LaTeX-section-hook
List of hooks to run when a new section is inserted.

The following variables are set before the hooks are run

level
Numeric section level, default set by prefix arg to LaTeX-section.

name
Name of the sectioning command, derived from level.


To me it seems like when the hook/dialog/prompt (I am new to emacs and do not know the correct terminology) asks for the Level which should be a numeric, and from which AucTeX should deduce Name, instead it is asking for Name. Is this correct, and perhaps my settings are interfering with AucTeX somehow? (I am using the version of AucTeX coming with an AquaMacs installation, which is presumably heavily pre-configured.)

EDIT: The manual online contradicts the information given about the LaTeX-section hooks inside of emacs, specifically that says that:

LaTeX-section-heading Hook to prompt for LaTeX section name. Hide Insert this hook into ‘LaTeX-section-hook’ to allow the user to change the name of the sectioning command inserted with ‘M-x LaTeX-section’.

In other words, this hook is intentionally designed to only allow the user to specify the name, not the level. This in direct contrast to the online AucTeX documentation which falsely claims that this hook allows one to change the name and the level.

Again, this does not make sense to me -- the level uniquely determines the name, does it not? So why allow the user to specify an incorrect section command, like \notasection{}, which also takes longer to type than the level number anyway, and additionally not allow the level of the section to specified? It makes no sense to me.

It also says that

The following variables are set before the hooks are run: level, name, ...

i.e. that it sets the value of the level before any of the hooks are run. And none of the hooks allow one to change the value of the level.

The documentation says something about the level being a prefix argument. As far as I can tell, this means that it can only be changed in an emacs lisp configuration file, but can not be changed in real time when using emacs, which does not make sense to me. This is based off of the emacs documentation for "Prefix Command Arguments" here, which I don't actually understand. So I guess this question comes down to how to specify a prefix command argument in real time while using emacs.

• Probably better to ask on the auctex mailing list. Manuals are often the last thing developers think about. Looking in the code (I use 11.90), that numbered list is mentions for LaTeX-section, but I get the same as you. So ask the developers, gnu.org/software/auctex/mailing-lists.html – daleif Feb 27 '18 at 14:06
• @daleif I just figured it out -- see the answer below. The documentation is correct, it just doesn't make sense to a novice like me who doesn't understand what prefix arguments are or how to specify them. – Chill2Macht Feb 27 '18 at 14:26
• I've always just used C-c C-s subsec TAB, easier to remember – daleif Feb 27 '18 at 14:27
• @daleif If that works for you, then of course feel free to use it. – Chill2Macht Feb 27 '18 at 18:00
• It just think that it is more natural, not many users remember these numbers – daleif Feb 27 '18 at 18:06

In general, Emacs' user interface is somewhat Minibuffer-tabcompletion-centric. If you don't like the current implementation of LaTeX-section, you can add the following lines to your init file:

(defun My-LaTeX-section ()
(interactive)
(let ((LaTeX-section-hook '(LaTeX-section-title
LaTeX-section-section
LaTeX-section-label)))
(LaTeX-section

(lambda ()
(local-set-key (kbd "C-c s") #'My-LaTeX-section))
t)


It defines a new function My-LaTeX-section which locally rebinds the value of LaTeX-section-hook before it asks you only for a number which is passed to the original implementation of LaTeX-section. Next, it maps the key binding C-c s to your function in LaTeX mode.

Now, you can type C-c s 2 RET and will go directly to the query for title and label of a section.

• This is impressive, thank you! This will probably take me some time to process/analyze, but I will let you know if/when I have any follow-up questions. – Chill2Macht Feb 28 '18 at 20:44

After C-c C-s type su and then TAB. Emacs will autocomplete as far as possible.

• This doesn't help much though because that doesn't allow one to distinguish between subsection, subsubsection, and subparagraph. The AucTeX documentation says that the command is supposed to query for the level using a numeric arg, but the LaTeX-section-heading hook is the only one available which modifies level, but doesn't query the user for the level. (Which doesn't make sense, because the level uniquely determines the name of the command, and the level is much easier and quicker to type than the entire name of the command, e.g. especially in the case of subsubsection.) – Chill2Macht Feb 27 '18 at 13:43

Here's how to do it: first type C-u and then the level (a number between 0 through 6, see here) and then type C-c C-s and fill in the prompts as normal.

So (after disabling LaTeX-section-heading under the settings for LaTeX-section-hook; see below), if one types C-u 2 C-c C-s RET title RET label one gets:

\section{title}
\label{label}


and if one types C-u 4 C-c C-s anothertitle RET anotherlabel one gets:

\subsubsection{anothertitle}
\label{anotherlabel}


To me this is still annoying, because I would prefer to be able to do C-c C-s 4 RET anothertitle RET anotherlabel but this is unfortunately the way the LaTeX-section command is currently written. If you know how to change these files and write in emacs lisp, and are therefore able to rewrite this function, then you probably wouldn't have had the same question that I had. In any case, it (1) explains what the AUCTeX documentation was talking about, and (2) is a lot easier than typing C-c C-s subsubsection RET anothertitle RET anotherlabel, (3) doesn't require typing out the whole section level name, which is supposed to be the point of these macros.

Behind the scenes, C-u is a shortcut ('key binding') for the command universal-argument (see here) which allows you to specify the value of the 'prefix argument' for the following command, which in this case is LaTeX-section, whose shortcut is C-c C-s. So C-u 4 C-c C-s runs the LaTeX-section command with the prefix argument 4, and C-u 2 C-c C-s runs the LaTeX-section command with the prefix argument 2 (which is explained here in the AUCTeX documentation).

Note: You might want to change the value of LaTeX-section-hook first so that it doesn't prompt you for the 'name' (which is useless). Do this by first typing C-h v (not C-h C-v), and then type LaTeX-section-hook into the prompt for the variable name which should have been created by typing C-h v. This should open up a window which allows you to "customize the value of this variable", do that, then uncheck the box for LaTeX-section-heading. Now C-c C-s won't give the dialog box which asks for "the level", but which actually only asks for the 'name' (it would help if the terminology were consistent within the AucTeX commands and documentation version themselves, but it isn't). This is good, because if that prompt were still there, you could type C-c C-s notasection ... ... and get as output \notasection{...} \label{...}which is totally useless.

C-h leads to general help prompts, so typing the value v after C-h leads to the prompt for help and information about emacs variables, which allows their values to be changed.

• +1 Note also that (a) C-u C-c C-s takes you down one level (b) you can write the numeric argument via ESC: ESC 3 C-c C-s etc. – Andrew Swann Feb 28 '18 at 20:17
• @AndrewSwann I'll have to try both of these out later -- thank you for this advice! – Chill2Macht Feb 28 '18 at 20:44