Browse Source

documentation

master
Jonathan Spratte 1 year ago
parent
commit
c77055fc91
6 changed files with 196 additions and 2 deletions
  1. 3
    0
      .gitignore
  2. 1
    1
      README.md
  3. BIN
      documentation.pdf
  4. 169
    0
      documentation.tex
  5. 22
    0
      example.c
  6. 1
    1
      listings-ext.py

+ 3
- 0
.gitignore View File

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

+ 1
- 1
README.md View File

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

BIN
documentation.pdf View File


+ 169
- 0
documentation.tex View File

@@ -0,0 +1,169 @@
1
+\documentclass[]{scrartcl}
2
+
3
+\makeatletter
4
+\newcommand*\py{\texttt{listings-ext.py}}
5
+\newcommand*\file{\texttt}
6
+\newcommand*\pkg{\textsf}
7
+\protected\def\meta#1{\texttt{$\langle$\textit{#1}$\rangle$}}
8
+\protected\def\cs#1{\texttt{\expandafter\@gobble\string\\#1}}
9
+\newcommand*\name{\emph{name}}
10
+\makeatother
11
+
12
+\title{\py}
13
+\author{Jonathan P.\@ Spratte}
14
+\date{\today}
15
+
16
+\usepackage{listings}
17
+\usepackage{listings-ext}
18
+\usepackage{enumitem}
19
+%% call listings-ext.py with:
20
+%%   ./listings-ext.py -o example.lst example.c
21
+\input{example.lst}
22
+
23
+\usepackage{xcolor}
24
+
25
+\lstdefinestyle{regex}
26
+  {
27
+    escapeinside=<>
28
+    ,escapebegin=$\langle$\begingroup\itshape
29
+    ,escapeend=\endgroup$\rangle$
30
+    ,otherkeywords={[,],?:,(,),\\A,\\s,\\w}
31
+    ,keywords=[1]{?:,(,)}
32
+    ,keywords=[2]{[,]}
33
+    ,keywords=[3]{\\A,\\s,\\w}
34
+  }
35
+\lstset
36
+  {%
37
+    basicstyle=\ttfamily
38
+    ,basewidth=.5em
39
+    ,language=html
40
+    ,keywordstyle=[1]{\bfseries\color{green!50!black}}
41
+    ,keywordstyle=[2]{\bfseries\color{red!50!black}}
42
+    ,keywordstyle=[3]{\bfseries\color{blue!50!black}}
43
+  }
44
+
45
+\begin{document}
46
+\maketitle
47
+
48
+\section{Introduction}
49
+\py\ was created because I liked the idea of the \pkg{listings-ext} package and
50
+the accompanying script \texttt{listings-ext.sh}, but I thought that naming the
51
+code blocks and getting the definitions with those names would be a more
52
+\LaTeX-y way, so I created this script.
53
+
54
+This script does extract lines and line ranges from a source file and outputs
55
+those ranges with \cs{lstdef}-calls so that \pkg{listings-ext} can understand
56
+them. Line ranges are marked using formatted comments.
57
+
58
+\section{File preparation}
59
+To make use of this script you have to mark the lines you want to be extracted.
60
+Those marks are formatted as a comment, and the lines containing those comments
61
+have to match the following regular expression:
62
+\begin{lstlisting}[style=regex]
63
+\A(?:\s+)(?:<comment char>) ([abej])e: ([\w:]+)
64
+\end{lstlisting}
65
+
66
+So there are four different types of mark: \texttt{ae}, \texttt{be},
67
+\texttt{ee}, and \texttt{je}. Each of those marks should be preceded by one
68
+or more space tokens followed by the appropriate \meta{comment char} of the used
69
+language and another space. After the mark there should be a colon and a space
70
+followed by a string which can consist of alphanumeric characters, underscores
71
+and colons, this string is considered the \name\ of that mark. The four
72
+different marks have the following effect:
73
+\begin{description}[font=\ttfamily]
74
+  \item[ae] the \name\ will combine \textbf{a}ll code blocks.
75
+  \item[be] \textbf{b}egin of code block \name.
76
+  \item[ee] \textbf{e}nd of code block \name.
77
+  \item[je] the \name\ will \textbf{j}oin together other code blocks.
78
+\end{description}
79
+So while there are four different marks, there are three categories to define a
80
+\name.
81
+
82
+The correct \meta{comment char} is guessed from the file extension of the file
83
+which is to be processed. There are a few file extensions included as a look up
84
+table, but the guess might be wrong or the file extensions unknown. For an
85
+unknown extension the regular expression
86
+\lstinline[style=regex]{#|%|!|;|//|/\*|--}
87
+is used. If the guess is wrong or that regular expression yields problems, take
88
+a look at the \texttt{--comment-char} parameter in section~\ref{sec:usage}.
89
+
90
+For the mark types \texttt{ae}, \texttt{be}, and \texttt{ee} everything in the
91
+line that follows after the \name\ will be ignored. On the other hand
92
+\texttt{je} will interpret the rest of the line in the following way. First
93
+another regular expression will be matched:
94
+\begin{lstlisting}[style=regex]
95
+(?:\s*=)[\w: ]+
96
+\end{lstlisting}
97
+This allows an optional \texttt{=} after the \name\ and a following space
98
+separated list of other possible names. As soon as a character that can't be
99
+part of a name is encountered, the rest of the line is dropped. The \name\ will
100
+combine the code blocks associated with the names in that space separated list.
101
+Subsequent calls of \texttt{je} will add the new list to the already defined
102
+list of names to be combined.
103
+
104
+The marks \texttt{be} and \texttt{ee} always have to be used in pairs, and
105
+mustn't be nested. Subsequent calls of \texttt{be} and \texttt{ee} pairs with
106
+the same \name\ will add the enclosed lines to that \name.
107
+
108
+The line in which you place \texttt{ae} and \texttt{je} marks doesn't matter,
109
+the \name\ will always act on a global scale.
110
+
111
+It is not checked whether a \name\ already defined in another category is
112
+redefined. A \name\ which is defined in multiple categories will be output
113
+multiple times, once for each category it is in, with the \texttt{ae} category
114
+being the first, then the \texttt{je} one, and finally the \texttt{be-ee}
115
+blocks.
116
+
117
+\section{Usage}\label{sec:usage}
118
+\py\ is called with a list of files to be processed, additionally it supports a
119
+few command line parameters to control its behaviour, the order doesn't matter,
120
+parameters can be given before or after file names. Arguments to parameters are
121
+always mandatory. The output will be printed
122
+to \texttt{stdout} by default.
123
+\begin{description}[font=-\ttfamily]
124
+  \item[a, --abs-path]
125
+    use the absolute file path instead of the path given as argument.
126
+  \item[b, --basename]
127
+    prefix every identifier with the processed file's basename followed by a
128
+    period.
129
+  \item[c, --comment-char=\meta{regex}]
130
+    use \meta{regex} as the comment starting \meta{comment char}. For instance
131
+    to match C-style comments this would be \lstinline{'//|/\*'}.
132
+  \item[h]
133
+    print a short help and exit
134
+  \item[S, --silent]
135
+    If used the program doesn't report which files to process and where to write
136
+    the output to.
137
+  \item[s, --spaces=\meta{choice}]
138
+    Defines how spaces at the begin of the line are handled.  \meta{choice} must
139
+    be one of:
140
+    \begin{description}[font=\ttfamily]
141
+      \item['must']
142
+        (default) there must be spaces before the start of the comment
143
+      \item['can']
144
+        there can be spaces before the start of the comment
145
+      \item['none']
146
+        no spaces are allowed before the start of the comment
147
+    \end{description}
148
+  \item[o, --output-file=\meta{output filename}]
149
+    if this argument is present, the output will be written into a file
150
+    \meta{output filename}; if \meta{output filename} is an empty string, the
151
+    output is redirected into a file with a basename corresponding to the name
152
+    of the current directory with the extension '.lst'.
153
+  \item[v, --version]
154
+    Print some version information and exit
155
+\end{description}
156
+
157
+\section{Example}
158
+As a small example, the following file contains every mark type, the \name\
159
+\texttt{main} is used twice, once as \texttt{je} and once in a \texttt{be-ee}
160
+block.
161
+\lstinputlisting[numbers=left,numberstyle=\tiny,language=c]{example.c}
162
+The file is saved as \file{example.c} and \py\ is run using
163
+\begin{lstlisting}[language=sh]
164
+listings-ext.py -o example.lst example.c
165
+\end{lstlisting}
166
+The following is the output in \file{example.lst}:
167
+\lstinputlisting[language=TeX]{example.lst}
168
+    
169
+\end{document}

+ 22
- 0
example.c View File

@@ -0,0 +1,22 @@
1
+ /* ae: complete */
2
+ /* je: functions = hello_world main */
3
+ /* je: main = headers hello_world -- this is rubbish */
4
+ /* be: headers */
5
+#include<stdio.h>
6
+ /* ee: headers */
7
+
8
+ /* be: hello_world */
9
+void hello_world(void)
10
+{
11
+	printf("Hello World!");
12
+	return;
13
+}
14
+ /* ee: hello_world */
15
+
16
+ /* be: main */
17
+int main(void)
18
+{
19
+	hello_world();
20
+	return 0;
21
+}
22
+ /* ee: main */

+ 1
- 1
listings-ext.py View File

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

Loading…
Cancel
Save