### TeXcount option file example with counting options, macro rules, and output template

Source: https://github.com/einarandreas/texcount/blob/master/Doc/TeXcount.tex

Example option file for TeXcount. It sets counting options (-sum=1,1,1, -sub=section, -inc), defines macro rules with %macro, %envir, %macroword, and %subst, and specifies an output template. Lines starting with # are comments, and a backslash at the start of a line continues the previous line.

```latex
### Options to use with TeXcount

# Counting options
-sum=1,1,1
-sub=section
-inc

# Macro rules
%macro \url 1
%envir sourcecode 0 0
%macroword \TeXcount 1

# Path used in file inclusion (\chapterpath filename)
%subst \chapterpath chap/

# Output template
-template=
   \::: {title} :::\n
   \Words: {sum}\n
   \Formulae: {6} + {7}\n
   \{5?Number of floats: {5}\n?5}
   \{SUB? - {sum} words in {title}\n?SUB}
```

--------------------------------

### Example: calling read_binary

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/cmd-io.md

Example usage of read_binary; the caller must handle undef.

```perl
my $bytes = read_binary('chapter1.tex');   # undef handled by caller
```

--------------------------------

### Example: calling TeXfile and handling undef

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/cmd-io.md

Example usage of TeXfile: checks for undef return and then calls parse($tex).

```perl
my $tex = TeXfile('paper.tex');
if (!defined $tex) { die "unreadable\n"; }   # caller must handle undef
parse($tex);
```

--------------------------------

### add_keys_to_hash usage examples

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/rules.md

Demonstrates how to use add_keys_to_hash with both list and scalar values.

```perl
my %TeXmacro;
add_keys_to_hash(\%TeXmacro,['[','text'], '\item');           # list value
add_keys_to_hash(\%TeXmacro,1, '\cite','\ref','\label');      # scalar value
```

--------------------------------

### get_sum_count usage examples

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/counts.md

Examples showing the definition of sum weights and the invocation of get_sum_count.

```perl
@sumweights=(0,1,1,1,0,0,1,1);   # -sum default
my $s = get_sum_count($total);    # text + headers + captions + math counts
```

--------------------------------

### Usage example with error path

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/html.md

Demonstrates a non-trivial option usage where a missing template file triggers an error.

```perl
# Non-trivial option use: template with placeholder, plus error check
$htmlstyle = $HTML_FULL;      # -html
$HTMLfile  = 'page.tmpl';     # must contain <!-- TeXcount -->, ${texcount} or </body>
Apply_Options();              # reports 'HTML template file not found: page.tmpl'
                              # via error($Main,...) if unreadable — parse continues
print_count($count);
Close_Output();               # adds tail, closes STDOUT
```

--------------------------------

### Fetching help text and options format

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/help.md

Example usage of StringData and StringDatum to fetch the ShortHelp lines and the OptionsFormat layout line.

```perl
my $lines = StringData('ShortHelp');   # lines of the -h text
my $fmt   = StringDatum('OptionsFormat');
```

--------------------------------

### set_verbosity_options usage examples

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/options.md

Examples demonstrating how to set base verbosity levels and modify style groups using the set_verbosity_options function.

```perl
set_verbosity_options('4');        # level 4 (v4: includes states)
set_verbosity_options('3-States'); # level 3, turn off state logging
set_verbosity_options('+Sums');    # keep current base, add sum group
```

--------------------------------

### Realistic template usage example

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/output.md

Demonstrates how to define an output template and invoke print_count to render the count object.

```perl
# Realistic template usage
$outputtemplate = '{TITLE}: {w} words + {hw} header words = {SUM}{SUB? ({SUB} subcounts)?SUB}';
print_count($count);   # prints via _print_count_template
```

--------------------------------

### note() usage example

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/error-reporting.md

Example call to note() that prints a note with the default prefix '%NOTE: ' at verbosity level 1 or higher. The text contains a template token '{header}' that will be expanded.

```perl
note($tex, 1, 'Section {header} headers so far');   # %NOTE: at -v1+
```

--------------------------------

### TeXcode usage examples - building TeX objects

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/texcode.md

Two usage examples: the first builds a TeX object from a UTF-8 byte string with a filename; the second shows a title override and error handling by capturing $tex->{'errorcount'} after parsing.

```perl
# Basic: build a TeX object from a UTF-8 byte string
my $tex = TeXcode(encode('utf8', '\section{Intro} Hello world.'), 'paper.tex');

# With title override and error handling in mind: decoding errors are
# reported against this object, so capture $tex->{'errorcount'} after parsing.
my $tex = TeXcode($bytes, 'main.tex', 'My Document');
parse($tex);
print "errors: ", $tex->{'errorcount'}, "\n";
```

--------------------------------

### html_head usage with template

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/html.md

Example configuration for using a template file with html_head.

```perl
# With a template file containing '<!-- TeXcount -->':
$HTMLfile  = 'wrapper.html';
$CSSfile   = 'style.css';
$showVersion = 1;
Apply_Options();   # calls html_head() when $htmlstyle==$HTML_FULL
```

--------------------------------

### apply_include_bibliography subroutine

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/options.md

Installs the pseudo-package %incbib rules to enable bibliography inclusion.

```perl
sub apply_include_bibliography {
  include_package('%incbib');
}
```

--------------------------------

### convert_hash usage examples

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/rules.md

Shows how convert_hash is used to transform rule strings and keys into state or counter constants.

```perl
convert_hash(\%TeXpreamble,\&keyarray_to_state);
convert_hash(\%TeXmacro,\&keyarray_to_state);
convert_hash(\%TeXmacrocount,\&keyarray_to_cnt);
convert_hash(\%TeXenvir,\&key_to_state);
```

--------------------------------

### Usage example for new_count

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/counts.md

Demonstrates initializing a new count object and interacting with counter values.

```perl
my $c = new_count('Total');
inc_count($tex, $CNT_WORDS_TEXT, 3);   # increment the current subcount
print get_count($c, $CNT_WORDS_TEXT);  # 0 — $c is separate from $tex->{'subcount'}
```

--------------------------------

### include_package usage examples (Perl)

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/rules.md

Shows typical calls to include_package: adding rules for 'amsmath', the internal pseudo-package '%incbib' for bibliography, and 'class%article' which is invoked automatically from \documentclass{article}.

```perl
include_package('amsmath');      # adds aligned/alignat/matrix/... rules
include_package('%incbib');      # internal pseudo-package for bibliography
include_package('class%article'); # invoked automatically from \documentclass{article}
```

--------------------------------

### Basic usage: full parse of a document

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/parsing.md

Example demonstrating a full parse of a LaTeX document and retrieving the word count.

```perl
# Basic usage: full parse of a document
my $tex = TeXcode(encode('utf8', <<'LATEX'), 'doc.tex');
\documentclass{article}
\begin{document}
\section{Introduction}
Counting words is easy.
\[ x^2 \]
\end{document}
LATEX
parse($tex);
my $count = next_subcount($tex);
print get_count($count, $CNT_WORDS_TEXT), " text words\n";
```

--------------------------------

### %TC:macro rules with parameter rules (\refnote, \newsection, \NB)

Source: https://github.com/einarandreas/texcount/blob/master/Doc/TeXcount.tex

Three examples of %TC:macro instructions that specify parsed parameters using a list of rules (e.g., 'text,othertext', 'header,ignore') or an integer to ignore that many parameters, each followed by its corresponding \newcommand definition.

```latex
%TC:macro \refnote[text,othertext]
\newcommand\refnote[2]{\textit{#1}\footnote{#2}}

%TC:macro \newsection [header,ignore]
\newcommand\newsection[2]{\section{#1}\label{sec:#2}}

%TC:macro \NB 1
\newcommand\NB[1]{\marginpar{#1}}

```

--------------------------------

### assert() usage example - check for %TC:newcounter key

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/error-reporting.md

Example call to assert() that checks if the line starts with a word, reporting an error if not, and returns from the current subroutine on failure.

```perl
assert($line =~ s/^(\w+)//, $tex, 'Expected %TC:newcounter key')
  || return;
```

--------------------------------

### inc_count usage examples

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/counts.md

Examples of calling inc_count to increment by one or by a specific value.

```perl
inc_count($tex, $CNT_COUNT_INLINEMATH);   # one inline equation
inc_count($tex, $CNT_WORDS_TEXT, 5);      # five text words at once
```

--------------------------------

### Command-line MAIN entry point (Perl/2_cmd_main.perl:21)

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/entry-points.md

Runs the main routine for the command-line executable. It initializes, checks arguments, parses files, applies options, and processes files or reports an error if none are specified. Exits after MAIN.

```perl
MAIN(@ARGV);
exit; # Just to make sure it ends here...

```

--------------------------------

### CGI MAIN entry point (Perl/2_cgi_main.perl:20)

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/entry-points.md

Runs the main routine for the CGI executable. It calls MAIN with no arguments and exits.

```perl
MAIN();
exit; # Just to make sure it ends here...

```

--------------------------------

### TeXcode($bincode, [$file], [$title])

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/texcode.md

Creates a new TeX object from raw LaTeX code. It initializes the object, sets the code, and processes the first paragraph.

```APIDOC
## TeXcode($bincode, [$file], [$title])

### Description
Creates a new TeX object from raw LaTeX code. It initializes the object, sets the code, and processes the first paragraph.

### Method
Function call

### Endpoint
Perl subroutine: TeXcode($bincode, [$file], [$title])

### Parameters
#### Positional Parameters
- **$bincode** (string) - Required - Raw (still byte-encoded) LaTeX code; decoded inside.
- **$file** (string) - Optional - File path/name; used for filename/dirpath/title. Default: undef.
- **$title** (string) - Optional - Title of the countsum count object. Default: 'File: '.$file (or undef).

### Returns
- **TeX object** (hash-ref) - New TeX object with texcode set, countsum/subcount fresh count objects, CNT_FILE already incremented, eof=0.

### Behaviour
- _TeXcode_blank builds the object.
- _TeXcode_setcode prepares the code.
- more_texcode moves the first paragraph into $tex->{'line'}.

### Usage Example
```perl
my $tex = TeXcode(encode('utf8', '\section{Intro} Hello world.'), 'paper.tex');

my $tex = TeXcode($bytes, 'main.tex', 'My Document');
parse($tex);
print "errors: ", $tex->{'errorcount'}, "\n";
```
```

--------------------------------

### include_file dummy implementation

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/cgi.md

Dummy implementation that always reports an error, as file inclusion is intentionally unavailable in the web service. Takes the same parameters as the CMD version but the third argument is the file name.

```perl
# Dummy implementation for adding included file to parsing list
sub include_file {
  my ($tex,$state,$file)=@_;
  error($tex,'Cannot include file when using web service');
}
```

--------------------------------

### tc_macro_param_option usage examples

Source: https://github.com/einarandreas/texcount/blob/master/_autodocs/api-reference/options.md

Demonstrates how to invoke tc_macro_param_option for macro definitions and environment settings.

```perl
# %TC:macro \foo [text,ignore]   → param='[text,ignore]'
tc_macro_param_option($tex,'macro','\foo','[text,ignore]',undef);
# %TC:envir myenv [ignore] text  → $option='text' is the contents state
tc_macro_param_option($tex,'envir','myenv','[ignore]','text');
```