5

A guy had a problem personalizing his ToC, and you helped him suggesting to use this lines:

\newcommand{\mychapter}[2]{
  \setcounter{chapter}{#1}
  \setcounter{section}{0}
  \chapter*{#2}
  \addcontentsline{toc}{chapter}{#2}
}

Could you explain me

  1. Why do you write [2] next to \mychapter?

  2. Why do you use the hashtag for numerating?

  3. What is the function of \addcontentline?

I hope no to bother you too much, I am just a new young user trying to understand the software.

Werner
  • 603,163
Emanuele
  • 51
  • Hi and welcome, why does an unnumbered chapter get a (fixed) number? Where have you taken this piece of code from? – Johannes_B Jan 04 '15 at 21:25

2 Answers2

5

  1. Why do you write "[2]" next to \mychapter?

    Taken from source2e.pdf - the source documentation for LaTeX2e (section 11.3 Command definitions, p 23):

    \newcommand*{<\FOO>}[<i>]{<TEXT>}

    User command to define \FOO to be a macro with i arguments (i = 0 if missing) having the definition <TEXT>. Produces an error if \FOO already defined. Normally the command is defined to be \long (i.e. it may take multiple paragraphs in its argument). In the star-form, the command is not defined as \long and a blank line in any argument to the command would generate an error.

    So, the general use of \newcommand (and also for \renewcommand and \providecommand) is to include the number of arguments within square brackets. Using your definition, \mychapter will take two (2) arguments.

    Also see What's the difference between \newcommand and \newcommand*? (beyond this scope and perhaps more technical, but still relevant, see What is the difference between \def and \newcommand?).

  2. Why do you use the hashtag for numerating?

    Taken from The TeXBook (chapter 20 Definitions (also called Macros), p 198):

    As soon as you get the hang of simple macros [...], you will probably begin to think, "Boy, wouldn't it be nice if I could have a macro in which some of the text in the expansion is changeable? I'd like to be able to stick different things into the middle of that text." Well, TeX has good news for you: Control sequences can be defined in terms of parameters, and you can supply arguments that will be substituted for the parameters.

    ... The symbol #1 stands for the first parameter to the macro, ... There can be as many as nine parameters, #1 to #9, [...]

    So you would reference the arguments within \mychapter using #1 and/or #2 since the macro takes two arguments. #1 represents the first argument and #2 represents the second argument.

    Relevant, if needed, see How to define a command that takes more than 9 arguments.

  3. What is the function of \addcontentsline?

    Taken from source2e.pdf (section 61.3 Table of Contents etc., p 287-):

    The \addcontentsline{<table>}{<type>}{<entry>} command allows the user to add his/her own entry to a Table of Contents, etc. The command adds the entry \contentsline{<type>}{<entry>}{<page>} to the .<table> file.

    This macro is implemented as an application of \addtocontents.

    So \addcontentsline{toc}{chapter}{#2} inserts an entry \contentsline{chapter}{#2}{<page>} into the .toc file, where #2 is the second argument of \mychapter. The <page> entry is determined when the page is actually shipped out, as that's the nature of TeX's asynchronous shipout routine and page references.

    You'll note that different <type>s have different formatting in the ToC. Chapters look different from sections, which are (or at least could be) different from subsections, etc. The differences require one to supply a <type> with the \addcontentsline macro, as is done in \mychapter.

Community
  • 1
Werner
  • 603,163
4

why do you write "[2]" next to \mychapter

Because the macro is being defined as taking 2 arguments. The arguments are evidently (a) the intended chapter number and (b) the title of the chapter.

Why do you use the hashtag for numerating

Because that's LaTeX/TeX syntax for referring to the arguments of a macro: #1 is the first argument, #2 is the second, etc.

What is the function of \addcontentline

For some reason, the creator of the \mychapter macro (I swear, it wasn't me!) chose to use \chapter* rather than \chapter to typeset the title of the chapter. In the main LaTeX document classes, \chapter* (a) creates unnumbered chapters and (b) does not automatically create an entry in the Table of Contents. The \addcontentsline macro is a manual way of inserting that information to the file that creates the ToC information.

Mico
  • 506,678