Wednesday, July 22, 2009

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!

Thursday, July 16, 2009

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.

Wednesday, July 15, 2009

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.