From 84a5593d3fb9d03aac5677678bcc4c92e8c9a9c4 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 27 May 2022 03:01:31 +0000
Subject: CTAN sync 202205270301

---
 support/pkgcheck/docs/pkgcheck.tex | 181 ++++++++++++++++++++++++++-----------
 1 file changed, 127 insertions(+), 54 deletions(-)

(limited to 'support/pkgcheck/docs/pkgcheck.tex')

diff --git a/support/pkgcheck/docs/pkgcheck.tex b/support/pkgcheck/docs/pkgcheck.tex
index ab96cc390a..a41a7db1ad 100644
--- a/support/pkgcheck/docs/pkgcheck.tex
+++ b/support/pkgcheck/docs/pkgcheck.tex
@@ -42,7 +42,7 @@
 %  \pdfinfo{
 %    /Author (Manfred Lotz)
 %    /Title  pkgcheck Utility
-% } 
+% }
 
 %\title{pkgcheck utility}
 \include{title}
@@ -59,6 +59,8 @@
 \end{abstract}
 
 
+\newpage
+
 \section{Introduction}
 
 Uploaded packages to CTAN must satisfy various requirements in order to get
@@ -67,7 +69,7 @@ installed on CTAN.
 A first introduction is given here \url{https://ctan.org/help/upload-pkg}.
 
 Even more details are to be found in the excellent CTAN-upload addendum
-\url{https://ctan.org/file/help/ctan/CTAN-upload-addendum} written by Petra Rübe-Pugliese. 
+\url{https://ctan.org/file/help/ctan/CTAN-upload-addendum} written by Petra Rübe-Pugliese.
 
 The \pkgcheck utility which runs on Linux systems only checks those requirements
 which can be checked by a program.
@@ -89,22 +91,14 @@ information for a certain error.
 The \pkgcheck is a 64-bit statically linked binary, and should work an any 64-bit Linux.
 It is available in the repository in directory \verb|bin/|.
 
-Currently, the only external programs required are:
-\begin{itemize}
-\item \verb|/usr/bin/unzip|
-
-Used only, when a TDS zip archive will be extracted.
+Currently, the only external program required is \verb|/usr/bin/pdfinfo|. It is
+used when a PDF document will be checked.
 
-\item \verb|/usr/bin/pdfinfo|
-
-Used only, when a PDF document will be checked. 
-  
-\end{itemize}
 
 \section{Installation}
 
-Copy the binary from \verb|bin/pkgcheck| to a suitable location on your hard disk, and 
-(recommended) make sure the directory is in the \verb|PATH| or call \verb|pkgcheck| using an 
+Copy the binary from \verb|bin/pkgcheck| to a suitable location on your hard disk, and
+(recommended) make sure the directory is in the \verb|PATH| or call \verb|pkgcheck| using an
 absolute path name.
 
 \section{Utility usage}
@@ -116,32 +110,109 @@ Running \verb|pkgcheck --help| shows the available command line options.
 
 Here a sample output:
 
+{\small
+
 \begin{verbatim}
-pkgcheck 1.0.0
+pkgcheck 3.0.0
 Manfred Lotz <manfred@ctan.org>
-A checker for uploaded packages to CTAN.
+Command-line tool to check packages uploaded to CTAN.
 
 USAGE:
-    pkgcheck [FLAGS] [OPTIONS]
-
-FLAGS:
-    -L, --correct-crlf         Correct CRLF line endings
-    -C, --correct-perms        Correct permissions
-        --explain-all          Explains all error or warning messages
-    -h, --help                 Prints help information
-    -I, --ignore-dupes         Ignore dupes
-        --no-colors            Don't display messages in color
-        --show-temp-endings    Show file endings for temporary files
-        --urlcheck             Check URLs found in README files
-    -V, --version              Prints version information
-    -v, --verbose              Verbose operation?
+    pkgcheck [OPTIONS]
 
 OPTIONS:
-    -e, --explain <explain>        Explain error or warning message
-    -d, --package-dir <pkg_dir>    Package directory
-    -T, --tds-zip <tds_zip>        tds zip archive
-
+    -C, --correct-perms                      Correct permissions
+        --config-file <CONFIG_FILE>          Specify config file to use
+    -d, --package-dir <PKG_DIR>              Package directory
+    -e, --explain <EXPLAIN>                  Explain error or warning message
+        --explain-all                        Explains all error or warning messages
+        --generate-completion <GENERATOR>    [possible values: bash, elvish, fish,
+                                             powershell, zsh]
+    -h, --help                               Print help information
+    -I, --ignore-dupes                       Ignore dupes
+        --ignore-same-named                  Ignore same-named files
+    -L, --correct-le                         Correct line endings
+        --no-colors                          Don't display messages in color
+        --show-temp-endings                  Show file endings for temporary files
+    -T, --tds-zip <TDS_ZIP>                  tds zip archive
+        --urlcheck                           Check URLs found in README files
+    -v, --verbose                            Verbose operation?
+    -V, --version                            Print version information
 \end{verbatim}
+}
+
+\subsection{Config file}
+
+It is now possible to have a config file for \pkgcheck which then is a YAML
+file. A config file can be
+specified by using the command line option \verb|--config-file|. If no config
+file is specified during invocation of \pkgcheck then \pkgcheck checks two
+locations for existence of a config file.
+
+\begin{itemize}
+  \item \verb|~/.ctan/pkgcheck.yml|
+  \item \verb|.config/ctan/pkgcheck.yml|
+\end{itemize}
+
+Currently, the config file may contain only TDS path exceptions. For more
+details see message
+\hyperlink{i0009----updating-entry-pkgname---tpkg-with-pkgname---new-tpkg-from-config-file}{I0009x}.
+
+
+\subsection{Generate shell completions}
+
+\pkgcheck offers an option to generate shell completions for various shells,
+most notably \texttt{bash}, \texttt{zsh }and \texttt{fish}.
+
+
+
+\subsubsection{bash completion}
+
+In \texttt{bash} one recommendation is to put completions directly into
+the \verb|~/.bash_completion| file.
+
+Example:
+
+\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
+pkgcheck -generate-completion bash >> ~/.bash-completion
+\end{minted}
+
+\subsubsection{zsh completion}
+
+\texttt{zsh} doesn't recommend a specific location for completions. One
+possibility is the following:
+
+
+
+\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
+# Prepare
+mkdir -p ~/.zfunc/completions
+pkgcheck -generate-completion zsh >> ~/.zfunc/completions/_pkgcheck
+\end{minted}
+
+Put the following into \verb|~/.zshrc|
+
+\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
+fpath+=~/.zfunc/completions
+autoload -Uz compinit
+zstyle ':completion:*' menu select
+compinit
+\end{minted}
+
+\subsubsection{fish completion}
+
+\texttt{fish} is pretty straight forward as it offers the \texttt{~/.config/fish/completions/}
+directory for completions.
+
+
+Run
+
+\begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
+pkgcheck -generate-completion fish > ~/.config/fish/completions/pkgcheck.fish
+\end{minted}
+
+
+
 
 
 \subsection{Check a package}
@@ -151,7 +222,7 @@ tar archive. The package must have a top level directory.
 
 After unpacking the archive of a package \texttt{mypkg} into directory
 \texttt{mypkg/} it can be checked by running \pkgcheck with
-option verb|--package-dir| or shorter \verb|-d|.
+option \verb|--package-dir| or shorter \verb|-d|.
 
 
 \begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
@@ -161,19 +232,19 @@ option verb|--package-dir| or shorter \verb|-d|.
 \pkgcheck returns 1 if there are any errors, otherwise 0.
 
 
- 
+
 \subsection{Check a package which has a TDS archive}
 
 If a package contains a TDS ZIP archive it is supposed to be in the
 top level directory of a package.
 
-In order to check the TDS ZIP archive the option 
+In order to check the TDS ZIP archive the option
 \verb|-T <tds_zip>| or \verb|--tds-zip <tds_zip>| can be used.
 
 Please note that a TDS ZIP archive will always be checked together with
 the non-install tree of the package which means that
-\verb|--tds-zip| requires option \verb|--package-dir| as well.  
-   
+\verb|--tds-zip| requires option \verb|--package-dir| as well.
+
 Checking package \texttt{mypkg} \pkgcheck will be invoked like follows:
 
 \begin{minted}[linenos=true,frame=single,fontsize=\footnotesize]{sh}
@@ -230,7 +301,7 @@ file from CRLF to LF line endings.
 \item \verb|-V|
 
   Outputs \pkgcheck's version number.
-  
+
 \item \verb|--help|
 
   \verb|--help| shows the available command line options.
@@ -262,7 +333,7 @@ OPTIONS:
 
 \end{verbatim}
 
-\item  \verb|--explain <explain| 
+\item  \verb|--explain <explain|
 
   This option explains an error message in more detail.
 
@@ -273,7 +344,7 @@ OPTIONS:
 \end{minted}
 
 
-\item  \verb|--explain-all| 
+\item  \verb|--explain-all|
 
 Outputs a list of explanations of all messages.
 
@@ -293,7 +364,7 @@ text file has CRLF line endings.
 
 It is very important to note that determining file types is not bullet proof.
 So, it might happen in some cases that \pkgcheck makes mistakes when determining
-a file type. This could lead to a subseqent mistake when complaining about an
+a file type. This could lead to a subsequent mistake when complaining about an
 x-bit, or complaining about CRF line ending.
 
 
@@ -306,7 +377,7 @@ x-bit, or complaining about CRF line ending.
 From an installation point of view the files and directories of a package
 \begin{itemize}
 \item must be at least world readable
-\item must be writable by owner or group 
+\item must be writable by owner or group
 \item must not have the x-bit on for the owner if the file isn't an executable,
   i.e. a script or binary
 \end{itemize}
@@ -314,7 +385,7 @@ From an installation point of view the files and directories of a package
 The reason for this minimal requirement is that the installation utility used by
 the CTAN team (which by the way was written by Rainer Schöpf a long time ago)
 sets permissions correctly if the owner permission is set correctly.
- 
+
 Examples:
 
 \begin{itemize}
@@ -335,29 +406,31 @@ are accepted.
 \begin{description}
 \item[Innnn] Informational messages
 
-  These are message which announce \pkgcheck actions.
-  
+  These are message which usually announce \pkgcheck actions.
+
 \item[Fnnnn] Fatal messages
 
-  Fatal messages report unrecoverable errors. In this case \pkgcheck's only
-  option is to terminate. If for example, the package directory specified at
-  the command line doesn't exist then the only option is to terminate.
-  
+  Fatal messages are related to environmental issues and not related to
+  packages. They are usually unrecoverable errors, and \pkgcheck's only
+  option is to terminate. Fatal messages are written to standard error.
+
+  If for example, the package directory specified at
+  the command line doesn't exist then the only option is to issue
+  a message and to terminate.
+
 \item[Ennnn] Error messages
 
   Error messages report errors which must be fixed before installing a package.
-  
+
 \item[Wnnnn] Warning messages
 
   Warning messages denote possible errors depending upon the situation.
 
   For example, for a font package having many duplicate files might be ok. For
   another package it could be regarded as an error.
+\end{description}
 
-  
 
-  
-\end{description}
 \section{Informational messages}
 \input{informationd}
 
-- 
cgit v1.2.3

