From b3969456a6bca6912da7f406ee065c65c704f6e1 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Sat, 6 Aug 2022 03:01:14 +0000
Subject: CTAN sync 202208060301

---
 support/texlogsieve/texlogsieve.tex | 64 +++++++++++++++++++++++++------------
 1 file changed, 44 insertions(+), 20 deletions(-)

(limited to 'support/texlogsieve/texlogsieve.tex')

diff --git a/support/texlogsieve/texlogsieve.tex b/support/texlogsieve/texlogsieve.tex
index 6270e27ffe..40323ceb2a 100644
--- a/support/texlogsieve/texlogsieve.tex
+++ b/support/texlogsieve/texlogsieve.tex
@@ -37,6 +37,8 @@
 \usepackage{microtype}
 \usepackage{metalogo}
 
+\hyphenation{tex-log-sieve tex-log-sieverc}
+
 \RecordChanges
 
 \changes{1.0.0-beta-1}{2021/12/16}{First public prerelease}
@@ -84,12 +86,18 @@
 \changes{1.2.0}{2022/07/21}{Summary messages use singular and plural
                             for pages and files}
 \changes{1.2.0}{2022/07/21}{Add unused labels to summary}
+\changes{1.3.0}{2022/08/05}{Sort line numbers in summary}
+\changes{1.3.0}{2022/08/05}{Indicate whether there were parse errors
+                            in summary}
+\changes{1.3.0}{2022/08/05}{Add line number to parse error messages}
+\changes{1.3.0}{2022/08/05}{Add \texttt{-\/-verbose} option}
+\changes{1.3.0}{2022/08/05}{Search for a config file in the user's homedir too}
 
 \begin{document}
 
 \title{\textsf{texlogsieve}:\thanks{This document
-corresponds to \textsf{texlogsieve}~1.2.0,
-dated~2022-07-21.}\\[.3\baselineskip]
+corresponds to \textsf{texlogsieve}~1.3.0,
+dated~2022-08-05.}\\[.3\baselineskip]
 {\normalsize(yet another program to)\\[-.6\baselineskip]}
 {\large filter and summarize \LaTeX\ log files}
 }
@@ -138,12 +146,12 @@ spirit to tools such as \href{https://ctan.org/pkg/texfot}{\texttt{texfot}},
 \href{https://gricad-gitlab.univ-grenoble-alpes.fr/labbeju/latex-packages}
 {\texttt{texlogfilter}}, and others.
 
-Note that it does not try to do anything smart about error messages
-(but it shows a warning in the summary if one is detected); if there
-is an error, you probably want to take a look directly at the log file
-anyway. It also cannot detect if \LaTeX{} stops for user input, so
-you should \textbf{really} run \LaTeX\ in \texttt{nonstopmode} when
-\texttt{texlogsieve} is reading from a pipe.
+Note that it does not try to do anything smart about error messages (but
+it shows a warning in the summary if one is detected; check the ``Tips''
+section regarding this); if there is an error, you probably want to take
+a look directly at the log file anyway. It also cannot detect if \LaTeX{}
+stops for user input, so you should \textbf{really} run \LaTeX\ in
+\texttt{nonstopmode} when \texttt{texlogsieve} is reading from a pipe.
 
 \texttt{texlogsieve} \textbf{must} be run from the same directory as
 \verb/[pdf|lua|xe]latex/, because it searches for the files used during
@@ -223,13 +231,14 @@ options to add it to the list of messages known to the program.
 \section{Configuration File}
 
 \texttt{texlogsieve} always searches automatically for the (optional)
-\texttt{texlogsieverc} configuration file in the \TeX\ path (i.e., it
-searches using \texttt{Kpathsea}). In the default configuration, the
-current directory is in the search path, so adding a config file with that
-name to the project directory is enough to make it work. Options in the
-config file are exactly the same as the long command-line options described
-below, but without the preceding ``\texttt{-\/-}'' characters. Lines
-starting with a ``\#'' sign are comments. An example configuration file:
+\texttt{texlogsieverc} configuration file in \texttt{\$TEXINPUTS} (i.e.,
+it searches using \texttt{Kpathsea}). In the default configuration, the
+current directory is in \texttt{\$TEXINPUTS}, so adding a config file
+with that name to the project directory is enough to make it work.
+Options in the config file are exactly the same as the long command-line
+options described below, but without the preceding ``\texttt{-\/-}''
+characters. Lines starting with a ``\#'' sign are comments. An example
+configuration file:
 
 \begin{quote}
 \begin{verbatim}
@@ -246,6 +255,16 @@ silence-files = *.sty
 \end{verbatim}
 \end{quote}
 
+If you'd like to also have a generic configuration file for all your projects
+(a good idea), put it at \texttt{\$HOME/.texlogsieverc} in unix-like systems;
+in Windows, put it either at \texttt{\%LOCALAPPDATA\%\textbackslash{}%
+texlogsieverc} (\texttt{C:\textbackslash{}Users\textbackslash{}<username>%
+\textbackslash{}AppData\textbackslash{}Local}) or \texttt{\%APPDATA\%%
+\textbackslash{}texlogsieverc} (\texttt{C:\textbackslash{}Documents and
+Settings\textbackslash{}<username>\textbackslash{}Application Data} or
+\texttt{C:\textbackslash{}Users\textbackslash{}<username>\textbackslash{}%
+AppData\textbackslash{}Roaming}).
+
 \section{Options}
 
 \begin{description}
@@ -426,8 +445,14 @@ the severity level of many different messages.
 
 \begin{description}
 \item[\texttt{-c CFGFILE}, \texttt{-\/-config-file=CFGFILE}]~\\
-Read options from the given configuration file in addition to
-\texttt{texlogsieverc}.
+Read options from the given configuration file in addition to the
+default config files (see the ``Configuration File'' section).
+\end{description}
+
+\begin{description}
+\item[\texttt{-v}, \texttt{-\/-verbose}]~\\
+Print the list of configuration files read and a short summary of the
+most important active configuration options.
 \end{description}
 
 \begin{description}
@@ -449,9 +474,8 @@ Print program version.
   \texttt{silence-[something]} and \texttt{set-to-level-[something]} options:
   You will get reasonably quiet output but still be notified of problems. Since
   you probably always use essentially the same set of packages and classes,
-  the file will be useable in other \LaTeX\ projects too (you may even put
-  it somewhere in your \TeX\ path, like \texttt{\$HOME/texmf/tex/latex} on
-  Unix-like systems).
+  the file will be useable in other \LaTeX\ projects too; just put it in one
+  of the places discussed in the ``Configuration File'' section.
 
   \item \texttt{texlogsieve} has no smarts to deal with error messages, but
   you may use options \texttt{-l unknown -\/-no-page-delay -\/-no-summary
-- 
cgit v1.2.3

