Acronyms and LaTeX

Computer geeks like acronyms, especially three-letter acronyms (TLAs). To give you an impression: I'm working in the area of MDD. Actually, OMG calls it MDA, Stuart Kent MDE, and others MDSD. In short, models, such as UML or EMF models, are transformed into other models or code by M2M- or M2T-transformations, such as QVT or ATL. Writing a thesis in that area is really hard, since you have to keep an eye on all that TLAs. So I've looked for a LaTeX package doing the job for me, and what I found is a package called acronym by Tobias Oetiker. I really like the simplicity of this package, this is why I decided to use that instead of other alternative solutions.

Install acronym

Surprisingly, it was already installed with my tex installation (gwTeX), but it requires a packages called suffix, which was not. The later is contained in a bundle called bigfoot. Here are the CTAN locations of acronym and bigfoot:

• http://tug.ctan.org/tex-archive/macros/latex/contrib/acronym/
• http://tug.ctan.org/tex-archive/macros/latex/contrib/bigfoot/

In order to install a package from the files available at CTAN, you usually have to

• download the zip or all the files from CTAN
• unzip them (or put them into a folder) and put the folder somewhere tex can find it, e.g. into $HOMETEXMF (i.e. ~/library/texmf/tex)
• run the installer via latex *.ins, in that case latex bigfoot.tex

Now you are ready to use acronym. It is quite simple: simply include the package via

\usepackage{acronym}

Instead of simply writing the acronym in your text, you now have to write \ac{..} (or, in case of a plural, \acp{..}). You have to add a new environment with a list of all the acronyms and their long form with

\begin{acronym}
\arcro{..}{...}
\end{acronym}

The first time an acronym is used, \ac prints the long form with the acronym in brakets. There are also some other commands available, see the acronym documentation for details.

Add list of acronyms to table of contents

Unfortunately, there is no command available for adding an entry to the table of contents. I have written my own command for that, which creates an entry similar to the list of figures. You have to add the following code somewhere in your preamble:

\@ifundefined{listofacronymsname}{\newcommand{\listofacronymsname}{Acronyms}}{}
\@ifundefined{chapter}{%
\newcommand{\listofacronyms}{%
\section*{\listofacronymsname}%
\addcontentsline{toc}{section}{\listofacronymsname}%
\label{sec:acronyms}%
\markboth{\listofacronymsname}{\listofacronymsname}%
}}{%
\newcommand{\listofacronyms}{%
\chapter*{\listofacronymsname}%
\addcontentsline{toc}{chapter}{\listofacronymsname}%
\label{sec:acronyms}%
\markboth{\listofacronymsname}{\listofacronymsname}%
}}

It defines two commands:

\listofacronymsname

defines the name of the heading used for the list of acronyms. It is "Acronyms" by default, but you can change that with \renewcommand, as demonstrated below.

\listofacronyms

creates a heading and a section or chapter definition (depending on the document class), which is also added to the table of contents. A label "sec:acronyms" is added as well.

(Update 2012-05-21: \markboth adjusts the header accordingly, see mrunix thread)

Put it all together

Let's put it all together. Firstly, we use the package and define the \listofacronyms command:

\usepackage[printonlyused,smaller]{acronym}     % acronyms ac
\@ifundefined{listofacronymsname}{\newcommand{\listofacronymsname}{Acronyms}}{}
...

I have added some parameters to only list the used acronyms and use a slightly smaller font. Secondly, we create a new file "acronyms.text" with a list of the acronyms, which makes it easier to maintain. This is how my file looks like:

\renewcommand{\listofacronymsname}{Abkürzungsverzeichnis} % german title
\listofacronyms

% \acro{acronym}[shortname]{fullname}
% inside fullname: \acroextra{} -- not in text, only in description list
\begin{acronym}
\acro{EMF}{Eclipse Modeling Framework \cite{EMF}}
\acro{GEF}{Graphical Editing Framework \cite{GEF}}
\acro{MDD}{Model Driven Development}
\acro{MDA}{Model Driven Architecture}
\acro{UML}{Unified Modeling Language}
...
\end{acronym}

The acronyms are not sorted automatically, I use SubEthaEdit for sorting the acronyms from time to time, but I guess there are several editors which can do that. This file has to be included in your main latex source document, e.g.,

\begin{appendix}
\input{acronyms}
\end{appendix}

Last but not least, we have to use the acronym commands in the text, just like that:

I'm working in the area of \ac{MDD}. Actually, \ac{OMG} calls it \ac{MDA}, Stuart Kent \ac{MDE}. In short, models, such as \ac{UML} or \ac{EMF} models, ...

You do not have to look for the first usage of an acronym anymore, acronym is doing that for you. If you forget to define an acronym, you will see that in the generated output as acronym creates a bold placeholder in that case. If you do not want to printed the list of acronyms, you can use acronym just as described before, you only have to add a package option nolist (i.e. \usepackage[nolist]{acronym}). This is especially useful in combination with the option footnote, as in that case the description of the acronym is printed as a footnote and not in the text (and one can find the definitions by scanning the footnotes, which is ok for shorter texts). Thank you very much, Tobias Oetiker, for writing that package!

Computer geeks like acronyms, especially three-letter acronyms (TLAs). To give you an impression: I'm working in the area of MDD. Actually, OMG calls it MDA, Stuart Kent MDE, and others MDSD. In short, models, such as UML or EMF models, are transformed into other models or code by M2M- or M2T-transformations, such as QVT or ATL. Writing a thesis in that area is really hard, since you have to keep an eye on all that TLAs. So I've looked for a LaTeX package doing the job for me, and what I found is a package called acronym by Tobias Oetiker. I really like the simplicity of this package, this is why I decided to use that instead of other alternative solutions.

Install acronym

Surprisingly, it was already installed with my tex installation (gwTeX), but it requires a packages called suffix, which was not. The later is contained in a bundle called bigfoot. Here are the CTAN locations of acronym and bigfoot:

• http://tug.ctan.org/tex-archive/macros/latex/contrib/acronym/
• http://tug.ctan.org/tex-archive/macros/latex/contrib/bigfoot/

In order to install a package from the files available at CTAN, you usually have to

• download the zip or all the files from CTAN
• unzip them (or put them into a folder) and put the folder somewhere tex can find it, e.g. into $HOMETEXMF (i.e. ~/library/texmf/tex)
• run the installer via latex *.ins, in that case latex bigfoot.tex

Now you are ready to use acronym. It is quite simple: simply include the package via

\usepackage{acronym}

Instead of simply writing the acronym in your text, you now have to write \ac{..} (or, in case of a plural, \acp{..}). You have to add a new environment with a list of all the acronyms and their long form with

\begin{acronym}
\arcro{..}{...}
\end{acronym}

The first time an acronym is used, \ac prints the long form with the acronym in brakets. There are also some other commands available, see the acronym documentation for details.

Add list of acronyms to table of contents

Unfortunately, there is no command available for adding an entry to the table of contents. I have written my own command for that, which creates an entry similar to the list of figures. You have to add the following code somewhere in your preamble:

\@ifundefined{listofacronymsname}{\newcommand{\listofacronymsname}{Acronyms}}{}
\@ifundefined{chapter}{%
\newcommand{\listofacronyms}{%
\section*{\listofacronymsname}%
\addcontentsline{toc}{section}{\listofacronymsname}%
\label{sec:acronyms}%
\markboth{\listofacronymsname}{\listofacronymsname}%
}}{%
\newcommand{\listofacronyms}{%
\chapter*{\listofacronymsname}%
\addcontentsline{toc}{chapter}{\listofacronymsname}%
\label{sec:acronyms}%
\markboth{\listofacronymsname}{\listofacronymsname}%
}}

It defines two commands:

\listofacronymsname

defines the name of the heading used for the list of acronyms. It is "Acronyms" by default, but you can change that with \renewcommand, as demonstrated below.

\listofacronyms

creates a heading and a section or chapter definition (depending on the document class), which is also added to the table of contents. A label "sec:acronyms" is added as well.

(Update 2012-05-21: \markboth adjusts the header accordingly, see mrunix thread)

Put it all together

Let's put it all together. Firstly, we use the package and define the \listofacronyms command:

\usepackage[printonlyused,smaller]{acronym}     % acronyms ac
\@ifundefined{listofacronymsname}{\newcommand{\listofacronymsname}{Acronyms}}{}
...

I have added some parameters to only list the used acronyms and use a slightly smaller font. Secondly, we create a new file "acronyms.text" with a list of the acronyms, which makes it easier to maintain. This is how my file looks like:

\renewcommand{\listofacronymsname}{Abkürzungsverzeichnis} % german title
\listofacronyms

% \acro{acronym}[shortname]{fullname}
% inside fullname: \acroextra{} -- not in text, only in description list
\begin{acronym}
\acro{EMF}{Eclipse Modeling Framework \cite{EMF}}
\acro{GEF}{Graphical Editing Framework \cite{GEF}}
\acro{MDD}{Model Driven Development}
\acro{MDA}{Model Driven Architecture}
\acro{UML}{Unified Modeling Language}
...
\end{acronym}

The acronyms are not sorted automatically, I use SubEthaEdit for sorting the acronyms from time to time, but I guess there are several editors which can do that. This file has to be included in your main latex source document, e.g.,

\begin{appendix}
\input{acronyms}
\end{appendix}

Last but not least, we have to use the acronym commands in the text, just like that:

I'm working in the area of \ac{MDD}. Actually, \ac{OMG} calls it \ac{MDA}, Stuart Kent \ac{MDE}. In short, models, such as \ac{UML} or \ac{EMF} models, ...

You do not have to look for the first usage of an acronym anymore, acronym is doing that for you. If you forget to define an acronym, you will see that in the generated output as acronym creates a bold placeholder in that case. If you do not want to printed the list of acronyms, you can use acronym just as described before, you only have to add a package option nolist (i.e. \usepackage[nolist]{acronym}). This is especially useful in combination with the option footnote, as in that case the description of the acronym is printed as a footnote and not in the text (and one can find the definitions by scanning the footnotes, which is ok for shorter texts). Thank you very much, Tobias Oetiker, for writing that package!

Acronyms and LaTeX

OmniGraffle Stencils

My favorite application for creating nice drawing is OmniGraffle. At Graffletopia you can find lots of user created stencils, that is templates for using in your own drawing. The latest version of OmniGraffle let you search a stencil directly at Graffletopia, so if you think you need something like UML notation elements, just enter UML in OmniGraffel's stencil window and you will find several stencils at Graffletopia. I have created some stencils as well, and you can download them from Graffletopia. You can either search for them from within OmniGraffle, or you can download and install them manually. Here is a list of my stencils:

• UML 2.1 Collection: A collection of notation elements for creating UML 2 class, activity, use case, sequence, or component diagrams. It's a rather large stencil, but it contains most UML 2.1 elements
• Feature Diagrams: Feature Diagram stencil, notation based on the book "Generative Programming" by K. Czarnecki and U.W. Eisenecker. (Updated today and fixed some problems)
• Post-it Notes: A collection of six colored post-it notes with nice shadow, slightly bended.

Have fun!

My favorite application for creating nice drawing is OmniGraffle. At Graffletopia you can find lots of user created stencils, that is templates for using in your own drawing. The latest version of OmniGraffle let you search a stencil directly at Graffletopia, so if you think you need something like UML notation elements, just enter UML in OmniGraffel's stencil window and you will find several stencils at Graffletopia. I have created some stencils as well, and you can download them from Graffletopia. You can either search for them from within OmniGraffle, or you can download and install them manually. Here is a list of my stencils:

• UML 2.1 Collection: A collection of notation elements for creating UML 2 class, activity, use case, sequence, or component diagrams. It's a rather large stencil, but it contains most UML 2.1 elements
• Feature Diagrams: Feature Diagram stencil, notation based on the book "Generative Programming" by K. Czarnecki and U.W. Eisenecker. (Updated today and fixed some problems)
• Post-it Notes: A collection of six colored post-it notes with nice shadow, slightly bended.

Have fun!

OmniGraffle Stencils

Increase/Decrease Section Level with TeXShop Macros

TeXShop is a really nice editor, especially since new commands can be added using macros. These macros can contain AppleScript, which makes them very flexible and powerful. I like formating my headings in order to easily see sections, subsections etc. For that reason, I have added some macros creating sections etc. like this: Macro "section":

% ==============================================================================
\section{#SEL##INS#}
\label{sec:#SEL#}
% ==============================================================================

My latex code then looks like that:

% ******************************************************************************
\chapter{Chapter}
\label{chapter:Chapter}
% ******************************************************************************

% ==============================================================================
\section{Section}
\label{sec:Section}
% ==============================================================================

% ------------------------------------------------------------------------------
\subsection{SubSection}
\label{sec:SubSection}
% ------------------------------------------------------------------------------

% ..............................................................................
\subsubsection{SubSubSection}
\label{sec:SubSubSection}
% ..............................................................................

\paragraph{Paragraph}

This works pretty well. But it becomes very painful to change a section to a subsection, because I do not only want to change "section" to "subsection", but the comment lines as well. So I added two macros including AppleScript in order to decrease or increase the level of a section. I assume other people might find these macros useful, so I publish them here. They are written very quick and dirty, so you may have to adapt them to suit your preferences: Macro: "Decrease Section Level":

--Applescript direct

-- Decrease Section Level
--Select Section Block including Comments to decrease section level, i.e. section become subsection, chapter becomes section and so on

-- (C) 2009 Jens von Pilgrim

--THE SCRIPT:

property texapp : "TeXShop"
tell application texapp
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set section to the content of the selection of the front document
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to set section to (the selection of the text of the front document)
 end if
 
 set new_section to ""
 repeat with ii from 1 to the count of the paragraphs of section
  
  set this_line to paragraph ii of section
  set new_line to this_line 
  set add to "true"

  -- replace commands
  if this_line contains "\\chapter" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\chapter/\\\\section/'"
  end if
  if this_line contains "\\section" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\section/\\\\subsection/'"
  end if
  if this_line contains "\\subsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsection/\\\\subsubsection/'"
  end if
  if this_line contains "\\subsubsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsubsection/\\\\paragraph/'"
  end if

  -- replace the comments
  if this_line contains "% ******************************************************************************" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\*/=/g'"
  end if
  if this_line contains "% ==============================================================================" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/=/-/g'"
  end if
  if this_line contains "% ------------------------------------------------------------------------------" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/-/\\./g'"
  end if
  if this_line contains "% .............................................................................." then
   set add to "false"
  end if

  if add="true" then
   if new_section = "" then
    set new_section to new_line
   else
    set new_section to new_section & return & new_line
   end if
  end if  
  
 end repeat
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set the selection of the front document to new_section
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to insert new_section in the text of the front document
 end if
end tell

Macro: "Increase Section Level":

--Applescript direct

-- Increase Section Level
--Select Section Block including Comments to decrease section level, i.e. section become subsection, chapter becomes section and so on

-- (C) 2009 Jens von Pilgrim
--THE SCRIPT:

property texapp : "TeXShop"
tell application texapp
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set section to the content of the selection of the front document
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to set section to (the selection of the text of the front document)
 end if
 
 set new_section to ""
 repeat with ii from 1 to the count of the paragraphs of section
  
  set this_line to paragraph ii of section
  set new_line to this_line 
  set add to "true"

  -- replace commands
  if this_line contains "\\section" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\section/\\\\chapter/'"
  end if
  if this_line contains "\\subsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsection/\\\\section/'"
  end if
  if this_line contains "\\subsubsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsubsection/\\\\subsection/'"
  end if
  if this_line contains "\\paragraph" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\paragraph/\\\\subsubsection/'"
   set new_line to "% .............................................................................." & return & new_line & return & "% .............................................................................."
  end if

  -- replace the comments
  if this_line contains "% ==============================================================================" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/=/\\*/g'"
  end if
  if this_line contains "% ------------------------------------------------------------------------------" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/-/=/g'"
  end if
  if this_line contains "% .............................................................................." then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\./-/g'"

  end if

  if add="true" then
   if new_section = "" then
    set new_section to new_line
   else
    set new_section to new_section & return & new_line
   end if
  end if  
  
 end repeat
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set the selection of the front document to new_section
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to insert new_section in the text of the front document
 end if
 
end tell

These two macros increase or decrease the level of a section. You have to simply select a section (or several sections), and the levels of all chapters, sections, and paragraphs are increased or decreased respectively. Besides the commands, the comments are reformatted as well. When increasing the levels, the following modifications are made:

1. section -> chapter
2. subsection -> section
3. subsubsection -> subsection
4. paragraph -> subsubsection

When decreasing the levels, the following modifications are made:

1. chapter -> section
2. section -> subsection
3. subsection -> subsubsection
4. subsubsection -> paragraph

Note that chapters are not increased any further, and paragraphs are not decreased.

TeXShop is a really nice editor, especially since new commands can be added using macros. These macros can contain AppleScript, which makes them very flexible and powerful. I like formating my headings in order to easily see sections, subsections etc. For that reason, I have added some macros creating sections etc. like this: Macro "section":

% ==============================================================================
\section{#SEL##INS#}
\label{sec:#SEL#}
% ==============================================================================

My latex code then looks like that:

% ******************************************************************************
\chapter{Chapter}
\label{chapter:Chapter}
% ******************************************************************************

% ==============================================================================
\section{Section}
\label{sec:Section}
% ==============================================================================

% ------------------------------------------------------------------------------
\subsection{SubSection}
\label{sec:SubSection}
% ------------------------------------------------------------------------------

% ..............................................................................
\subsubsection{SubSubSection}
\label{sec:SubSubSection}
% ..............................................................................

\paragraph{Paragraph}

This works pretty well. But it becomes very painful to change a section to a subsection, because I do not only want to change "section" to "subsection", but the comment lines as well. So I added two macros including AppleScript in order to decrease or increase the level of a section. I assume other people might find these macros useful, so I publish them here. They are written very quick and dirty, so you may have to adapt them to suit your preferences: Macro: "Decrease Section Level":

--Applescript direct

-- Decrease Section Level
--Select Section Block including Comments to decrease section level, i.e. section become subsection, chapter becomes section and so on

-- (C) 2009 Jens von Pilgrim

--THE SCRIPT:

property texapp : "TeXShop"
tell application texapp
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set section to the content of the selection of the front document
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to set section to (the selection of the text of the front document)
 end if
 
 set new_section to ""
 repeat with ii from 1 to the count of the paragraphs of section
  
  set this_line to paragraph ii of section
  set new_line to this_line 
  set add to "true"

  -- replace commands
  if this_line contains "\\chapter" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\chapter/\\\\section/'"
  end if
  if this_line contains "\\section" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\section/\\\\subsection/'"
  end if
  if this_line contains "\\subsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsection/\\\\subsubsection/'"
  end if
  if this_line contains "\\subsubsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsubsection/\\\\paragraph/'"
  end if

  -- replace the comments
  if this_line contains "% ******************************************************************************" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\*/=/g'"
  end if
  if this_line contains "% ==============================================================================" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/=/-/g'"
  end if
  if this_line contains "% ------------------------------------------------------------------------------" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/-/\\./g'"
  end if
  if this_line contains "% .............................................................................." then
   set add to "false"
  end if

  if add="true" then
   if new_section = "" then
    set new_section to new_line
   else
    set new_section to new_section & return & new_line
   end if
  end if  
  
 end repeat
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set the selection of the front document to new_section
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to insert new_section in the text of the front document
 end if
end tell

Macro: "Increase Section Level":

--Applescript direct

-- Increase Section Level
--Select Section Block including Comments to decrease section level, i.e. section become subsection, chapter becomes section and so on

-- (C) 2009 Jens von Pilgrim
--THE SCRIPT:

property texapp : "TeXShop"
tell application texapp
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set section to the content of the selection of the front document
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to set section to (the selection of the text of the front document)
 end if
 
 set new_section to ""
 repeat with ii from 1 to the count of the paragraphs of section
  
  set this_line to paragraph ii of section
  set new_line to this_line 
  set add to "true"

  -- replace commands
  if this_line contains "\\section" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\section/\\\\chapter/'"
  end if
  if this_line contains "\\subsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsection/\\\\section/'"
  end if
  if this_line contains "\\subsubsection" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\subsubsection/\\\\subsection/'"
  end if
  if this_line contains "\\paragraph" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\\\paragraph/\\\\subsubsection/'"
   set new_line to "% .............................................................................." & return & new_line & return & "% .............................................................................."
  end if

  -- replace the comments
  if this_line contains "% ==============================================================================" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/=/\\*/g'"
  end if
  if this_line contains "% ------------------------------------------------------------------------------" then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/-/=/g'"
  end if
  if this_line contains "% .............................................................................." then
   set new_line to do shell script ¬
    "echo " & the quoted form of this_line & ¬
    " | sed 's/\\./-/g'"

  end if

  if add="true" then
   if new_section = "" then
    set new_section to new_line
   else
    set new_section to new_section & return & new_line
   end if
  end if  
  
 end repeat
 
 if texapp = "TeXShop" then
  tell application "TeXShop" to set the selection of the front document to new_section
 else if texapp = "iTeXMac" then
  --tell application "iTeXMac" to insert new_section in the text of the front document
 end if
 
end tell

These two macros increase or decrease the level of a section. You have to simply select a section (or several sections), and the levels of all chapters, sections, and paragraphs are increased or decreased respectively. Besides the commands, the comments are reformatted as well. When increasing the levels, the following modifications are made:

1. section -> chapter
2. subsection -> section
3. subsubsection -> subsection
4. paragraph -> subsubsection

When decreasing the levels, the following modifications are made:

1. chapter -> section
2. section -> subsection
3. subsection -> subsubsection
4. subsubsection -> paragraph

Note that chapters are not increased any further, and paragraphs are not decreased.

Increase/Decrease Section Level with TeXShop Macros

How to write very long documents with LaTeX

I eventually started writing my thesis--with LaTeX. Since it will become a rather long document (approx. 200 pages) I decided to split the document into its chapters (and maybe into more parts). Splitting a document is very easy with latex and it typically looks like that:

\documentclass{someClass}
... some definitions, use packages etc ...
\begin{document}
...
\maketitle
...
\input{abstract}
\input{introduction}
...
\input{relatedwork}
\input{conclusion}
...
\end{document}

This works pretty well, and I always use this pattern for writing smaller papers. Unfortunately I found two severe problems:

1. The latex compiler is unaware of folders.
2. I cannot compile the parts separately, which leads to new problems

Chapterfolder

The first problem is further described and solved by the latex package "chapterfolder". Instead of simply including a chapter, it is included and the current folder is changed accordingly. The main file will now look like this:

...
\begin{document}
...
\maketitle
...
\cfchapter{Introduction}{chapters/introduction}{introduction.tex}
...
\cfchapter{Conclusion}{chapters/conclusion}{conclusion.tex}

In my case I can now use chapter-relative figure folders, i.e. my folder structure looks like that:

/Main
- main.tex
+ chapters
 + introduction
     - introduction.tex
     + fig
         - figOfChapter1.png
+ conclusion
     - conclusion.tex
     + fig
         - figOfChapter2.png

Without "chapterfolder", I had to include a figure in chapter 1 (Introduction) like this:

\includegraphics{chapters/introduction/fig/figOfChapter1}

However, I want to be able to simply include figures by specifying a relative path to the chapter document, that is

\includegraphics{fig/figOfChapter1}

In order to achieve, this, we have to rewrite the includegraphics command. We can do that in the preamble, next to the usepackage statement:

\usepackage{chapterfolder}
% and we re-write includegraphics
\let\includegraphicsWithoutCF\includegraphics
\renewcommand{\includegraphics}[2][]{\includegraphicsWithoutCF[#1]{\cfcurrentfolder#2}}

This makes life much easier, especially if figures are moved from one chapter to another (I have only to move the file of the figure and can simply copy the code). And we are also able of compiling documents separately, as explained further on!

Compile Separately and Embedded

Although I'm using a wonderful LaTeX editor (Texshop) and my computer is pretty fast, working with a split document has some tradeoffs:

1. The "goto error" function in my editor is not working with included documents, which makes bug fixing really annoying.
2. Compiling a (currently) 100 page long document with lots of images takes quite some time

For that reason, I tried to figure out how to split my document and use a main file including all parts, while at the same time the parts could be compiled standalone. Here is my solution: In the main file, I define a command for letting the included files know that they are embedded:

\newcommand{\isEmbedded}{true}

In my parts (chapters), I can now test whether this command is defined or not, and include a preamble if required:

\ifx\isEmbedded\undefined
..
\documentclass{../../styles/myStyle}
..
other settings
...
\begin{document}
\maketitle
...
% -------+---------+---------+---------+---------+---------+---------+---------+
\else
\fi
% ******************************************************************************

Here comes the text of the chapter or part.

% ******************************************************************************
\ifx\isEmbedded\undefined
\bibliography{myBib}
...
\end{document}
\else
\fi

I can now compile every chapter separately, and finding a bug is very simple thanks to Texshops "Goto Error" function -- which is now working. Without any modifications, I can also compile the whole text, i.e. my main.tex file.

I eventually started writing my thesis--with LaTeX. Since it will become a rather long document (approx. 200 pages) I decided to split the document into its chapters (and maybe into more parts). Splitting a document is very easy with latex and it typically looks like that:

\documentclass{someClass}
... some definitions, use packages etc ...
\begin{document}
...
\maketitle
...
\input{abstract}
\input{introduction}
...
\input{relatedwork}
\input{conclusion}
...
\end{document}

This works pretty well, and I always use this pattern for writing smaller papers. Unfortunately I found two severe problems:

1. The latex compiler is unaware of folders.
2. I cannot compile the parts separately, which leads to new problems

Chapterfolder

The first problem is further described and solved by the latex package "chapterfolder". Instead of simply including a chapter, it is included and the current folder is changed accordingly. The main file will now look like this:

...
\begin{document}
...
\maketitle
...
\cfchapter{Introduction}{chapters/introduction}{introduction.tex}
...
\cfchapter{Conclusion}{chapters/conclusion}{conclusion.tex}

In my case I can now use chapter-relative figure folders, i.e. my folder structure looks like that:

/Main
- main.tex
+ chapters
 + introduction
     - introduction.tex
     + fig
         - figOfChapter1.png
+ conclusion
     - conclusion.tex
     + fig
         - figOfChapter2.png

Without "chapterfolder", I had to include a figure in chapter 1 (Introduction) like this:

\includegraphics{chapters/introduction/fig/figOfChapter1}

However, I want to be able to simply include figures by specifying a relative path to the chapter document, that is

\includegraphics{fig/figOfChapter1}

In order to achieve, this, we have to rewrite the includegraphics command. We can do that in the preamble, next to the usepackage statement:

\usepackage{chapterfolder}
% and we re-write includegraphics
\let\includegraphicsWithoutCF\includegraphics
\renewcommand{\includegraphics}[2][]{\includegraphicsWithoutCF[#1]{\cfcurrentfolder#2}}

This makes life much easier, especially if figures are moved from one chapter to another (I have only to move the file of the figure and can simply copy the code). And we are also able of compiling documents separately, as explained further on!

Compile Separately and Embedded

Although I'm using a wonderful LaTeX editor (Texshop) and my computer is pretty fast, working with a split document has some tradeoffs:

1. The "goto error" function in my editor is not working with included documents, which makes bug fixing really annoying.
2. Compiling a (currently) 100 page long document with lots of images takes quite some time

For that reason, I tried to figure out how to split my document and use a main file including all parts, while at the same time the parts could be compiled standalone. Here is my solution: In the main file, I define a command for letting the included files know that they are embedded:

\newcommand{\isEmbedded}{true}

In my parts (chapters), I can now test whether this command is defined or not, and include a preamble if required:

\ifx\isEmbedded\undefined
..
\documentclass{../../styles/myStyle}
..
other settings
...
\begin{document}
\maketitle
...
% -------+---------+---------+---------+---------+---------+---------+---------+
\else
\fi
% ******************************************************************************

Here comes the text of the chapter or part.

% ******************************************************************************
\ifx\isEmbedded\undefined
\bibliography{myBib}
...
\end{document}
\else
\fi

I can now compile every chapter separately, and finding a bug is very simple thanks to Texshops "Goto Error" function -- which is now working. Without any modifications, I can also compile the whole text, i.e. my main.tex file.

How to write very long documents with LaTeX