path: root/macros/latex/contrib/coseoul/coseoul.tex

\documentclass[parskip,12pt]{scrartcl}
\usepackage[margin=20mm]{geometry}
\usepackage{multicol}
\usepackage{kerkis}
\usepackage{xcolor}
\usepackage{listings}
\usepackage{framed}
\usepackage[colorlinks=true,urlcolor=red]{hyperref}

\setlength{\columnseprule}{0.4pt}

\makeatletter
% tableofcontent
\renewcommand*\tableofcontents{%
  \section*{Contents}%       Überschrift (ohne Eintrag in toc)
  \columnseprule 0.5pt%                Dicke der Zwischenlinie
  \columnsep 2em%                      Spaltenabstand
  \begin{framed}%                      Rahmen
    \begin{multicols}{2}%              zwei Spalten
      \parskip\z@ \@plus .3\p@\relax%  Absatzabstand
      \@starttoc{toc}%                 toc-Liste ausgeben
    \end{multicols}
  \end{framed}
}

% Gliederungsnummer
\renewcommand{\numberline}[1]{%
  \makebox[1cm][l]{#1}\hspace{1mm}}

% section
\renewcommand{\l@section}[2]{%
  \addvspace{3ex}%                      vert. Abstand
  \pagebreak[3]%                        Seitenumbruch hier erlauben
  \noindent%                            nicht einrücken
  \makebox[0pt][l]{%                    Box für Linie
    \rule[-3pt]{\linewidth}{0.5pt}}%    Linie über Textbreite
  {\large\textbf{#1}}\hfill\textbf{#2}%          Text +  Nummer
  \par%                                 Zeilenumbruch
  \nopagebreak%                         Seitenumbruch nicht erlauben
  \addvspace{1ex}%                      vert. Abstand
}

% subsection
\renewcommand{\l@subsection}[2]{%
  \addvspace{0.5ex}%                     vert. Abstand
  \pagebreak[0]%                        Seitenumbruch hier nicht erlauben
  \noindent%                            nicht einrücken
  {\large#1}\hfill#2%          					Text +  Nummer
  \par%                                 Zeilenumbruch
  \addvspace{1ex}%                      vert. Abstand
}

%\renewcommand*\l@subsection{\@dottedtocline{2}{0pt}{1.1cm}}

\makeatother

\newcommand{\blindtext}{asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb asdf qwe yxcvb }

\lstdefinestyle{nonum}{language=[LaTeX]TeX, numbers=none, frame=lr	,backgroundcolor=\color{black!10!white}, rulecolor=\color{blue!80!black}, tabsize=2}

\lstdefinestyle{codelst}{language=[LaTeX]TeX, numbers=left, numberstyle=\tiny, stepnumber=5, numbersep=5pt, firstnumber=1, frame=ltbr, backgroundcolor=\color{black!10!white}, rulecolor=\color{blue!80!black}, tabsize=2}

\lstdefinestyle{codetop}{language=[LaTeX]TeX, numbers=left, numberstyle=\tiny, stepnumber=1, numbersep=5pt, firstnumber=1, frame=ltr, backgroundcolor=\color{black!10!white}, rulecolor=\color{blue!80!black}, tabsize=2}

\lstdefinestyle{codemid}{language=[LaTeX]TeX, numbers=left, numberstyle=\tiny, stepnumber=1, numbersep=5pt, , frame=lr, backgroundcolor=\color{black!10!white}, rulecolor=\color{blue!80!black}, tabsize=2}

\lstdefinestyle{codebot}{language=[LaTeX]TeX, numbers=left, numberstyle=\tiny, stepnumber=1, numbersep=5pt, frame=lbr, backgroundcolor=\color{black!10!white}, rulecolor=\color{blue!80!black}, tabsize=2}

\begin{document}
{\Huge Context sensitve ouline elements:\\ a manual for \textbf{coseoul}}

{\LARGE Dynamic alteration of the document structure}

{\LARGE {\today} \textsc{Version 1.1}}

written by \textsc{Michael Teubner}, August 2011

\tableofcontents

\section{Introduction}
The commands used for document outlining in {\LaTeX} are quite rigid. If you define a heading to be at chapter level, it will remain at that level even when you move it to a different part of your document. While this is desirable most of the time, there are some cases in which a more flexible approach may be needed, like in collaborative work, when writing comprehensive documents or when assembling a document from many different sources. This package aims at providing means of such flexible outlining. 

\section{Working principle}
Instead of specifying exactly at what level your outline element should appear, this package provides relative commands for going up and down in the outline hierarchy. The commands provided are:
\begin{itemize}
	\item \verb+\levelup{<title>}+\\This command goes up one level in the document hierarchy, so depending on where you are, this will insert an outline element \verb+<title>+ at one level above the current. So if for instance written inside a section, this command will insert a new chapter.
	\item \verb+\leveldown{<title>}+\\This command goes down one level in the document hierarchy, so depending on where you are, this will insert an outline element \verb+<title>+ at one level below the current. So if for instance written inside a paragraph, this command will insert a new subparagraph.
	\item \verb+\levelstay{<title>}+\\This command stays at the current document hierarchy level, so depending on where you are, this will insert an outline element \verb+<title>+ at the same as the current level. So if for instance written inside a subsection, this command will insert a new subsection.
	\item \verb+\levelmultiup{<title>}{<levels>}+\\This goes up multiple levels in the document hierarchy, so depending on where you are, this will insert an outline element \verb+<title>+ at a level differing by \verb+<levels>+ from the current level. So if for instance writte \verb+\levelmultiup{title}{3}+ inside a paragraph, this command will insert a new section. This may be used for situation in which level skipping is required. While downwards you will go only one level, upwards a skip of more than one may be required, for instance if you are in the last subsubsection of a passage of your text and as you want to start a new passage you need to insert a section.
\end{itemize}

\section{Use cases}
\subsection{Collaborative work}
Suppose you are writing a complex document where you collaborate with others (a book on Mexican cacti, a documentation for your extensive software project or a term paper). Hopefully you all could agree to use {\LaTeX}, but still problems arise as you only see each other about once a month. So during this month, all of you work on their respective parts, but when meeting you decide to swap parts, raise the importance of some and lowering the importance of others. Usually this would require rewriting outline elements, but with this package you only need to move stuff to the right place and probably changing one or two outline elements, all the others change accordingly as they are context sensitive, which may save you a lot of work. 
\\
\\
Lets say Alice and Bob are writing on that cactus book. Alice, touring northern Mexico, wrote this:
\lstset{style=codelst}
\begin{lstlisting}
\documentclass{scrartcl}
\usepackage{coseoul}
\begin{document}
\levelstay{Corynopuntia}         % main
\leveldown{Grusonia aggeria}     % sub
\levlestay{Grusonia agglomerata} % sub
\levlestay{Grusonia bulbispina}  % sub
\end{document}
\end{lstlisting}
While Bob, scouting southern Mexico, wrote this:
\begin{lstlisting}
\documentclass{scrreprt}
\usepackage{coseoul}
\begin{document}
\levelstay{Grusonia}           % main
\leveldown{Grusonia bradtiana} % sub
\levelup{Marenopuntia}         % main
\levelstay{Grusonia marenae}   % sub
\end{document}
\end{lstlisting}
Ideally, of cause, they would store their content including outline in seperate files, but this should only be a small example. Alice, writing an article type document, would usually use sections top level outline element, while Bob, who is writing a report style document, would use sections. When combining their work either Alice (all one level up) or Bob (all one level down) would have to rewrite their outline. Instead, Bob only changes his first element to \lstinline!\levleup! and they are ready to go!
\begin{lstlisting}
\documentclass{scrartcl}
\usepackage{coseoul}
\begin{document}
% Alices contribution
\levelstay{Corynopuntia}         % main
\leveldown{Grusonia aggeria}     % sub
\levlestay{Grusonia agglomerata} % sub
\levlestay{Grusonia bulbispina}  % sub
% Bobs contribution
\levelup{Grusonia}             % main, only changed command
\leveldown{Grusonia bradtiana} % sub
\levelup{Marenopuntia}         % main
\levelstay{Grusonia marenae}   % sub
\end{document}
\end{lstlisting}

\subsection{Writing a thesis}
Suppose you are writing your master thesis, say on \textit{mobility management in Germany}. You are writing for quite some time and interviewed quite some people in different cities on the topic. As you go, you realize that your initial outline, which made perfect sense at the time of writing, now seems odd. Not that it is wrong, but some parts are condensed now and should be subordinate to others, some portions are to be moved, recombined, edited or deleted, but this will mess up your outline. If you considered that something like this might happen, you used this package and have relatively little to do:
\begin{itemize}
	\item to subordinate, just change \verb!\levelstay! to \verb!\leveldown!
	\item move portions to a new, more appropriate position. No matter what level they are now on, worst case is you have to adjust it's first outline command and that of the next portion
	\item recombination is really like moving, two changes at most per portion, however long or complex
\end{itemize}

\subsection{Editing a compilation}
Suppose you are an editor, responsible for some proceedings. The guy responsible for writing a template that any participant should use was ill, now everyone submitted documents outlined to their individual liking: structured in sections or chapters, some mistaking this for a book and using parts. Now you are left with the mess, but fortunately, they all used \textbf{coseoul}, so you \verb!\include! all their documents and you are (almost) done!

\section{Package options}
There are no \textit{real} options at this time.

\subsection{Current level}
While document classes defining chapters are initialized at that level, classes not defining chapters are initialized at section level.

Normally, you would not want to set \verb!\currentlevel! manually. However, you might want to start a document with a \verb!\part!, to achieve that you can do the following:\\
\verb!\setcounter{currentlevel}{<level>}! where <level> can be:

\begin{tabular}{l|l}
 7 & for part level\\
 6 & for chapter level\\
 5 & for section level\\
 4 & for subsection level\\
 3 & for subsubsection level\\
 2 & for paragraph level\\
 1 & for subparagraph level\\
\end{tabular}

But be aware: if you set the level to chapter in a document not defining those, and immediately after use \verb!\levelstay!, you will produce an error. 

There will probably a function with named arguments in the future (see~\ref{limits}).

\section{Limitations}
\label{limits}
\subsection{Min and max levels}
It would be desirable to specify minimum and maximum levels to use. Most people will not want to use parts, paragraphs or even subparagraphs. Right now, all levels are uses, with no chance of influence. I'm thinking of something like:

\verb!\usepackage[minlevel=subsubsection, maxlevel=chapter]{coseoul}!

\subsection{Initial level} Document classes with chapters are initialized at chapter level, classes without it are initialized at section level. There should be a package option for that:

\verb!\usepackage[initlevel=section]{coseoul}!

\subsection{Structure warnings}
When you use \verb!\leveldown! are on the lowest level or use \verb!\levelup! on the highest level, the new element will still be set on the same level, as there are no lower or higher levels which could be used. As this will possibly compromise your structure, there should be an optional warning for such occurrence. So something like

\lstset{style=nonum}
\begin{lstlisting}
...
\usepackage[warningstop, warningsbottom]{coseoul}
...
\levelup{part}
\levelup{above part}
...
\levelup{subparagraph}
\levelup{below subparagraph}
\end{lstlisting}

should result in:

\textbf{I part}\\
\textbf{II above part \textcolor{red}{(Warning: level above top)}}\\
...\\
\textbf{subparagraph}\\
\textbf{below subparagraph \textcolor{orange}{(Warning: level below bottom)}}

Also entries in the log file would be nice.

\subsection{Change levels}
Manually changing the level is possible, but not comfortable, there should really be some command like:

\verb!\setcurrentlevel{subsection}!. 

\section{Developement history}
\subsection{Inspiration}
The package is based on \href{http://tex.stackexchange.com/questions/26181/create-context-sensitive-headings/}{this question} on \url{tex.stackexchange.com}. The user Speldosa wanted to know if such flexible behaviour was possible, and so I started the development. While the first version was quite straightforward and complicated, the big number of lines of code made me think about my approach and totally redesign it.

\subsection{First attempt}
The very first version, although working yet, was in a well human readable but not elegant form. It consisted of many, many \verb!\ifthenelse! constructs which also had to be in the right order. The current level was denoted by a string and therefore had to be redefined quite often. As no standard level was defined, one of the absolute commands like \verb!\newchapter! had to be used. \verb!\levlemultiup! did not  exist yet, there also absolute commands had to be used.
\lstset{style=nonum}
\begin{lstlisting}
...
\newcommand{\currentlevel}{}

\newcommand{\levelup}[1]%
{ \ifthenelse{\equal{\currentlevel}{c}}%
  {\chapter{#1}\renewcommand{\currentlevel}{c}}{}%
  \ifthenelse{\equal{\currentlevel}{s}}%
  {\chapter{#1}\renewcommand{\currentlevel}{c}}{}%
... 
\newcommand{\newchapter}[1]%
  {\chapter{#1}\renewcommand{\currentlevel}{c}}
...  
\end{lstlisting}

\subsection{Current Version}
When I tried to expand the first version to all outline elements and also a \verb!\levlemultiup!, I realized that this would be $(3 \cdot 2 + 7 \cdot 5) \cdot 2 = 82$ new lines of code, and that for achieving relatively little, so I decided to rewrite the code from scratch. The indicator for the current level (\verb!\currentlevel!), formerly containing strings, is now a counter, thus operations on levels now are arithmetic operations instead of string rewrites. Instead of defining separate commands for each task (\verb!\levleup! and the others), they are now derived from a general command. \verb!\currentlevel! is never set to chapter if used in a \verb!\documentclass! not defining it. \verb!\documentclass!es defining chapters are initialized as such, while those which do not are initialized at section level.

\lstset{style=nonum}
\begin{lstlisting}
...
\newcommand{\chex}{}
\ifthenelse{\isundefined{\chapter}}%
	{\renewcommand{\chex}{N}}{\renewcommand{\chex}{Y}}
...
\newcounter{currentlevel}
...
\newcommand{\findnewlevel}[1]%
{	\addtocounter{currentlevel}{#1}%
...
\newcommand{\levelchange}[2]%
{	\findnewlevel{#2}%
	\ifthenelse{\value{currentlevel} = 1}{\subparagraph{#1}}{}%
...	
\newcommand{\levelup}[1]{\levelchange{#1}{1}}	
...
\end{lstlisting}
	
\subsection{Future Developement}
The current version, while being fully functional, has several shortcomings (see~\ref{limits}). I plan on adding more features, but I don't know when or to what extend, so better not wait for changes. The \href{https://bitbucket.org/Kraken/coseoul/overview}{current version} is also maintained by \textsc{Kraken} at  \href{https://bitbucket.org/}{BitBucket.org}

\section{Acknowledgements}
First of all, thanks to \textsc{mahok}, you first made me aware that something awesome like {\LaTeX} existed.
\subsection{The custom TOC}
The table of contents was modelled on an example from \textsc{Elke} and \textsc{Michael Niedermair}: \href{http://www.amazon.de/LaTeX-Das-Praxisbuch-Elke-Niedermair/dp/3772369308/ref=sr_1_3?s=books&ie=UTF8&qid=1314210321&sr=1-3}{"{\LaTeX}.~Das~Praxisbuch"}. Thanks for the example and the book as a whole, it's what got me started with {\LaTeX}.

\subsection{The name \textbf{coseoul}}
I decided to go with the first two letters of each word in the phrase 'Context Sensitive Outline Elements', which would be 'CoSeOuEl'. Four vocals in a row was too much for my taste, so my alternate ideas were 'consul', 'console', or something with 'Seoul'. As I'm not too much of a fan of the Romans nor want to mislead anyone into thinking this was some kind of command line tool, I decided to go with the Seoul idea. Although I have never been there, what better reason is there to visit Seoul than to see the city I named my package after!

\subsection{This document}
This document does \textit{not} use any of the features of \textbf{coseoul}, as you should be able to build this documentation on your own. So you can install the package \textit{after} you built and read the manual.

\newpage

\section{Code}
\subsection{Complete Code}
\lstset{style=codelst}
\lstinputlisting{coseoul.sty}

\newpage

\subsection{Commented Code}
This section is mainly for people like me, who have never or seldomly created packages. So if you are a \textit{deep magic wizard}, please don't take offence in my simplistic explanations.\\

\lstset{style=codetop}
\lstinputlisting[firstline=1, lastline=2]{coseoul.sty}
The first line tells {\LaTeX} that this file provides the package \textbf{coseoul}. Note that the file name doesn't have to coincide with the package name, so foo.sty may provide a package bar. The second line states that the package \textbf{ifthen} is required for this to work. So such commands state dependencies on other packages.\\

\lstset{style=codemid, firstnumber=4}
\lstinputlisting[linerange={4-13}]{coseoul.sty}
First, a command \verb!\chex! is initialized as empty, then a counter is initialized (as zero). Then it is checked, if currently a command \verb!\chapter! is defined. If it is not, \verb!\chex! is set to 'N' and the document is initialized at section level. If it is, then \verb!\chex! is set to 'Y' and the document is initialized at chapter level.\\

\lstset{firstnumber=15}
\lstinputlisting[linerange={15-16}]{coseoul.sty}
a new command  \verb!\findnewlevel! with one parameter is defined. The comment explains which values it will take for which command. The number given in the argument is then added to \verb!\currentlevel!, thus changing the active level.\\

\lstset{firstnumber=17}
\lstinputlisting[linerange={17-20}]{coseoul.sty}
Here we have a triple nested \verb!\ifthenelse! statement. The first two are used to check whether we are at chapter level (currentlevel = 6) although chapter is undefined (\verb!\chex! = 'N'). If this is the case, then dependant on whether we move level up or down (1 or -1), the \verb!\currentlevel! counter increased or decreased by one.\\

\lstset{firstnumber=21}
\lstinputlisting[linerange={21-22}]{coseoul.sty}
The level may range from 1 to 7. Therefore values outside that range are set to the respective nearest value. This may cause undesired effects (see~\ref{limits})\\

\lstset{firstnumber=25}
\lstinputlisting[linerange={25-26}]{coseoul.sty}
A new command \verb!\levelchange! is defined, which has two arguments, the title for the new outline element and the desired change in level (labelled 'uppity'). Then the previously defined \verb!\findnewlevel! is called with the desired change in level.\\

\lstset{firstnumber=27}
\lstinputlisting[linerange={27-33}]{coseoul.sty}
According to what value \verb!\currentlevle! was changed by \verb!\findnewlevel!, a new outline element is inserted.\\

\lstset{style=codebot, firstnumber=36}
\lstinputlisting[linerange={36-39}]{coseoul.sty}
Four commands are defined for easily changing the outline level. These are pure convineance, as you could also use \verb!\levelchange! directly with the appropriate parameters.

\newpage

\section{Licence}
 \textbf{coseoul.tex} \& \textbf{coseoul.pdf}\\
 Copyright 2011 \textsc{M. Teubner}

 This work may be distributed and/or modified under the
 conditions of the LaTeX Project Public License, either version 1.3
 of this license or (at your option) any later version.
 The latest version of this license is in \url{http://www.latex-project.org/lppl.txt}
 and version 1.3 or later is part of all distributions of LaTeX
 version 2005/12/01 or later.

 This work has the LPPL maintenance status `maintained'.

 The Current Maintainer of this work is \textsc{M. Teubner}.

 This work consists of the files \textbf{coseoul.sty}, \textbf{coseoul.tex}, \textbf{cosexamp.tex}
 and the derived files \textbf{coseoul.pdf} and \textbf{cosexamp.pdf}.


\end{document}