From 84a5593d3fb9d03aac5677678bcc4c92e8c9a9c4 Mon Sep 17 00:00:00 2001 From: Norbert Preining 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 -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 error or warning message - -d, --package-dir Package directory - -T, --tds-zip tds zip archive - + -C, --correct-perms Correct permissions + --config-file Specify config file to use + -d, --package-dir Package directory + -e, --explain Explain error or warning message + --explain-all Explains all error or warning messages + --generate-completion [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 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 | or \verb|--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