summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/texcount/QuickReference.tex
blob: e6aeaf3eee846dbf6c0e899816ed059fee652a8b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
\documentclass{article}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{a4wide}
\usepackage{times}

\include{macros}


\title{\TeXcount{}\footnote{Copyright (2008-2009) of Einar Andreas Rødland, distributed
under the \LaTeX{} Project Public Licence (LPPL).}~
Quick Reference Guide\\
Version 2.2
}

\begin{document}

\maketitle

\section{Command line options}

Syntax for running \TeXcount{}:
\codeline{texcount \textit{[options] [files]}}
where \code{texcount} refers to the TeXcount Perl-script, and the options may be amongst the following:
\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[-q, -quiet]Quiet mode, does not print error messages. Use is
discouraged, but it may be useful when piping the output into another
application.

\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[-utf8, -unicode]Turn on Unicode (UTF-8) support.

\option[-ch, -chinese, -zhongwen]Turn on Chinese mode in which Chinese
characters are counted. Switches on UTF-8 mode.

\option[-jp, -japanese]Turn on Japanese mode in which Japanese
characters (kanji and kana) are counted. Switches on UTF-8 mode.

\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}


\section{\TeXcount{} instructions embedded in \LaTeX{} documents}

Instructions to \TeXcount{} can be given from within the
\LaTeX{} document using \LaTeX{} comments on the format
\codeline{\%TC:\textit{instruction [name] parameters}}
where the name is use for instructions providing macro handling rules to give the name of the macro or group for which the rule applies.

\begin{description}\def\option#1{\item[\bigcode{#1}]}

\option{ignore}Indicates start of a region to be ignored. End region with the TC-instruction \code{endignore}.

\option{break \textit{title}}Break point which initiates a new subcount. The title is used to identify the following region in the summary output.

\end{description}

\subsection{Adding macro handling rules}

The macro handling rules all take the format
\codeline{\%TC:\textit{instruction name parameters}}
where the name indicates the macro (with backslash) or group name for which the rule applies.

\begin{description}\def\option[#1]{\item[\bigcode{#1}]}

\option[macro]Define macro handling rule for specified 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[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.

\option[floatinclude]This may be used to specify macros which should be counted when within float groups. The handling rules are spefified as for \code{macro}, but like with \code{header} an array parameter should be provided and parameters that should be counted as text in floats should be specified by parsing status 3. Thus, a macro that takes one parameter which should be counted as float/caption text should take the parameter \code{[3]}.

\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: 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}

\end{document}