You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

documentation.tex 8.6KB

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