bin/38233: audit-packages.conf(5) doesn't describe the file syntax

[jbernard%mines.edu@localhost]

>Number:         38233
>Category:       bin
>Synopsis:       audit-packages.conf(5) doesn't describe the file syntax
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Mar 12 16:30:00 +0000 2008
>Originator:     Jim Bernard
>Release:        NetBSD 4.99.49
>Organization:
>Environment:
System: NetBSD 4.99.49 Mon Jan 21 19:17:34 MST 2008 i386
Architecture: i386
Machine: i386
>Description:
        The man page for audit-packages.conf specifies variables that
        can be set in the file, but makes no mention of the syntax of
        the file.  It's used by two programs, download-vulnerability-list,
        a Bourne-shell script, and by audit-packages, a binary program.
        The script simply sources the config file as a shell-script fragment,
        and the program parses the file to find lines in which the variables
        it cares about are set with something resembling shell-script syntax.
        It ignores comments, blank lines, and any lines that don't start
        with the names of the variables it cares about (which constitute
        a limited subset of the variables mentioned in audit-packages.conf(5)).

        One other problem: the man page says the default for PKGVULNDIR
        is /var/db/pkg.  The default is actually the value of PKG_DBDIR,
        which has the default value /var/db/pkg.  The distinction can be
        an important one.  (PKG_DBDIR cannot be set in this config file,
        but can be set in the environment or on the command line of any
        of the pkg_install tools.)

>How-To-Repeat:
        man audit-packages.conf

>Fix:
        Since audit-packages uses the more limited syntax, it's probably
        best to describe the syntax it uses.  I suggest appending something
        like the following to the opening paragraph of the DESCRIPTION:

          Blank lines and comments introduced by a "#" in the first column
          are ignored, and variable assignments are of the general form

            VARIABLE=value

          where the name of the variable must begin in the first column.


        For the second issue, I suggest changing

          The default is "/var/db/pkg".

        to something like

          The default is the value of PKG_DBDIR, which may be specified
          in the environment or on the command line with the "-K" flag.
          The default value of PKG_DBDIR is "/var/db/pkg".

        in the description of PKGVULNDIR.  Alternatively, since the
        detailed description of PKG_DBDIR appears in the man pages for
        audit-packages(1) and download-vulnerability-list(1), one could
        just say the default is PKG_DBDIR and cross reference those
        man pages for the details.