Provided by: sidplayfp_1.4.4-1_amd64 bug

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

       SourceForge project: <http://sourceforge.net/projects/sidplay-residfp/>
       High Voltage Sid Collection (HVSC): <http://hvsc.c64.org/>

COPYING

       Copyright (C) 1998, 2002 LaLa
       Copyright (C) 2012-2016 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.