summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-11-03 22:55:12 +0000
committerKarl Berry <karl@freefriends.org>2019-11-03 22:55:12 +0000
commitde291447213d023596118b9a20bded5a0d2a7a76 (patch)
tree5be181395c6af7d504d8583b8c26aebae86429f3 /Master/texmf-dist/doc/support
parent90a58e00fcc8f175df8ffcb7aa5f326b28675905 (diff)
chklref (3nov19)
git-svn-id: svn://tug.org/texlive/trunk@52631 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/chklref/Makefile.doc13
-rw-r--r--Master/texmf-dist/doc/support/chklref/README.md51
-rw-r--r--Master/texmf-dist/doc/support/chklref/VERSION1
-rw-r--r--Master/texmf-dist/doc/support/chklref/chklref.pdfbin0 -> 298764 bytes
-rw-r--r--Master/texmf-dist/doc/support/chklref/chklref.tex136
-rwxr-xr-xMaster/texmf-dist/doc/support/chklref/release.sh48
6 files changed, 249 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/chklref/Makefile.doc b/Master/texmf-dist/doc/support/chklref/Makefile.doc
new file mode 100644
index 00000000000..4faf33d8917
--- /dev/null
+++ b/Master/texmf-dist/doc/support/chklref/Makefile.doc
@@ -0,0 +1,13 @@
+.PHONY: all clean cleanall
+
+all: chklref.pdf clean
+
+chklref.pdf: chklref.tex
+ pdflatex chklref.tex
+ pdflatex chklref.tex
+
+clean:
+ rm -f chklref.log chklref.aux chklref.out chklref.fls chklref.fdb_latexmk chklref.synctex.gz
+
+cleanall: clean
+ rm -f chklref.pdf
diff --git a/Master/texmf-dist/doc/support/chklref/README.md b/Master/texmf-dist/doc/support/chklref/README.md
new file mode 100644
index 00000000000..a39c0948f15
--- /dev/null
+++ b/Master/texmf-dist/doc/support/chklref/README.md
@@ -0,0 +1,51 @@
+# Installation
+
+## System wide installation
+
+### Installation into the TeX structure
+
+This package follows the TDS[1]
+
+- put the TeX package `chklref.sty` into `$(texmf_prefix)/tex/latex/chklref`
+- put the manual `chklref.pdf` into `$(texmf_prefix)/doc/latex/chklref`
+- put the Perl parser `chklref.pl` into `$(texmf_prefix)/scripts/chklref`
+
+Note that you will also need to make a link or copy `chklref.pl` to a location in your `PATH`. On Unix systems, you may need to set the script as executable.
+
+Depending on your OS and TeX distribution, the `TEXMF` directory `texmf_prefix` can have different values
+
+- **Single account installation under Linux** `~/texmf`.
+- **Single account installation under Mac OS X** `~/texmf` or `$HOME/Library/texmf`.
+- **System wide installation under Linux** `/usr/share/texmf-local/`.
+- **System wide installation under Mac OS X** `/usr/local/texlive/texmf-local/`.
+- **Under Windows** something like `C:\localtexmf\`. Check in your distribution settings.
+
+**You may need to run `texhash` to update your TeX Directory Structure.**
+
+The fastest way to carry out the installation is to use the file `chklref.tds.zip` included in the numbered releases (not available inside the git repository). You just have to unzip it inside the proper `texmf_prefix`. Alternatively, you can copy the files by hand. On Unix systems, you may need to set the script as executable.
+
+#### Local installation
+
+Instead of carrying out a system wide installation, you can simply copy the package file `chklref.sty` next to your main LaTeX file and put the Perl script `chklref.pl` next to it or in anywhere in your `PATH`. On Unix systems, you may need to set the script as executable.
+
+## Requirements
+
+The `chklref` tool is mainly written in TeX with a small Perl script to parse the output generated by the TeX package. It should be working with any standard Perl installation.
+
+The Perl script calls a LaTeX compiler to extract labels related information.
+
+## Usage
+
+You typically just run: `perl chklref.pl file.tex`
+
+The full calling syntax is `perl chklref.pl [options] file.tex`, where `options` can be
+
+- `--tex <compiler>`, `-t`: Specify the TeX compiler to be used. Default is `pdflatex`.
+- `--tex-options`: List of options to pass to the TeX compiler. Note that we always add `-interaction nonstopmode` on top of these options.
+- `--debug`, `-d`: Run in debug mode. Do not clean the generated `.chk` file.
+- `--quiet`, `-q`: Run in quiet mode. Do not print the output of the TeX compiler.
+- `--parse-only`: Do not run the LaTeX compiler but use the already existing `.chk` file. When this option is passed, the following other options are meaningless: `--tex`, `--tex-options`, `--quiet`, `--debug`.
+- `--version`, `-v`: Print the version of this script.
+- `--help,h`: Print this help.
+
+[1] : TeX Directory Structure http://www.tug.org/twg/tds/
diff --git a/Master/texmf-dist/doc/support/chklref/VERSION b/Master/texmf-dist/doc/support/chklref/VERSION
new file mode 100644
index 00000000000..cb2b00e4f7a
--- /dev/null
+++ b/Master/texmf-dist/doc/support/chklref/VERSION
@@ -0,0 +1 @@
+3.0.1
diff --git a/Master/texmf-dist/doc/support/chklref/chklref.pdf b/Master/texmf-dist/doc/support/chklref/chklref.pdf
new file mode 100644
index 00000000000..df3d7637c11
--- /dev/null
+++ b/Master/texmf-dist/doc/support/chklref/chklref.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/chklref/chklref.tex b/Master/texmf-dist/doc/support/chklref/chklref.tex
new file mode 100644
index 00000000000..4a9b0baf8d6
--- /dev/null
+++ b/Master/texmf-dist/doc/support/chklref/chklref.tex
@@ -0,0 +1,136 @@
+\documentclass[a4paper,11pt,twoside]{article}
+\usepackage{a4wide}
+\usepackage{latexsym,t1enc,lmodern,url}
+\usepackage{amssymb, amsmath,indentfirst}
+\usepackage[utf8]{inputenc}
+\usepackage[english]{babel}
+
+%%--------------------------------------------
+\hbadness=10000
+\emergencystretch=\hsize
+\tolerance=9999
+\textheight=9.0in
+%%--------------------------------------------
+
+\def\chk{{\it chklref}}
+
+\title{Check \LaTeX\ references: chklref \\
+Version \input{../VERSION}}
+\date{\today}
+\author{Jérôme Lelong}
+
+\begin{document}
+\maketitle
+
+\begin{abstract} Every \LaTeX\ user has once dreamt of cleaning its \TeX\ file of any useless labels right, for instance before submitting an article. The purpose of \chk\ is precisely to help to do this.
+\end{abstract}
+
+\section{What {\it chklref} can do for a \LaTeX\ user?}
+
+While writing a \LaTeX document, it is quite common to add labels that will reveal unused in the end, this is especially true for equations or any other mathematical environments. It would be quite convenient to wipe out those labels from the final version of the document. \chk\ has been designed to help \LaTeX\ users do so.
+
+
+\chk\ parses the \LaTeX\ file to detect labels that do not have any matching reference. At the end of the program, a summary is printed with the list of labels to be removed. Obviously, this search is performed in the whole document and not only within mathematical environments. Nonetheless, there is something specifically dedicated to environments that have a star version: it looks for the non star environments not containing any label.
+
+For instance, consider you a have a \LaTeX\ file with the following piece of code
+\begin{verbatim}
+\begin{equation}
+ x^2 + x + 1 = 0
+\end{equation}
+\end{verbatim}
+\chk\ will advise you to consider using \verb!equation*! instead of \verb!equation! in order to remove the unneeded number appearing next to the equation.
+
+Star environments with labels are also tracked because with most \LaTeX\ distributions it does not even raise a warning. However if you ever refer to this label, the printed number will most likely be nonsense.
+
+The summary printed at the end of the program contains two sections (see Figure~\ref{fig:output}): the first one is about labels in star environments and the second one is about unneeded labels. Each of these output lines begins with a line number referring to the parsed \LaTeX\ file. Then, the action to take is printed: ``remove label'' or ``use a starred environment''. In the case of a ``remove label'' message, the label to be removed is also printed to avoid any possible confusion.
+
+\begin{figure}[!ht]
+ \centering
+\begin{verbatim}
+************************************
+** Labels in starred environments **
+************************************
+line 264 : remove label eq:quantified
+line 200 : consider using a STAR environment
+
+*******************
+** Unused Labels **
+*******************
+line 313 : remove label eq:prog_dyn_prix
+\end{verbatim}
+ \caption{Program output}
+ \label{fig:output}
+\end{figure}
+
+Since version 2.5, bibliography entries have also been checked to detect if some entries are not explicitly cited in the text, see Figure~\ref{fig:output}. In this case, a ``remove bibitem'' message is printed.
+\begin{figure}[!ht]
+ \centering
+\begin{verbatim}
+**********************************
+** Non cited Bibliography entries **
+**********************************
+remove bibitem : premia
+\end{verbatim}
+ \caption{Bibliography analysis}
+ \label{fig:biblio}
+\end{figure}
+
+
+\section{Usage}
+
+There are two ways of using the package.
+
+\begin{enumerate}
+ \item Directly calling \verb!perl chklref.pl file.tex!.
+ \item Adding \verb!\usepackage{chklref}! to your main \LaTeX\ file and compiling it normally. This will create a file with extension \verb!.chk!, which can then be parsed by the Perl script:
+\begin{verbatim}
+ perl chklref.pl --parse-only file.tex
+\end{verbatim}
+ Note that you need to pass the \verb!.tex! file to the parser not the \verb!.chk! file.
+\end{enumerate}
+
+
+\section{Installation}
+
+\subsection{Installation into the \TeX\ structure}
+
+This package follows the TDS\footnote{TeX Directory Structure
+ \url{http://www.tug.org/twg/tds/}}:
+\begin{itemize}
+ \item put the \TeX\ package \verb!chklref.sty! into \verb!$(texmf_prefix)/tex/latex/chklref!
+ \item put the manual \verb!chklref.pdf! into \verb!$(texmf_prefix)/doc/latex/chklref!
+ \item put the Perl parser \verb!chklref.pl! into \verb!$(texmf_prefix)/scripts/chklref!
+\end{itemize}
+Note that you will also need to make a link or copy \verb!chklref.pl! to a location in your \texttt{PATH}. On Unix systems, you may need to set the script executable. \\
+
+Depending on your OS and \TeX\ distribution, the TEXMF directory \verb!texmf_prefix! can have different values
+\begin{description}
+ \item[Single account installation under Linux] \verb!~/texmf!.
+ \item[Single account installation under Mac OS X] \verb!~/texmf! or \verb!$HOME/Library/texmf!.
+ \item[System wide installation under Linux] \verb!/usr/share/texmf-local/!.
+ \item[System wide installation under Mac OS X] \verb!/usr/local/texlive/texmf-local/!.
+ \item[Under Windows] something like \verb!C:\localtexmf\!. Check in your distribution settings.
+\end{description}
+
+\noindent \textbf{You may need to run \texttt{texhash} to update your \TeX\ Directory Structure.}
+
+The fastest way to carry out the installation is to use the file \verb!chklref.tds.zip! included in the numbered releases (not available inside the git repository). You just have to unzip it inside the proper \verb!texmf_prefix!. Alternatively, you can copy the files by hand. On Unix systems, you may need to set the script as executable.
+
+\subsection{Local installation}
+
+Instead of carrying out a system wide installation, you can simply copy the package file \verb!chklref.sty! next to your main \LaTeX\ file and put the Perl script \verb!chklref.pl! next to it or in anywhere in your \texttt{PATH}. On Unix systems, you may need to set the script as executable.
+
+
+\section{Requirements}
+
+The \chk\ tool is written mainly in \TeX\ with a small Perl script to parse the output generated by the \TeX\ package. It should be working with any standard Perl installation. \\
+
+The Perl script calls a LaTeX compiler to extract labels related information.
+
+\section{Source code}
+
+The source code is available from GitHub \url{https://github.com/jlelong/chklref}. \\
+
+It is distributed under the GPL licence version 3 or any later version in the hope it will be useful but without any warranty. Should you find a bug in chklref, create an issue at \url{https://github.com/jlelong/chklref/issues} and please provide minimal a \LaTeX\ file to reproduce the problem.
+
+\end{document}
diff --git a/Master/texmf-dist/doc/support/chklref/release.sh b/Master/texmf-dist/doc/support/chklref/release.sh
new file mode 100755
index 00000000000..3455541c971
--- /dev/null
+++ b/Master/texmf-dist/doc/support/chklref/release.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# This script creates a new releas of chklref
+CWD="$(pwd)/$0"
+CHKLREFGIT=$(dirname $"CWD")
+DATE=$(date +%Y%m%d)
+# Local temporary directory
+LOCAL_TMPDIR="$HOME/tmp/chklref-$DATE"
+CHKLREF_DIR="$LOCAL_TMPDIR/chklref"
+
+# Perform git archive
+git_archive() {
+ cwd=$(pwd)
+ [[ -d "$LOCAL_TMPDIR" ]] && rm -rf "$LOCAL_TMPDIR"
+ mkdir -p "$CHKLREF_DIR"
+ cd "$CHKLREFGIT"
+ git archive --format=tar master | tar -x -C "$CHKLREF_DIR"
+ cd "$cwd"
+}
+
+compile_doc() {
+ cwd=$(pwd)
+ cd "$CHKLREF_DIR/doc"
+ make
+ cd "$cwd"
+}
+
+create_tds() {
+ cwd=$(pwd)
+ mkdir -p "$CHKLREF_DIR/chklref.tds"
+ cd "$CHKLREF_DIR/chklref.tds"
+ mkdir -p tex/latex/chklref
+ mkdir -p doc/latex/chklref
+ mkdir -p scripts/chklref
+ cp ../chklref.sty tex/latex/chklref
+ cp ../doc/chklref.{tex,pdf} doc/latex/chklref
+ cp ../README.md doc/latex/chklref
+ cp ../chklref.pl scripts/chklref
+ cd ..
+ zip -r chklref.tds.zip chklref.tds
+ rm -rf chklref.tds
+ cd "$cwd"
+}
+
+git_archive
+compile_doc
+create_tds
+zip -r "$CHKLREF_DIR.zip" "$CHKLREF_DIR" \ No newline at end of file