documentation

.gitignore

@@ -0,0 +1,3 @@
+documentation.aux
+documentation.log
+example.lst

README.md

@@ -14,4 +14,4 @@ License
 : GPLv3+ <https://gnu.org/licenses/gpl.html>
 
 Documentation
-: not yet
+: [documentation.pdf](https://gitlass.de/jonathan/listings-ext.py/src/branch/master/documentation.pdf)

documentation.tex

@@ -0,0 +1,169 @@
+\documentclass[]{scrartcl}
+
+\makeatletter
+\newcommand*\py{\texttt{listings-ext.py}}
+\newcommand*\file{\texttt}
+\newcommand*\pkg{\textsf}
+\protected\def\meta#1{\texttt{$\langle$\textit{#1}$\rangle$}}
+\protected\def\cs#1{\texttt{\expandafter\@gobble\string\\#1}}
+\newcommand*\name{\emph{name}}
+\makeatother
+
+\title{\py}
+\author{Jonathan P.\@ Spratte}
+\date{\today}
+
+\usepackage{listings}
+\usepackage{listings-ext}
+\usepackage{enumitem}
+%% call listings-ext.py with:
+%%   ./listings-ext.py -o example.lst example.c
+\input{example.lst}
+
+\usepackage{xcolor}
+
+\lstdefinestyle{regex}
+  {
+    escapeinside=<>
+    ,escapebegin=$\langle$\begingroup\itshape
+    ,escapeend=\endgroup$\rangle$
+    ,otherkeywords={[,],?:,(,),\\A,\\s,\\w}
+    ,keywords=[1]{?:,(,)}
+    ,keywords=[2]{[,]}
+    ,keywords=[3]{\\A,\\s,\\w}
+  }
+\lstset
+  {%
+    basicstyle=\ttfamily
+    ,basewidth=.5em
+    ,language=html
+    ,keywordstyle=[1]{\bfseries\color{green!50!black}}
+    ,keywordstyle=[2]{\bfseries\color{red!50!black}}
+    ,keywordstyle=[3]{\bfseries\color{blue!50!black}}
+  }
+
+\begin{document}
+\maketitle
+
+\section{Introduction}
+\py\ was created because I liked the idea of the \pkg{listings-ext} package and
+the accompanying script \texttt{listings-ext.sh}, but I thought that naming the
+code blocks and getting the definitions with those names would be a more
+\LaTeX-y way, so I created this script.
+
+This script does extract lines and line ranges from a source file and outputs
+those ranges with \cs{lstdef}-calls so that \pkg{listings-ext} can understand
+them. Line ranges are marked using formatted comments.
+
+\section{File preparation}
+To make use of this script you have to mark the lines you want to be extracted.
+Those marks are formatted as a comment, and the lines containing those comments
+have to match the following regular expression:
+\begin{lstlisting}[style=regex]
+\A(?:\s+)(?:<comment char>) ([abej])e: ([\w:]+)
+\end{lstlisting}
+
+So there are four different types of mark: \texttt{ae}, \texttt{be},
+\texttt{ee}, and \texttt{je}. Each of those marks should be preceded by one
+or more space tokens followed by the appropriate \meta{comment char} of the used
+language and another space. After the mark there should be a colon and a space
+followed by a string which can consist of alphanumeric characters, underscores
+and colons, this string is considered the \name\ of that mark. The four
+different marks have the following effect:
+\begin{description}[font=\ttfamily]
+  \item[ae] the \name\ will combine \textbf{a}ll code blocks.
+  \item[be] \textbf{b}egin of code block \name.
+  \item[ee] \textbf{e}nd of code block \name.
+  \item[je] the \name\ will \textbf{j}oin together other code blocks.
+\end{description}
+So while there are four different marks, there are three categories to define a
+\name.
+
+The correct \meta{comment char} is guessed from the file extension of the file
+which is to be processed. There are a few file extensions included as a look up
+table, but the guess might be wrong or the file extensions unknown. For an
+unknown extension the regular expression
+\lstinline[style=regex]{#|%|!|;|//|/\*|--}
+is used. If the guess is wrong or that regular expression yields problems, take
+a look at the \texttt{--comment-char} parameter in section~\ref{sec:usage}.
+
+For the mark types \texttt{ae}, \texttt{be}, and \texttt{ee} everything in the
+line that follows after the \name\ will be ignored. On the other hand
+\texttt{je} will interpret the rest of the line in the following way. First
+another regular expression will be matched:
+\begin{lstlisting}[style=regex]
+(?:\s*=)[\w: ]+
+\end{lstlisting}
+This allows an optional \texttt{=} after the \name\ and a following space
+separated list of other possible names. As soon as a character that can't be
+part of a name is encountered, the rest of the line is dropped. The \name\ will
+combine the code blocks associated with the names in that space separated list.
+Subsequent calls of \texttt{je} will add the new list to the already defined
+list of names to be combined.
+
+The marks \texttt{be} and \texttt{ee} always have to be used in pairs, and
+mustn't be nested. Subsequent calls of \texttt{be} and \texttt{ee} pairs with
+the same \name\ will add the enclosed lines to that \name.
+
+The line in which you place \texttt{ae} and \texttt{je} marks doesn't matter,
+the \name\ will always act on a global scale.
+
+It is not checked whether a \name\ already defined in another category is
+redefined. A \name\ which is defined in multiple categories will be output
+multiple times, once for each category it is in, with the \texttt{ae} category
+being the first, then the \texttt{je} one, and finally the \texttt{be-ee}
+blocks.
+
+\section{Usage}\label{sec:usage}
+\py\ is called with a list of files to be processed, additionally it supports a
+few command line parameters to control its behaviour, the order doesn't matter,
+parameters can be given before or after file names. Arguments to parameters are
+always mandatory. The output will be printed
+to \texttt{stdout} by default.
+\begin{description}[font=-\ttfamily]
+  \item[a, --abs-path]
+    use the absolute file path instead of the path given as argument.
+  \item[b, --basename]
+    prefix every identifier with the processed file's basename followed by a
+    period.
+  \item[c, --comment-char=\meta{regex}]
+    use \meta{regex} as the comment starting \meta{comment char}. For instance
+    to match C-style comments this would be \lstinline{'//|/\*'}.
+  \item[h]
+    print a short help and exit
+  \item[S, --silent]
+    If used the program doesn't report which files to process and where to write
+    the output to.
+  \item[s, --spaces=\meta{choice}]
+    Defines how spaces at the begin of the line are handled.  \meta{choice} must
+    be one of:
+    \begin{description}[font=\ttfamily]
+      \item['must']
+        (default) there must be spaces before the start of the comment
+      \item['can']
+        there can be spaces before the start of the comment
+      \item['none']
+        no spaces are allowed before the start of the comment
+    \end{description}
+  \item[o, --output-file=\meta{output filename}]
+    if this argument is present, the output will be written into a file
+    \meta{output filename}; if \meta{output filename} is an empty string, the
+    output is redirected into a file with a basename corresponding to the name
+    of the current directory with the extension '.lst'.
+  \item[v, --version]
+    Print some version information and exit
+\end{description}
+
+\section{Example}
+As a small example, the following file contains every mark type, the \name\
+\texttt{main} is used twice, once as \texttt{je} and once in a \texttt{be-ee}
+block.
+\lstinputlisting[numbers=left,numberstyle=\tiny,language=c]{example.c}
+The file is saved as \file{example.c} and \py\ is run using
+\begin{lstlisting}[language=sh]
+listings-ext.py -o example.lst example.c
+\end{lstlisting}
+The following is the output in \file{example.lst}:
+\lstinputlisting[language=TeX]{example.lst}
+    
+\end{document}

example.c

@@ -0,0 +1,22 @@
+ /* ae: complete */
+ /* je: functions = hello_world main */
+ /* je: main = headers hello_world -- this is rubbish */
+ /* be: headers */
+#include<stdio.h>
+ /* ee: headers */
+
+ /* be: hello_world */
+void hello_world(void)
+{
+	printf("Hello World!");
+	return;
+}
+ /* ee: hello_world */
+
+ /* be: main */
+int main(void)
+{
+	hello_world();
+	return 0;
+}
+ /* ee: main */

listings-ext.py

@@ -178,7 +178,7 @@ def give_help(name,err=0):# {{{
             "prefix every identifier with the processed file's basename "
             + "followed by a period."
             )
-    print_opt("-c, --comment_char <regex>",
+    print_opt("-c, --comment-char <regex>",
             "use <regex> as the comment starting character. For "
             + "instance to match C-style comments this would be '//|/\*'."
         )