OK gnezdo@ Thanks for doing that!
On Wed, Jun 9, 2021 at 4:21 AM Stuart Henderson <[email protected]> wrote: > Now that we have pandoc on amd64, would it be OK to add a preformatted > manual for shellcheck? The diff adds a simple hash check to remind about > (though not enforce) updating it if the source file changes. > > Index: Makefile > =================================================================== > RCS file: /cvs/ports/devel/shellcheck/Makefile,v > retrieving revision 1.8 > diff -u -p -r1.8 Makefile > --- Makefile 25 Apr 2021 17:29:48 -0000 1.8 > +++ Makefile 9 Jun 2021 11:20:37 -0000 > @@ -5,6 +5,7 @@ COMMENT = shell script analysis tool > MODCABAL_STEM = ShellCheck > MODCABAL_VERSION = 0.7.2 > MODCABAL_EXECUTABLES = shellcheck > +REVISION = 0 > PKGNAME = ${DISTNAME:L} > CATEGORIES = devel > HOMEPAGE = https://www.shellcheck.net/ > @@ -57,11 +58,13 @@ RUN_DEPENDS-main = > > NO_TEST = Yes > > -# TODO(gnezdo): find a lighter-weight option than pandoc used by > -# ShellCheck's manpage converter or pre-format and carry the page with > -# files directory. Gating ShellCheck on pandoc is a bad trade-off. > +# pkg_add pandoc; cd ${WRKSRC}; ./manpage; cp shellcheck.1 ${FILESDIR}/ > +# (and update md5) > +post-patch: > + @[ `md5 < ${WRKSRC}/shellcheck.1.md` == > e0bc56969657579f92b02bba09970ae4 ] || \ > + (echo "*** manpage changed; regenerate > ${FILESDIR}/shellcheck.1"; sleep 3) > + > post-install: > - ${INSTALL_DATA_DIR} ${PREFIX}/share/doc/${PKGNAME} > - ${INSTALL_DATA} ${WRKSRC}/shellcheck.1.md > ${PREFIX}/share/doc/${PKGNAME} > + ${INSTALL_DATA} ${FILESDIR}/shellcheck.1 ${PREFIX}/man/man1/ > > .include <bsd.port.mk> > Index: files/shellcheck.1 > =================================================================== > RCS file: files/shellcheck.1 > diff -N files/shellcheck.1 > --- /dev/null 1 Jan 1970 00:00:00 -0000 > +++ files/shellcheck.1 9 Jun 2021 11:20:37 -0000 > @@ -0,0 +1,406 @@ > +.\" Automatically generated by Pandoc 2.12 > +.\" > +.TH "SHELLCHECK" "1" "" "Shell script analysis tool" "" > +.hy > +.SH NAME > +.PP > +shellcheck - Shell script analysis tool > +.SH SYNOPSIS > +.PP > +\f[B]shellcheck\f[R] [\f[I]OPTIONS\f[R]...] \f[I]FILES\f[R]... > +.SH DESCRIPTION > +.PP > +ShellCheck is a static analysis and linting tool for sh/bash scripts. > +It\[aq]s mainly focused on handling typical beginner and intermediate > +level syntax errors and pitfalls where the shell just gives a cryptic > +error message or strange behavior, but it also reports on a few more > +advanced issues where corner cases can cause delayed failures. > +.PP > +ShellCheck gives shell specific advice. > +Consider this line: > +.IP > +.nf > +\f[C] > +(( area = 3.14*r*r )) > +\f[R] > +.fi > +.IP \[bu] 2 > +For scripts starting with \f[C]#!/bin/sh\f[R] (or when using > +\f[C]-s sh\f[R]), ShellCheck will warn that \f[C](( .. ))\f[R] is not > +POSIX compliant (similar to checkbashisms). > +.IP \[bu] 2 > +For scripts starting with \f[C]#!/bin/bash\f[R] (or using > +\f[C]-s bash\f[R]), ShellCheck will warn that decimals are not > +supported. > +.IP \[bu] 2 > +For scripts starting with \f[C]#!/bin/ksh\f[R] (or using > +\f[C]-s ksh\f[R]), ShellCheck will not warn at all, as \f[C]ksh\f[R] > +supports decimals in arithmetic contexts. > +.SH OPTIONS > +.TP > +\f[B]-a\f[R],\ \f[B]--check-sourced\f[R] > +Emit warnings in sourced files. > +Normally, \f[C]shellcheck\f[R] will only warn about issues in the > +specified files. > +With this option, any issues in sourced files will also be reported. > +.TP > +\f[B]-C\f[R][\f[I]WHEN\f[R]],\ \f[B]--color\f[R][=\f[I]WHEN\f[R]] > +For TTY output, enable colors \f[I]always\f[R], \f[I]never\f[R] or > +\f[I]auto\f[R]. > +The default is \f[I]auto\f[R]. > +\f[B]--color\f[R] without an argument is equivalent to > +\f[B]--color=always\f[R]. > +.TP > +\f[B]-i\f[R]\ \f[I]CODE1\f[R][,\f[I]CODE2\f[R]...],\ > \f[B]--include=\f[R]\f[I]CODE1\f[R][,\f[I]CODE2\f[R]...] > +Explicitly include only the specified codes in the report. > +Subsequent \f[B]-i\f[R] options are cumulative, but all the codes can be > +specified at once, comma-separated as a single argument. > +Include options override any provided exclude options. > +.TP > +\f[B]-e\f[R]\ \f[I]CODE1\f[R][,\f[I]CODE2\f[R]...],\ > \f[B]--exclude=\f[R]\f[I]CODE1\f[R][,\f[I]CODE2\f[R]...] > +Explicitly exclude the specified codes from the report. > +Subsequent \f[B]-e\f[R] options are cumulative, but all the codes can be > +specified at once, comma-separated as a single argument. > +.TP > +\f[B]-f\f[R] \f[I]FORMAT\f[R], \f[B]--format=\f[R]\f[I]FORMAT\f[R] > +Specify the output format of shellcheck, which prints its results in the > +standard output. > +Subsequent \f[B]-f\f[R] options are ignored, see \f[B]FORMATS\f[R] below > +for more information. > +.TP > +\f[B]--list-optional\f[R] > +Output a list of known optional checks. > +These can be enabled with \f[B]-o\f[R] flags or \f[B]enable\f[R] > +directives. > +.TP > +\f[B]--norc\f[R] > +Don\[aq]t try to look for .shellcheckrc configuration files. > +.TP > +\f[B]-o\f[R]\ \f[I]NAME1\f[R][,\f[I]NAME2\f[R]...],\ > \f[B]--enable=\f[R]\f[I]NAME1\f[R][,\f[I]NAME2\f[R]...] > +Enable optional checks. > +The special name \f[I]all\f[R] enables all of them. > +Subsequent \f[B]-o\f[R] options accumulate. > +This is equivalent to specifying \f[B]enable\f[R] directives. > +.TP > +\f[B]-P\f[R]\ \f[I]SOURCEPATH\f[R],\ > \f[B]--source-path=\f[R]\f[I]SOURCEPATH\f[R] > +Specify paths to search for sourced files, separated by \f[C]:\f[R] on > +Unix and \f[C];\f[R] on Windows. > +This is equivalent to specifying \f[C]search-path\f[R] directives. > +.TP > +\f[B]-s\f[R]\ \f[I]shell\f[R],\ \f[B]--shell=\f[R]\f[I]shell\f[R] > +Specify Bourne shell dialect. > +Valid values are \f[I]sh\f[R], \f[I]bash\f[R], \f[I]dash\f[R] and > +\f[I]ksh\f[R]. > +The default is to deduce the shell from the file\[aq]s \f[C]shell\f[R] > +directive, shebang, or \f[C].bash/.bats/.dash/.ksh\f[R] extension, in > +that order. > +\f[I]sh\f[R] refers to POSIX \f[C]sh\f[R] (not the system\[aq]s), and > +will warn of portability issues. > +.TP > +\f[B]-S\f[R]\ \f[I]SEVERITY\f[R],\ \f[B]--severity=\f[R]\f[I]severity\f[R] > +Specify minimum severity of errors to consider. > +Valid values in order of severity are \f[I]error\f[R], > +\f[I]warning\f[R], \f[I]info\f[R] and \f[I]style\f[R]. > +The default is \f[I]style\f[R]. > +.TP > +\f[B]-V\f[R],\ \f[B]--version\f[R] > +Print version information and exit. > +.TP > +\f[B]-W\f[R] \f[I]NUM\f[R],\ \f[B]--wiki-link-count=NUM\f[R] > +For TTY output, show \f[I]NUM\f[R] wiki links to more information about > +mentioned warnings. > +Set to 0 to disable them entirely. > +.TP > +\f[B]-x\f[R],\ \f[B]--external-sources\f[R] > +Follow \f[C]source\f[R] statements even when the file is not specified > +as input. > +By default, \f[C]shellcheck\f[R] will only follow files specified on the > +command line (plus \f[C]/dev/null\f[R]). > +This option allows following any file the script may \f[C]source\f[R]. > +.TP > +\f[B]FILES...\f[R] > +One or more script files to check, or \[dq]-\[dq] for standard input. > +.SH FORMATS > +.TP > +\f[B]tty\f[R] > +Plain text, human readable output. > +This is the default. > +.TP > +\f[B]gcc\f[R] > +GCC compatible output. > +Useful for editors that support compiling and showing syntax errors. > +.RS > +.PP > +For example, in Vim, > +\f[C]:set makeprg=shellcheck\[rs] -f\[rs] gcc\[rs] %\f[R] will allow > +using \f[C]:make\f[R] to check the script, and \f[C]:cnext\f[R] to jump > +to the next error. > +.IP > +.nf > +\f[C] > +<file>:<line>:<column>: <type>: <message> > +\f[R] > +.fi > +.RE > +.TP > +\f[B]checkstyle\f[R] > +Checkstyle compatible XML output. > +Supported directly or through plugins by many IDEs and build monitoring > +systems. > +.RS > +.IP > +.nf > +\f[C] > +<?xml version=\[aq]1.0\[aq] encoding=\[aq]UTF-8\[aq]?> > +<checkstyle version=\[aq]4.3\[aq]> > + <file name=\[aq]file\[aq]> > + <error > + line=\[aq]line\[aq] > + column=\[aq]column\[aq] > + severity=\[aq]severity\[aq] > + message=\[aq]message\[aq] > + source=\[aq]ShellCheck.SC####\[aq] /> > + ... > + </file> > + ... > +</checkstyle> > +\f[R] > +.fi > +.RE > +.TP > +\f[B]diff\f[R] > +Auto-fixes in unified diff format. > +Can be piped to \f[C]git apply\f[R] or \f[C]patch -p1\f[R] to > +automatically apply fixes. > +.RS > +.IP > +.nf > +\f[C] > +--- a/test.sh > ++++ b/test.sh > +\[at]\[at] -2,6 +2,6 \[at]\[at] > + ## Example of a broken script. > + for f in $(ls *.m3u) > + do > +- grep -qi hq.*mp3 $f \[rs] > ++ grep -qi hq.*mp3 \[dq]$f\[dq] \[rs] > + && echo -e \[aq]Playlist $f contains a HQ file in mp3 format\[aq] > + done > +\f[R] > +.fi > +.RE > +.TP > +\f[B]json1\f[R] > +Json is a popular serialization format that is more suitable for web > +applications. > +ShellCheck\[aq]s json is compact and contains only the bare minimum. > +Tabs are counted as 1 character. > +.RS > +.IP > +.nf > +\f[C] > +{ > + comments: [ > + { > + \[dq]file\[dq]: \[dq]filename\[dq], > + \[dq]line\[dq]: lineNumber, > + \[dq]column\[dq]: columnNumber, > + \[dq]level\[dq]: \[dq]severitylevel\[dq], > + \[dq]code\[dq]: errorCode, > + \[dq]message\[dq]: \[dq]warning message\[dq] > + }, > + ... > + ] > +} > +\f[R] > +.fi > +.RE > +.TP > +\f[B]json\f[R] > +This is a legacy version of the \f[B]json1\f[R] format. > +It\[aq]s a raw array of comments, and all offsets have a tab stop of 8. > +.TP > +\f[B]quiet\f[R] > +Suppress all normal output. > +Exit with zero if no issues are found, otherwise exit with one. > +Stops processing after the first issue. > +.SH DIRECTIVES > +.PP > +ShellCheck directives can be specified as comments in the shell script. > +If they appear before the first command, they are considered file-wide. > +Otherwise, they apply to the immediately following command or block: > +.IP > +.nf > +\f[C] > +# shellcheck key=value key=value > +command-or-structure > +\f[R] > +.fi > +.PP > +For example, to suppress SC2035 about using \f[C]./*.jpg\f[R]: > +.IP > +.nf > +\f[C] > +# shellcheck disable=SC2035 > +echo \[dq]Files: \[dq] *.jpg > +\f[R] > +.fi > +.PP > +To tell ShellCheck where to look for an otherwise dynamically determined > +file: > +.IP > +.nf > +\f[C] > +# shellcheck source=./lib.sh > +source \[dq]$(find_install_dir)/lib.sh\[dq] > +\f[R] > +.fi > +.PP > +Here a shell brace group is used to suppress a warning on multiple > +lines: > +.IP > +.nf > +\f[C] > +# shellcheck disable=SC2016 > +{ > + echo \[aq]Modifying $PATH\[aq] > + echo \[aq]PATH=foo:$PATH\[aq] >> \[ti]/.bashrc > +} > +\f[R] > +.fi > +.PP > +Valid keys are: > +.TP > +\f[B]disable\f[R] > +Disables a comma separated list of error codes for the following > +command. > +The command can be a simple command like \f[C]echo foo\f[R], or a > +compound command like a function definition, subshell block or loop. > +A range can be be specified with a dash, e.g. > +\f[C]disable=SC3000-SC4000\f[R] to exclude 3xxx. > +.TP > +\f[B]enable\f[R] > +Enable an optional check by name, as listed with > +\f[B]--list-optional\f[R]. > +Only file-wide \f[C]enable\f[R] directives are considered. > +.TP > +\f[B]source\f[R] > +Overrides the filename included by a \f[C]source\f[R]/\f[C].\f[R] > +statement. > +This can be used to tell shellcheck where to look for a file whose name > +is determined at runtime, or to skip a source by telling it to use > +\f[C]/dev/null\f[R]. > +.TP > +\f[B]source-path\f[R] > +Add a directory to the search path for \f[C]source\f[R]/\f[C].\f[R] > +statements (by default, only ShellCheck\[aq]s working directory is > +included). > +Absolute paths will also be rooted in these paths. > +The special path \f[C]SCRIPTDIR\f[R] can be used to specify the > +currently checked script\[aq]s directory, as in > +\f[C]source-path=SCRIPTDIR\f[R] or > +\f[C]source-path=SCRIPTDIR/../libs\f[R]. > +Multiple paths accumulate, and \f[C]-P\f[R] takes precedence over them. > +.TP > +\f[B]shell\f[R] > +Overrides the shell detected from the shebang. > +This is useful for files meant to be included (and thus lacking a > +shebang), or possibly as a more targeted alternative to > +\[aq]disable=SC2039\[aq]. > +.SH RC FILES > +.PP > +Unless \f[C]--norc\f[R] is used, ShellCheck will look for a file > +\f[C].shellcheckrc\f[R] or \f[C]shellcheckrc\f[R] in the script\[aq]s > +directory and each parent directory. > +If found, it will read \f[C]key=value\f[R] pairs from it and treat them > +as file-wide directives. > +.PP > +Here is an example \f[C].shellcheckrc\f[R]: > +.IP > +.nf > +\f[C] > +# Look for \[aq]source\[aq]d files relative to the checked script, > +# and also look for absolute paths in /mnt/chroot > +source-path=SCRIPTDIR > +source-path=/mnt/chroot > + > +# Turn on warnings for unquoted variables with safe values > +enable=quote-safe-variables > + > +# Turn on warnings for unassigned uppercase variables > +enable=check-unassigned-uppercase > + > +# Allow [ ! -z foo ] instead of suggesting -n > +disable=SC2236 > +\f[R] > +.fi > +.PP > +If no \f[C].shellcheckrc\f[R] is found in any of the parent directories, > +ShellCheck will look in \f[C]\[ti]/.shellcheckrc\f[R] followed by the > +XDG config directory (usually \f[C]\[ti]/.config/shellcheckrc\f[R]) on > +Unix, or \f[C]%APPDATA%/shellcheckrc\f[R] on Windows. > +Only the first file found will be used. > +.PP > +Note for Snap users: the Snap sandbox disallows access to hidden files. > +Use \f[C]shellcheckrc\f[R] without the dot instead. > +.PP > +Note for Docker users: ShellCheck will only be able to look for files > +that are mounted in the container, so \f[C]\[ti]/.shellcheckrc\f[R] will > +not be read. > +.SH ENVIRONMENT VARIABLES > +.PP > +The environment variable \f[C]SHELLCHECK_OPTS\f[R] can be set with > +default flags: > +.IP > +.nf > +\f[C] > +export SHELLCHECK_OPTS=\[aq]--shell=bash --exclude=SC2016\[aq] > +\f[R] > +.fi > +.PP > +Its value will be split on spaces and prepended to the command line on > +each invocation. > +.SH RETURN VALUES > +.PP > +ShellCheck uses the following exit codes: > +.IP \[bu] 2 > +0: All files successfully scanned with no issues. > +.IP \[bu] 2 > +1: All files successfully scanned with some issues. > +.IP \[bu] 2 > +2: Some files could not be processed (e.g. > +file not found). > +.IP \[bu] 2 > +3: ShellCheck was invoked with bad syntax (e.g. > +unknown flag). > +.IP \[bu] 2 > +4: ShellCheck was invoked with bad options (e.g. > +unknown formatter). > +.SH LOCALE > +.PP > +This version of ShellCheck is only available in English. > +All files are leniently decoded as UTF-8, with a fallback of ISO-8859-1 > +for invalid sequences. > +\f[C]LC_CTYPE\f[R] is respected for output, and defaults to UTF-8 for > +locales where encoding is unspecified (such as the \f[C]C\f[R] locale). > +.PP > +Windows users seeing > +\f[C]commitBuffer: invalid argument (invalid character)\f[R] should set > +their terminal to use UTF-8 with \f[C]chcp 65001\f[R]. > +.SH AUTHORS > +.PP > +ShellCheck is developed and maintained by Vidar Holen, with assistance > +from a long list of wonderful contributors. > +.SH REPORTING BUGS > +.PP > +Bugs and issues can be reported on GitHub: > +.PP > +https://github.com/koalaman/shellcheck/issues > +.SH COPYRIGHT > +.PP > +Copyright 2012-2019, Vidar Holen and contributors. > +Licensed under the GNU General Public License version 3 or later, see > +https://gnu.org/licenses/gpl.html > +.SH SEE ALSO > +.PP > +sh(1) bash(1) > Index: pkg/PLIST > =================================================================== > RCS file: /cvs/ports/devel/shellcheck/pkg/PLIST,v > retrieving revision 1.1 > diff -u -p -r1.1 PLIST > --- pkg/PLIST 28 Feb 2021 19:58:09 -0000 1.1 > +++ pkg/PLIST 9 Jun 2021 11:20:37 -0000 > @@ -1,5 +1,4 @@ > @comment $OpenBSD: PLIST,v 1.1 2021/02/28 19:58:09 gnezdo Exp $ > @pkgpath devel/shellcheck,-main > @bin bin/shellcheck > -share/doc/${PKGNAME}/ > -share/doc/${PKGNAME}/shellcheck.1.md > +@man man/man1/shellcheck.1 > > -- nest.cx is Gmail hosted, use PGP: https://pgp.key-server.io/0x0B1542BD8DF5A1B0 Fingerprint: 5E2B 2D0E 1E03 2046 BEC3 4D50 0B15 42BD 8DF5 A1B0
