NAME
    stilview - command-line program to help you retrieve the entries stored
    in STIL.

SYNOPSIS
    stilview [-b] [-d] [-e entry] [-f field] [-i] [-l HVSC base dir] [-m]
    [-o] [-s] [-t tune number]

    stilview {[-h] | [-v]}

DESCRIPTION
    STILView is a command-line driven program to help you retrieve the
    entries stored in STIL fast and accurately. STILView uses the STIL C++
    class heavily to do this, and in fact, the primary purpose of this
    command-line program is to test that class (which is, BTW, used in many
    GUI-based SID players, most notably in SIDPlay for Windows and XSIDPLAY
    for Unix systems). However, it is user-friendly enough to be used by
    non-programmers, too.

GLOSSARY
    Some terms and STIL-related lingo in alphabetical order:

    BUG ENTRY
        There exists a special file in HVSC (/DOCUMENTS/BUGlist.txt) that
        lists all known bugs in SID tunes in HVSC. See the top of that file
        for details about what's in it exactly. A BUG entry is like a STIL
        entry, but it is contained in this BUGlist.txt file.

    FIELD
        The smallest piece of information in a STIL entry. Currently valid
        field names are NAME, TITLE, ARTIST and COMMENT.

    FILE-GLOBAL COMMENT
        A special COMMENT field in a STIL entry for a multi-tune SID file
        that refers to the whole SID, not just one tune in it. These usually
        contain general information about the SID file itself.

        Example:

          /Hubbard_Rob/Gerry_the_Germ.sid
          COMMENT: In Rob's own demo of this music, the tunes are named after the levels
                   in the original game.
          (#1)
            TITLE: Lungs
          (#2)
            TITLE: Kidney
          (#7)
            TITLE: End

    HVSC
        High Voltage SID Collection. If you don't know what this is, you
        downloaded the wrong program. :)

    HVSC-RELATIVE PATHNAME
        The pathname plus filename of a SID file that can be found in your
        HVSC, relative to the base directory of HVSC. It is always in
        UNIX-style format, eg.: /Hubbard_Rob/Commando.sid refers to Rob
        Hubbard's Commando.sid file within HVSC (which may actually be found
        as C:\Music\HVSC\Hubbard_Rob\Commando.sid on your Windows PC).

    MULTI-TUNE ENTRY
        A STIL entry that is referring to a SID file that has many tunes in
        it. Each tune might have its own STIL block, which are separated by
        a so-called tune designation in the form of "(#x)", where x = the
        tune number. Consult the STIL.FAQ in HVSC for a detailed
        description.

        Example:

          /Hubbard_Rob/Gerry_the_Germ.sid
          COMMENT: In Rob's own demo of this music, the tunes are named after the levels
                   in the original game.
          (#1)
            TITLE: Lungs
          (#2)
            TITLE: Kidney
          (#7)
            TITLE: End

    SECTION
        A part of STIL that belongs to one composer (ie. every STIL entry
        referring to SID files that are in one subdirectory in HVSC).
        Sections in STIL are always separated by a line in the form of: "###
        Composer's name ########".

    SECTION-GLOBAL COMMENT
        A special STIL entry that refers not to an individual SID file, but
        to a whole subdirectory. These usually contain info about the
        composer himself, or about all the SID file he/she ever composed,
        and are always indexed in the form of "/Subdir/" (note the trailing
        slash!).

        Example:

          /Hubbard_Rob/
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
                   Hubbard's own comments are denoted by (RH).

    SINGLE-TUNE ENTRY
        A STIL entry that has no tune designation in it in the form of
        "(#x)", where x is a number. (Note, that a single-tune entry might
        still refer to a SID file which has many tunes in it, ie. when a
        single-tune entry has nothing but a COMMENT field in it!)

        Example:

          /Hubbard_Rob/Chain_Reaction.sid
          TITLE: Zoolook (remix) [from Zoolook]
          ARTIST: Jean Michel Jarre

        Another example (the SID this is refering to has many tunes in it!):

          /Barrett_Steve/Magic_Land_Dizzy.sid
          COMMENT: Also used in the game "Wacky Darts" (c) 1990 Codemasters.

    STIL
        SID Tune Information List, essentially a text-file database that can
        be found in your HVSC in the /DOCUMENTS/ subdirectory.

    STIL ENTRY
        All of the pieces of information in STIL relating to one SID file of
        the HVSC. They are always indexed by the HVSC-relative pathname.

    TUNE
        One of the compositions in a SID. Most SID files have only one tune
        in them, but many have more than one (eg. one for the title score of
        the game, and one for the hi-score music).

OPTIONS
    -b  Do not print BUG entries Default value: Not specified (ie. do print
        BUG entries)

        Example: "stilview -e=/Hubbard_Rob/Commando.sid -b"

        When this option is specified, BUG entries will not be printed for
        the given SID tune. At a minimum, the -e option has to be specified
        for this option to work.

    -d  Default value: Not specified (ie. debug mode is off)

        Example: "stilview -e=/Hubbard_Rob/Commando.sid -d"

        Turns on debug mode in STILView. This will result in an extensive
        output, with the debugging messages going to STDERR. If you
        encounter any problem or strange behavior with STILView, run
        STILView with the exact same options as you did when you encountered
        the problem, with this -d option added to them. Capture the complete
        output of this run, and send it to me with a detailed explanation of
        the problem (see email address at the top of this file).

    -e=*entry*
        Default: NONE (you have to give an HVSC-relative pathname to this
        option)

        Example #1: "stilview -e=/Hubbard_Rob/Commando.sid"

        Example #2: "stilview -e=/Hubbard_Rob/"

        This is where you specify the STIL entry you are looking for, given
        as an HVSC-relative pathname. If there exists no STIL entry for the
        given filename, STILView will print out nothing. Otherwise, you'll
        get the STIL entry (or parts of it, as you may have specified it by
        other options). HVSC-relative pathnames are case-insensitive, so
        /HUBBARD_ROB/Commando.sid is the same as /Hubbard_Rob/Commando.sid.

        Example #1 is the most frequent way of retrieving STIL entries, and
        it will return all of the STIL entry for Commando.sid, as well as
        the section-global comment for /Hubbard_Rob/. Example #2 is another
        valid thing to do: this will return only the section-global comment
        for /Hubbard_Rob/.

    -h  Default: NONE Example: stilview -h

        Prints a brief help screen listing the available options. All other
        options that are also specified on the command-line are ignored.

    -f=*field*
        Default: all

        Valid values for <field> are: all, name, author, title, artist,
        comment

        Example #1: "stilview -l -e=/Hubbard_Rob/Delta.sid -f=comment"

        Example #2: "stilview -l -e=/Hubbard_Rob/Delta.sid -t=1 -f=title"

        Example #3: "stilview -l -e=/Hubbard_Rob/Delta.sid -t=12 -f=all -s
        -b"

        Asks for one particular field in a STIL entry. Combined with the -t
        option, these two options can retrieve any portion of a STIL entry,
        including a single field in a specific subtune's entry. Below is
        full and complete explanation of what the different possible
        combinations of the -t and -f options retrieve:

        "-t=0 -f=all" : All of the STIL entry is printed.

        "-t=0 -f=comment" : The file-global comment is printed. For
        single-tune entries that have nothing but a COMMENT field in them,
        this prints that COMMENT. For single-tune entries that have other
        fields in them, this prints nothing. (This is because single-tune
        entries with nothing but a COMMENT field are assumed to be
        file-global comments.)

        "-t=0 -f=<name/author/title/artist>" : Nothing is printed. This
        combination of these options is invalid.

        "-t=<x> -f=all" : (Where x is anything but 0.) All fields from the
        portion of the STIL entry for the given tune number <x> are printed.
        For single-tune entries, asking for -t=1 -f=all is equivalent to
        saying -t=0 -f=all, since by definition, the whole entry refers to
        only one tune. (However, specifying -t with any other number than 1
        will print nothing!) Note that if there's a file-global comment in
        the STIL entry (which also means that if a single-tune entry has
        nothing but a COMMENT field in it), that is not printed with these
        combinations of options.

        "-t=<x> -f=<name/author/title/artist/comment>" : (Where x is
        anything but 0.) The specific field from the portion of the STIL
        entry for the given tune number is printed. For single-tune entries
        that have nothing but a COMMENT in them, this returns nothing.

        Of course, if the STIL entry or any portion of it asked with these
        options does not exist, STILView will print nothing. Also, unless
        otherwise specified with the -o, -s and -b options, the
        section-global comment and the BUG entry of the given SID file will
        also get printed (provided they exist).

        In example #1, the file-global comment for /Hubbard_Rob/Delta.sid is
        printed, since -t is not specified and is assumed to be 0. Also
        printed are the section- global comment and the BUG entry for the
        same SID file (if they exist). In example #2, the TITLE field of the
        STIL entry for tune #1 of /Hubbard_Rob/Delta.sid is printed along
        with the section-global comment and the BUG entry for the same SID
        file (if they exist). In example #3, all of the STIL entry for tune
        #12 of /Hubbard_Rob/Delta.sid is printed, but nothing else.

    -i  Default: NONE

        Example: "stilview -i"

        Starts STILView in interactive mode, ignoring all other options
        specified on the command-line, except -l, -d and -m. In interactive
        mode, you can look for STIL entries by typing them in. You will get
        prompted for the desired STIL entry (which has to be specified with
        an HVSC-relative pathname), for the tune number requested (which
        should be any non-negative number, but this is not enforced), and
        finally for the specific STIL field you want to retrieve.

    -l=*HVSC base dir*
        Default: The value of the HVSC_BASE environment variable

        Example #1: "stilview -l=C:\Music\HVSC\
        -e=/Hubbard_Rob/Commando.sid"

        Example #2: "stilview -l=../HVSC/ =-e=/Hubbard_Rob/Commando.sid"

        Example #3: "stilview -l -e=/Hubbard_Rob/Commando.sid"

        This is where you tell STILView where it can find the HVSC base
        directory (the path to the directory has to be specified in the form
        required by your operating system, eg. C:\Music\HVSC under Windows,
        /home/lala/HVSC under UNIX). STILView will then try to locate the
        STIL.txt file in the /DOCUMENTS/ subdirectory of that directory. If
        this option is not specified (or if -l is specified without a base
        directory), STILView will try to extract the path of the HVSC base
        directory from the HVSC_BASE environment variable. If that
        environment variable doesn't exist or is pointing to a location
        where there's no STIL.txt file in a DOCUMENTS directory, STILView
        fails. If the HVSC_BASE environment variable exists and is valid,
        and this option is specified, the directory specified with this
        option is used as the HVSC base directory instead of the environment
        variable.

        In example #1 the HVSC base directory is located in C:\Music\HVSC\
        on the hard drive of a Windows PC, in example #2 it is located in
        the HVSC directory of the current directory's parent directory of a
        UNIX system. In example #3 the HVSC base directory is not specified
        with the option, so it is assumed that the HVSC_BASE environment
        variable contains the path to it. In reality, specifying the -l
        option in example #3 is redundant, and can be omitted.

    -m  Demo mode

        Default: NONE

        Example #1: "stilview -m"

        Example #2: "stilview -e=/Hubbard_Rob/Commando.sid -m -i"

        When specified, it prints out a whole bunch of things that a) test
        most of the functionality of STILView, and b) show what STILView is
        capable of retrieving from STIL. In example #1, the demo is printed
        with the STIL info coming from a default STIL entry, then STILView
        quits. In example #2, the demo is printed taking the STIL info from
        the specified STIL entry of /Hubbard_Rob/Commando.sid (instead of
        the default SID file), then interactive mode is entered.

    -o  Do not print STIL entries

        Default value: Not specified (ie. do print STIL entries)

        Example #1: "stilview -e=/Hubbard_Rob/Delta.sid -o"

        Example #2: "stilview -e=/Hubbard_Rob/Delta.sid -o -s"

        When this option is specified, STIL entries will not be printed for
        the given SID tune (but section-global entries and BUG entries will
        be printed, provided they exist and other options did not turn their
        output off). At a minimum, the -e option has to be specified for
        this option to work. Example #1 will print out the section-global
        comment and the BUG entry for /Hubbard_Rob/Delta.sid, example #2
        will print out just the section-global comment for the same SID.

    -s  Do not print section-global comments

        Default value: Not specified (ie. do print section-global entries)

        Example: "stilview -e=/Hubbard_Rob/Delta.sid -s"

        When this option is specified, section-global entries will not be
        printed for the given SID tune. At a minimum, the -e option has to
        be specified for this option to work.

    -t=*tune number*
        Default value: 0

        Example #1: "stilview -e=/Hubbard_Rob/Commando.sid -t=0"

        Example #2: "stilview -e=/Hubbard_Rob/Delta.sid -t=1 -f=title -s -b"

        Example #3: "stilview -e=/Hubbard_Rob/Delta.sid -t=12"

        Asks for the portion of a STIL entry referring to one particular
        tune. If tune number 0 is given, it retrieves all of the entry.
        Combined with the -f option, these two options can retrieve any
        portion of a STIL entry, including a single field in a specific
        subtune's entry.

        For further details about this option, see the explanation of the -f
        option.

        Example #1 retrieves all of the STIL entry for
        /Hubbard_Rob/Commando.sid, including the section-global comment and
        the BUG entry (if any), but since the default value for this option
        is 0, it might as well be omitted in this example. Example #2
        retrieves only the TITLE field of the first subtune's entry for
        /Hubbard_Rob/Delta.sid (and not the section- global comment or the
        BUG entry), while example #3 retrieves all of the STIL entry for
        tune #12 of the same SID file (including the section-global comment
        and the BUG entry, if any).

    -v  Print version numbers

        Default value: Not specified (ie. do *not* print version numbers)

        Example #1: "stilview -v"

        Example #2: "stilview -e=/Hubbard_Rob/Commando.sid -v"

        When this option is specified, the version number of the STILView
        program and the version number of the STIL.txt file used by it is
        printed out. In example #1 this is the only piece of info that gets
        printed on the screen, in example #2 the version numbers are printed
        out, then the STIL entry for /Hubbard_Rob/Commando.sid is also
        printed out.

ENVIRONMENT
    HVSC_BASE
        Specifies the location of the HVSC base directory.

EXAMPLES
    All of the examples below assume that the HVSC_BASE environment is set
    to a valid HVSC base directory (where the $HVSC_BASE/DOCUMENTS/STIL.txt
    and $HVSC_BASE/DOCUMENTS/BUGlist.txt files exist), and the examples also
    assume the presence of the following entries in these files:

     --- In STIL.txt ---

       /Hubbard_Rob/
       COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                have often stolen Hubbard's routine causing some tunes to be falsely
                credited to him.

       /Hubbard_Rob/Action_Biker.sid
       COMMENT: "Action B was a very early game and very conservative in it's approach
                - it was my idea of giving them what I thought they wanted, a simple
                cute tune....." (RH)

       /Hubbard_Rob/Commando.sid
       COMMENT: Tunes #1 and #3 have been converted from arcade version.

       /Hubbard_Rob/Delta.sid
       COMMENT: According to Hubbard, Kentilla and Delta were the most complicated one
                to compose, they took the longest time to do and they both drove him
                insane.
       (#1)
         TITLE: On the Run [from the Dark Side of the Moon]
        ARTIST: Pink Floyd
       COMMENT: It is more inspired by it than a remix of it.
       (#12)
         TITLE: Koyaanisqatsi [from the movie]
        ARTIST: Philip Glass
       COMMENT: "Inspired by Philip Glass and Pink Floyd." (RH)

       /Hubbard_Rob/International_Karate.sid
         TITLE: Merry Christmas, Mr. Lawrence [from the movie] (0:42-1:16)
        ARTIST: Ryuichi Sakamoto
       COMMENT: "[...] I started exploring pentatonic things in B flat minor over
                different bass notes, B flat, D flat, G flat and A flat. The middle
                section went into F (I think) at double tempo to liven things up. I
                was pleased with the tune......" (RH)

       /Hubbard_Rob/Rasputin.sid
       (#1)
         TITLE: Katjusha (0:07-0:36)
        ARTIST: Matvei Blanter, M. Isakovski
         TITLE: Katjusha (2:20)
        ARTIST: Matvei Blanter, M. Isakovski
         TITLE: Kaljinka (2:41-2:51)
        ARTIST: Traditional
       COMMENT: Russian folk song.
         TITLE: Kaljinka (3:12-3:22)
        ARTIST: Traditional
       COMMENT: Russian folk song.
       (#2)
       COMMENT: Russian folk song.

     --- In BUGlist.txt ---

       /Hubbard_Rob/Commando.sid
         BUG: This is just for demo.

       /Hubbard_Rob/Delta.sid
       (#12)
         BUG: Demo entry.

    Given these entries, following are the printouts you can expect from
    STILView. ($> denotes a command-line prompt given by your operating
    system.)

    Everything related to a SID file is printed:

       $> stilview -e=/Hubbard_Rob/Commando.sid
          ---- GLOBAL  COMMENT ----
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
          ------ STIL  ENTRY ------
          COMMENT: Tunes #1 and #3 have been converted from arcade version.
          ---------- BUG ----------
            BUG: This is just for demo.
       $>

    Ask for just the section-global comment:

       $> stilview -e=/Hubbard_Rob/
          /Hubbard_Rob/
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
       $>

    Note that this can also be retrieved with:

       $> stilview -e=/Hubbard_Rob/Commando.sid -o -b
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
       $>

    This prints out nothing, as single-tune entries do not have file-global
    comments:

       $> stilview -e=/Hubbard_Rob/International_Karate.sid -t=0 -f=comment -s -b
       $>

    ...Except if the only field in them is a COMMENT (in which case that
    comment is assumed to be a file-global comment):

       $> stilview -e=/Hubbard_Rob/Action_Biker.sid -t=0 -f=comment -s -b
          COMMENT: "Action B was a very early game and very conservative in it's approach
                   - it was my idea of giving them what I thought they wanted, a simple
                   cute tune....." (RH)
       $>

    Also note that single-tune entries have only one tune, so asking for the
    STIL entry of tune #3 is pointless:

       $> stilview -e=/Hubbard_Rob/International_Karate.sid -t=3 -s -b
       $>

    Print out the file-global comment for the given SID file:

       $> stilview -e=/Hubbard_Rob/Delta.sid -t=0 -f=comment -s -b
          COMMENT: According to Hubbard, Kentilla and Delta were the most complicated one
                   to compose, they took the longest time to do and they both drove him
                   insane.
       $>

    Print out the ARTIST field of tune #12 of the given SID file, plus print
    out everything else related to the SID file:

       $> stilview -e=/Hubbard_Rob/Delta.sid -t=12 -f=artist
          ---- GLOBAL  COMMENT ----
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
          ------ STIL  ENTRY ------
           ARTIST: Philip Glass
          ---------- BUG ----------
            BUG: Demo entry.
       $>

    Note that the current version of STILView is capable to retrieve only
    the first specified field of a tune that covers multiple songs! See
    below:

       $> stilview -e=/Hubbard_Rob/Rasputin.sid -t=1 -f=title -s
            TITLE: Katjusha (0:07-0:36)
       $>

    Section-global comments are printed out even if the STIL entry for the
    given SID file does not exist:

       $> stilview -e=/Hubbard_Rob/This_doesnt_exist.sid
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
       $>

    The following 4 steps depict how to have STILView print out everything
    related to a given SID file's given tune number one by one:

    1) This prints out just the section-global comment:

       $> stilview -e=/Hubbard_Rob/Delta.sid -o -b
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
       $>

    2) This prints out just the file-global comment:

       $> stilview -e=/Hubbard_Rob/Delta.sid -t=0 -f=comment -s -b
          COMMENT: According to Hubbard, Kentilla and Delta were the most complicated one
                   to compose, they took the longest time to do and they both drove him
                   insane.
       $>

    3) This prints out all of the STIL entry for the given tune number:

       $> stilview -e=/Hubbard_Rob/Delta.sid -t=12 -f=all -s -b
            TITLE: Koyaanisqatsi [from the movie]
           ARTIST: Philip Glass
          COMMENT: "Inspired by Philip Glass and Pink Floyd." (RH)
       $>

    4) And this prints out just the BUG entry for the same tune number:

       $> stilview -e=/Hubbard_Rob/Delta.sid -t=12 -s -o
            BUG: Demo entry.
       $>

    The following 3 steps depict how to have STILView print out everything
    related to a given SID file:

    1) This prints out just the section-global comment:

       $> stilview -e=/Hubbard_Rob/Delta.sid -o -b
          COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
                   have often stolen Hubbard's routine causing some tunes to be falsely
                   credited to him.
       $>

    2) This prints out all of the STIL entry:

       $> stilview -e=/Hubbard_Rob/Delta.sid -s -b
          COMMENT: "[...] The Delta music loader and ingame music was Gary Liddon's idea.
                   [...] He was the producer at Thalamus at the time. He told Rob Hubbard
                   to make the ingame music like the 2nd track from Dark Side of the Moon
                   by Pink Floyd." (Info from Matt Furniss.)
                   "The small jingles are all small clips from Sanxion and Romeo/Juliet
                   music. They were all supposed to be for short stingers such as end of
                   level, extra life etc..."
                   "Delta was based on this minimalist composition technique inspired by
                   Glass and a bit of Pink Floyd. It was quite hard too do and required
                   some custom code to the driver to do it. The music was tedious to
                   debug. The other Delta stuff was more conventional - I quite liked the
                   other tunes. Delta was spread over a 2 week period....." (RH)
                   According to Hubbard, Kentilla and Delta were the most complicated one
                   to compose, they took the longest time to do and they both drove him
                   insane.
          (#1)
            TITLE: On the Run [from the Dark Side of the Moon]
            ARTIST: Pink Floyd
          COMMENT: It is more inspired by it than a remix of it.
          (#12)
            TITLE: Koyaanisqatsi [from the movie]
           ARTIST: Philip Glass
          COMMENT: "Inspired by Philip Glass and Pink Floyd." (RH)
       $>

    3) And this prints out all of the BUG entry:

       $> stilview -e=/Hubbard_Rob/Delta.sid -s -o
          (#12)
            BUG: Demo entry.
       $>

AUTHORS
    LaLa <LaLa@C64.org>
        Original author.

    Leandro Nini <drfiemost@users.sourceforge.net>
        Current maintainer.

RESOURCES
    Home page: <https://github.com/libsidplayfp/>
    High Voltage Sid Collection (HVSC): <http://hvsc.c64.org/>

COPYING
    Copyright (C) 1998, 2002 LaLa
    Copyright (C) 2012-2017 Leandro Nini

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

