File Names And Places

Info-Mac Archive File Name and Placement Conventions
revision 17 Jul 93: DRAFT VERSION

--- File Names ----------------------------------------------------------

File Names Must:
  Contain ONLY lowercase letters, numbers, and dashes.
  Begin with a letter, not a number or dash.
  Be 50 characters or less with its directory name(s).
  Use dashes where words are separated (but not too much).
  Exclude periods from version numbers.
  Exclude references to compression software.
  End with one of the following suffixes:
    .hqx  Binhexed
    .txt  text 
   .shar  Unix shell archives
     .uu  Unix uuencoded
    .bin  MacBinary format (rarely used)
    .etx  Setext (only for Tidbits issues)
  Some examples:
    DrawNothing 1.41 -> draw-nothing-141.hqx
    doIt Now 0.9b    -> doit-now-09b.hqx
    QuickTime 2.0    -> quicktime-20.hqx

Specific File Format
  To identify the format of the file more specifically than the suffix
  does, use an extension JUST BEFORE the suffix. Some common ones:
  -msdos  MS-DOS program
   -unix  Unix program
     -ps  Postscript code
    -etx  Setext text format
    -msw  Microsoft Word
   -fkey  Mac fkey utility
     -hc  Hypercard stacks

Descriptive Extensions
  Some info about files should be placed in file name extensions:
   -demo  incomplete version for demonstration purposes
   -updt  a utility to update a file to a newer version

References to Common Mac Things
  System software: sys607, sys7, sys701, sys71, sys7-finder
              Not: system-7, system-seven, system7, finder7, finder-7
  Mac models: mac-512, mac-plus, mac-se, mac-ii, se30, iici, lcii
              mac-portable, powerbook, centris-610, quadra-700
         Not: power-book, pb, ii-vx,
  Other software: resedit, quicktime, mactcp
  System operations: startup, shutdown

Date Format
  The format for dates is
    "file-name-YY-MM.???"
  where YY and MM are the numbers of the year and month,
  respectively.  If necessary "-DD" (the day) may be added
  after the month.

Conventions for Specific Directories
  app/ Filemaker stuff should begin with "filemaker-"
  per/ File names should include an issue number or date (not both)
  dev/a4d/ File names should end in one of the following extensions:
     -ext  externals
    -demo  commercial demos
      -db  example databases
    -info  documentation and information
    -util  utilities that don't plug directly into 4D or a database
     -src  native 4d source code
  dev/src/ File names should end in one of the following extensions:
       -c  C source code
     -pas  Pascal source code
    -plog  Prolog source code
  info/ Software and hardware company info should begin with "vendor-"
  info/hdwr/ Specific mac model info should begin with the model name

--- File Placement ---------------------------------------------------

Things should be archived by topic as much as possible.  Some
directories are more specific than others, text/ and prn/ are quite
definite, whereas app/ and cfg/ are more general.  Things should be
placed in the most specific directory appropriate, ie: printer drivers
in prn/, not cfg/.

Generally, information files about software should be archived
together with applications, whereas data (such as sounds and pictures)
should be archived separately.  For example, a picture goes in grf/,
the utility to display it goes in grf/util/ and a review or collection
of tips about that utility also goes in grf/util/.

Hypercard stacks, desk accessories and other apps that provide info
ABOUT MACS should be placed in the appropriate info/ or topic
directory, not in card/ or app/.

--- Archive Directories ------------------------------------------------

A directory at the archive has many components:
+ An entry in directory-contents.txt with a description of the
  directory's intended contents.
+ The directory itself, which is a short 3 or 4 character name.
+ A link to the directory that resides in the same directory as the
  real directory.  Its name is descriptive and capitalized.  If its
  name is two words normally separated by a space, the 2nd word is also
  capitalized.  If its name is 2 words that represent different
  concepts, the 2nd word is capitalized and separated from the 1st by a
  dash.
+ An abstract file in the directory (an empty one must be created when
  a directory is installed).
+ A link to the abstract file that resides in help/abs/.  Its name
  begins with the descriptive name of the parent directory (if any)
  followed by the descriptive name of the directory.  Dashes are used in
  this name to separate words as they are in normal archive files.
+ A directory in the backmod/ar/ hierarchy whose name is the same as
  the directory's actual name.