summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/texcount/TeXcount.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/texcount/TeXcount.tex')
-rw-r--r--Master/texmf-dist/doc/support/texcount/TeXcount.tex166
1 files changed, 123 insertions, 43 deletions
diff --git a/Master/texmf-dist/doc/support/texcount/TeXcount.tex b/Master/texmf-dist/doc/support/texcount/TeXcount.tex
index a460d8be924..3ec27f73368 100644
--- a/Master/texmf-dist/doc/support/texcount/TeXcount.tex
+++ b/Master/texmf-dist/doc/support/texcount/TeXcount.tex
@@ -8,21 +8,12 @@
%\parindent=0pt\parskip=8pt
-%TC:macroword \TeXcount 1
-\newcommand\TeXcount{{\TeX}count}
-
-\newcommand\code[1]{\texttt{\small#1}}
-\newcommand\bigcode[1]{\texttt{#1}}
-\newcommand\codeline[1]{\begin{quote}\code{#1}\end{quote}}
-\newcommand\bs[1]{$\backslash$#1}
-\newcommand\URL[1]{\texttt{\small #1}}
-
-%TC:macro NB 1
-\newcommand\NB[1]{\marginpar{\textsf{\tiny#1}}}
\title{\TeXcount\footnote{Copyright 2008 Einar Andreas Rødland, distributed
under the \LaTeX{} Project Public Licence (LPPL).}\\
-Perl script for counting words in \LaTeX{} documents}
+\Large
+Perl script for counting words in \LaTeX{} documents\\
+Version 2.1}
\author{Einar Andreas Rødland}
\begin{document}
@@ -71,7 +62,7 @@ In general, while \TeXcount{} does the parsing in some detail, it does not do it
Another issue is that, since \TeXcount{} does not know how to expand macros, it cannot handle macros like \code{\bs{maketitle}}. Instead, it will count \code{\bs{title}\{title text\}} when it occurs.
-For users of languages containing letters other than A to Z, there may be an additional challenge. The script relies on Perl to recognize words as sequence of letters, and must therefore know which characters are considered to be letters. The Perl locale may be changed (as of now this is hard-coded!) to accommodate this, but this does not work for special letters encoded using \TeX{} or \LaTeX{} macros or codes: e.g. \code{\bs{aa}} and \code{\bs{"}a} will not be understood to be letters in the present implementation, whereas \code{\aa} and \code{\"a} will.
+For users of languages containing letters other than A to Z, there may be an additional challenge. The script relies on Perl to recognize words as sequence of letters, and must therefore know which characters are considered to be letters. The Perl locale may be changed (as of now this is hard-coded!) to accommodate this, but this does not work for special letters encoded using \TeX{} or \LaTeX{} macros or codes: e.g. \code{\bs{aa}} and \code{\bs{"}a} will not be understood to be letters in the present implementation, whereas \code{\aa} and \code{\"a} will. I have added a relaxed mode where some special character and character modifying macros are allowed as parts of words, which may be activated with the option \code{-relaxed}.
\section{Syntax and options}
@@ -87,45 +78,103 @@ Under Windows, running \code{texcount} from the command line suffices if \code{t
Alternatively, if the above methods do not work, you may have to execute it more exclicitly under Perl using \code{perl texcount.pl}. You then need to have the \code{perl} executable file in the path or give the explicit path.
I will simply write \code{texcount} in this manual for the code to execute the script. Then, the syntax becomes
-\codeline{texcount [options] [files]}
+\codeline{texcount \textit{[options] [files]}}
where the options may be amongst the following:
-\begin{description}\def\option[#1]{\item[\quad\code{#1}]}
-\option[-v]Verbose (same as -v3)
-\option[-v0]No details (default)
-\option[-v1]Prints counted text, marks formulae
-\option[-v2]Also prints ignored text
-\option[-v3]Also includes comments and options
-\option[-v4]Same as \code{-v3 -showstate}
-\option[-showstate]Show internal states (with verbose)
-\option[-brief]Only prints a one line summary of the counts
-\option[-nc, -nocol]No colours (colours require ANSI)
-\option[-inc]Include tex files included in the document
-\option[-noinc]Do not include included tex files (default)
-\option[-html]Output in HTML format
-\option[-htmlcore]Only HTML body contents
-\option[-h, -?, --help, /?]Help
-\option[--version]Print version number
-\option[--license]License information
+\begin{description}
+\def\option[#1]{\item[\quad\code{#1}]}
+\def\alt#1{[#1]}
+
+\option[-v]Verbose (same as -v3).
+
+\option[-v0]No details (default).
+
+\option[-v1]Prints counted text, marks formulae.
+
+\option[-v2]Also prints ignored text.
+
+\option[-v3]Also includes comments and options.
+
+\option[-v4]Same as \code{-v3 -showstate}.
+
+\option[-showstate]Show internal states (with verbose).
+
+\option[-brief]Only prints a one line summary of the counts.
+
+\option[-total]Only give total sum, no per file sums.
+
+\option[-1]Same as specifying \code{-brief} and \code{-total}, and ensures there will only be one line of output. If used with \code{-sum}, the output will only be the total number.
+
+\option[-sub\alt{=\ldots}, -subcount\alt{=\ldots}]Generate subcounts. Valid option values are \code{none}, \code{part}, \code{chapter}, \code{section} and \code{subsection} (default), indicating at which level subcounts are generated.
+
+\option[-sum\alt{=n,n,\ldots}]Produces total sum, default being all words and formulae, but customizable to any weighted sum of the seven counts (list of weights for text words, header words, caption words, headers, floats, inlined formulae, displayed formulae).
+
+\option[-nc, -nocol]No colours (colours require ANSI).
+
+\option[-relaxed]Relaxes the rules for matching words and macro options.
+
+\option[-inc]Include tex files included in the document.
+
+\option[-noinc]Do not include included tex files (default).
+
+\option[-dir\alt{=\ldots}]Working directory, either taken from the first file given, or specified.
+
+\option[-html]Output in HTML format.
+
+\option[-htmlcore]Only HTML body contents.
+
+\option[-codes]Display an overview of the colour codes. Can be used as a separate option to only display the colour codes, or together with files to parse.
+
+\option[-nocodes]Do not display overview of colour codes.
+
+\option[-h, -?, --help, /?]Help.
+
+\option[--version]Print version number.
+
+\option[--license]License information.
+
\end{description}
If more than one file is given, \TeXcount{} will perform the count on each of them printing the results for each, then print the total sum at the end.
-\subsection{Details}
+\subsection{Parsing details}
-By selecting one of the \code{-v} options, you can choose how much detail is printed. This is useful for checking what \TeXcount{} counts.
+By selecting one of the \code{-v} options, you can choose how much detail is printed. This is useful for checking what \TeXcount{} counts. The option \code{-showstate} shows the internal state and is for debugging purposes only.
-The output is colour coded with counted text coloured blue, other colours for other contexts. The colour coding is made using ANSI colour codes. These should work when printed directly to Linux xterm window, but need not work if piped through \code{more} or \code{less}: with \code{less} you need to use the option \code{-r} for the colours to be shown correcly. Under Windows or other operating systems, the ANSI colour codes cannot be expected to work, in which case the option \code{-nocol} (\code{-nc}) may be used to turn off colour coding; instead I recommend using HTML output which can be viewed in a browser.
+The output is colour coded with counted text coloured blue, other colours for other contexts. The colour coding is made using ANSI colour codes. These should work when printed directly to Linux xterm window, but need not work if piped through \code{more} or \code{less}: with \code{less} you need to use the option \code{-r} for the colours to be shown correcly.
+
+Under Windows or other operating systems, the ANSI colour codes cannot be expected to work, in which case the option \code{-nocol} (\code{-nc}) may be used to turn off colour coding; instead I recommend using HTML output which can be viewed in a browser.
To print the details encoded as HTML code, use the option \code{-html}; alternatively, with \code{-htmlcore} only the HTML body is printed. On Windows, I suggest using the options \code{-html -v} to get full detail, save this to a HTML file, e.g. using
\codeline{texcount -html -v texfile.tex > details.html}
and then view the details.html file in a browser.
+\subsection{Summary information}
+
+By default, \TeXcount{} outputs counts of text words, header words, caption words, number of headers, number of floats/figures, number of inlined formulae, and number of displayed formulae, and lists each of these counts. To shorten this to a one-line format, specify \code{-brief}.
+
+To get \TeXcount{} to produce a total count, specify \code{-sum}: this will compute the sum of all words plus the number of formulae. A customized sum may be computed by speficying \code{-sum=n,n,\ldots} with up to seven numbers separated by commas giving the weight (0=don't count, 1=count once) of each of the seven counts: e.g. the default is equivalent to \code{-sum=1,1,1,0,0,1,1}. To count words only, use \code{-sum=1,1,1}. Higher weights may also be used, e.g. to count displayed formulae or floats/figures as a given number of words.
+
+Specifying \code{-sum} has two main effects: the cumulative sum is added to the output in verbose formats, and the sum is added to the summary. If combined with \code{-brief}, the option \code{-total} is automatically set, resulting in a one line output containing only the total sum.
+
+For adding subcounts e.g. by sections, the option \code{-sub} (or \code{-subcount}) may be used. By default, this produces subcounts by part, chapter, section and subsection which are listed in a brief format. One may, however, specify \code{-sub=} followed by \code{part}, \code{chapter}, \code{section}, or \code{subsection} (default when given without value). Break points which initiate a new subcount may also be specified within the \LaTeX{} document using \code{\%TC:break name}.
+
+If included files are included in the count (\code{-inc}), counts per file will be produced followed by a total count. To suppress per file counts, the option \code{-total} may be used.
+
\subsection{Parsing options}
-If the option \code{-inc} is used, \TeXcount{} will automatically count documents that are included (using \code{\bs{input}} or \code{\bs{include}}. As when giving a list of files to count, it will print the sum per file and a total sum at the end.
+\TeXcount{} uses regular expressions to identify words and macro options. By default, these are moderately strict, but can be relaxed using the option \code{-relaxed}. This allows more general document elements to be identified as words or macro options, which may sometimes be desired, but may also have undesirable effects, so check the verbose output to verify that \TeXcount{} has counted the appropriate elements.
+
+Macro options, i.e. \code{[\ldots]} after macros and macro parameters are ignored. Since \TeXcount{} has no specific knowledge of which macros take options, this is a general rule. In order to avoid that uses of [\ldots] that are not macro options are mistaken as such, \TeXcount{} makes some restrictions on what may be contained in such an option. By default, this restriction is relatively strict under the assumption that it is better to count a few macro options as words than risk large fragments of text to be ignored. However, if your document contains macro options with more complicated values (e.g. certain special characters or macros), using \code{-relaxed} may help handle these correctly.
+
+By default, \TeXcount{} does not allow special characters or macros to be part of words. This may cause problems if character modifiers or some special characters are used which are entered as macros. The \code{-relaxed} option makes the word recognition regular expression somewhat more general.
-The default is \code{-noinc} indicating that included documents are not counted.
+\subsection{File inclusion}
+If the option \code{-inc} is used, \TeXcount{} will automatically count documents that are included (using \code{\bs{input}} or \code{\bs{include}}. As when giving a list of files to count, it will print the sum per file and a total sum at the end. The default is \code{-noinc} indicating that included documents are not counted.
+
+By default, \TeXcount{} assumes paths are relative to the working directory. Alternatively, an explicit path may be given using \code{-dir=path}. Note that the path must end in the path delimiter symbol (depending on the operating system, \code{/} under Linux, \textbackslash under Windows). If only \code{-dir} is used, the path of the first file given will be used.
+
+Note that included documents are analysed as separate files: the text of included documents are thus not included where the \code{\bs{input}} or \code{\bs{include}} is located. This has two consequences. First, since word counts are produced per file, subcounts f.ex. by chapter will only include the text in the same file as the \code{\bs{chapter}} macro. Secondly, if TC-instructions to \TeXcount{} are embedded in the \LaTeX{} document, e.g. defining additional macro handling rules, these take effect in the order they are parsed by \TeXcount{}. Since included documents are parsed after the parent document, definitions in the parent document will be in effect for the included documents; definitions made in the included documents will only be in effect for subsequently included documents, not in the parent or previously included documents.
\section{What \TeXcount{} counts}
@@ -150,9 +199,9 @@ A very few rules are hard-coded, e.g. that text between \code{\bs{documentclass}
\TeXcount{}, the reason being that the rule originally only gave the number of
parameters to ignore following a given macro.)
-\item[header]Macros that are specified to be counted as headers. In fact, this only indicates that the macro should cause the number of headers to be increased by one; a rule is added to the macro-rule to count the following parameter as header text.
+\item[header]Some macros are specified to be counted as headers. This initially only indicates that the macro should cause the number of headers to be increased by one, but an additional rule is added to the macro-rule to count the following parameter as header text.
-\item[group]For groups enclosed by \code{\bs{begin}\{\textit{name}\}} and \code{\bs{end}\{\textit{name}\}}, there are rules specifying how the contents should be interpreted. A macro rule is added for \code{begin\textit{name}} (without the backslash!) which is \TeXcount{}'s internal representation of \code{\bs{begin}\{\textit{name}\}}.
+\item[group]For groups enclosed by \code{\bs{begin}\{\textit{name}\}} and \code{\bs{end}\{\textit{name}\}}, there are rules specifying how the contents should be interpreted. A macro rule is added for \code{begin\textit{name}} (without the backslash!) which is \TeXcount{}'s internal representation of \code{\bs{begin}\{\textit{name}\}}. Some special characters will be ignored if following \code{\textit{name}}, e.g. \code{\bs{begin}\{equation*\}} will be treated as \code{\bs{begin}\{equation\}} since \code{*} is ignored.
\item[macroword]This type of rule indicates that the macro itself represents one or more words. Initially, \code{\bs{LaTeX}} and \code{\bs{TeX}} are defined with values 1 indicating that each represents one word.
@@ -160,7 +209,7 @@ parameters to ignore following a given macro.)
\item[float inclusion]Within floats (begin-end groups defined with parsing status $-1$) there may be texts that should still be counted: in particular captions. These are specified with the float inclusion rule.
-\item[file include]If \code{-inc} is specified, included files will also be parsed and the total presented at the end. Initially, \code{\bs{input}} and \code{\bs{include}} trigger file inclusion, but more macros may be added here.
+\item[file include]If \code{-inc} is specified, included files will also be parsed and the total presented at the end. Initially, \code{\bs{input}} and \code{\bs{include}} trigger file inclusion, but more file inclusion macros may be added.
\end{description}
@@ -177,7 +226,34 @@ More critically, since \TeXcount{} does not really know which macros take option
More advanced macros are not supported and can potentially confuse \TeXcount{}. In partcular, if you define macros that contain unbalanced begin--end groups, this will cause problems as \TeXcount{} needs to keep track of these to know where different groups start and end.
-\section{Adding your own rules}
+\section{\TeXcount{} instructions in the \LaTeX{} document}
+
+It is possible to give some instructions to \TeXcount{} from within the
+\LaTeX{} document. The general format of these instructions are
+\codeline{\%TC:\textit{instruction [name] parameters}}
+where the name parameter is used with macro handling instructions to specify the macro or group name for which the rule applies.
+
+Note that the comment should be on a separate line, and that instructions are case sensitive.
+
+\subsection{Ignoring segments of the file}
+
+The TC-instruction \code{ignore}, later canceled by \code{endignore}, may be used to turn of all counting in a segment of the \LaTeX{} file. The ignored segment should thus be started by
+\codeline{\%TC:ignore}
+end ended by
+\codeline{\%TC:endignore}
+causing all text inbetween to be ignored. Note that \TeXcount{} still parses this text and may be affected by unbalanced brackets.
+
+\subsection{Adding subcount break points}
+
+By specifying \code{-sub}, \TeXcount{} can produce subcounts, e.g. per section. Alternatively, or in addition, explicit break points can be entered in the \LaTeX{} document using the TC-instruction \code{break}. These take the form:
+\codeline{\%TC:break \textit{title}}
+A title (or name) may be given to identify the break point.
+
+If you define new section macros or macros you wish to cause a break point, these may be specified using the TC-instruction \code{breakmacro}:
+\codeline{\%TC:breakmacro \textit{macro} \textit{label}}
+This defines the given macro to cause a break point, and uses the given label to indicate the type of break (e.g. Section, Chapter, etc.).
+
+\subsection{Adding macro handling rules}
Adding your own macro handling rules is relatively simple. Although editing the script is possible, and not too difficult, this has the disadvantage that the modifications will be lost if updating to a new version of \TeXcount. A better and more flexible solution is to include instructions to \TeXcount{} in the \LaTeX{} documents, alternatively to make a definition file in which new macro handling rules are defined.
@@ -193,9 +269,13 @@ The instructions may be one of the following:
%
\begin{description}\def\option[#1]{\item[\bigcode{#1}]}
-\option[macro]Takes one parameter which is either an integer or a \code{[]}-enclosed array of integers (e.g. \code{[0,1,0]}). An integer value $n$ indicates that the $n$ first parameters to the macro should be ignored. An array of length $n$ indicates that the first $n$ parameters should be handled, and the numbers of the array specifies the parsing status (see below) with which they should be parsed. Giving the number $n$ as parameter is equivalent to giving an array of $n$ zeroes (\code{[0,\ldots,0]}) as zero is the parsing status for ignoring text.
+\option[macro]Define macro handling rule for the given macro. Takes one parameter which is either an integer or a \code{[]}-enclosed array of integers (e.g. \code{[0,1,0]}). An integer value $n$ indicates that the $n$ first parameters to the macro should be ignored. An array of length $n$ indicates that the first $n$ parameters should be handled, and the numbers of the array specifies the parsing status (see below) with which they should be parsed. Giving the number $n$ as parameter is equivalent to giving an array of $n$ zeroes (\code{[0,\ldots,0]}) as zero is the parsing status for ignoring text.
+
+\option[macroword]This defines the given macro to represent a certain number of words, where the number is given as the parameter.
+
+\option[header]Define macro to give a header. This is specified much as the macro rule. The added effect is that the header counter is increase by 1. Note, however, that you should specify a parameter array, otherwise none of the parameters will be parsed as header text. The parser status for header text is 2, so a standard header macro that uses the first parameter as header should be given the parameter \code{[2]}.
-\option[header]This is specified much as the macro rule. The added effect is that the header counter is increase by 1. Note, however, that you should specify a parameter array, otherwise none of the parameters will be parsed as header text. The parser status for header text is 2, so a standard header macro that uses the first parameter as header should be given the parameter \code{[2]}.
+\option[breakmacro]Specify that the given macro should cause a break point. Defining it as a header macro does not do this, nor is it required of a break point macro that it be a header (although I suppose in most cases of interest it will be).
\option[group]This specifies a begin-end group with the given name (no backslash). It takes two further parameters. The first parameter speficies the macro rule following \code{\bs{begin}\{\textit{name}\}}. The second parameter specifies the parser status with which the contents should be parsed: e.g. $1$ for text (default rule), $0$ to ignore, $-1$ to specify a float (table, group, etc.) for which text should not be counted but captions should, $6$ and $7$ for inline or displated math.
@@ -203,7 +283,7 @@ The instructions may be one of the following:
\option[preambleinclude]The preamble, i.e. text between \code{\bs{documentclass}} and \code{\bs{begin}\{document\}}, if the document contains one, should generally not be included in the word count. However, there may be definitions, e.g. \code{\bs{title}\{title text\}}, that should still be counted. In order to be able to include these special cases, there is a preambleinclude rule in which one may speficy handling rules for macros within the preamble. Again, the rule is speficied like the \code{macro} rules, but since the default is to ignore text the only relevant rules to be specified require an array.
-\option[fileinclude]By default, \TeXcount{} does not automatically add files included in the document using \code{\bs{input}} or \code{\bs{include}}, but inclusion may be turned on by using the option \code{-inc}. If other macros are used to include files, these may be specifed by adding fileinclude rules for these macros. The specification takes one parameter: 1 if filetype \code{.tex} should be added if the file is without a filetype, 0 if it should not.
+\option[fileinclude]By default, \TeXcount{} does not automatically add files included in the document using \code{\bs{input}} or \code{\bs{include}}, but inclusion may be turned on by using the option \code{-inc}. If other macros are used to include files, these may be specifed by adding fileinclude rules for these macros. The specification takes one parameter: 0 if the file name should be used as provided, 1 if file type \code{.tex} should be added to files without a file type, and 2 if the file tyle \code{.tex} should always be added.
\end{description}