." tirph.1 - tirph man page                           -*-nroff-*-
." 2010/9/7 David Meyer <papa@freeshell.org>  +JMJ
.TH tirph 1 "September 7, 2010" "Version 1.0" "Project TWENEX"
.SH NAME
tirph \- Generate TIR gophermap from directory
.SH SYNOPSIS
.B tirph 
[\-CPVh] [\-n 
.I phlog-count
] [\-o 
.I output-file
] [\-p 
.I phlog-directory
] [
.I directory
]
.SH DESCRIPTION
Generate a gophermap menu for
.I directory
(defaults to the nexus directory (See DIRECTORY STRUCTURE). If
specified, must be base name of subdirectory in nexus (without slash
characters)) with the following contents:
.TP
0. Title
contents of file directory/.title (null if file absent). A one-line
title for
.I directory.
.TP
1. Description
contents of file directory/.description (null if file absent). An
extended description of 
.I directory
's purpose, contents, or other information.
.TP
2. Nexus link
link to nexus directory (See DIRECTORY STRUCTURE) (null for nexus 
gophermap)
.TP
3. Gopher header
contents of file directory/.gophhead (null if file absent). Gopher
menu-specific links, explanatory text, or other information.
.TP
4. Phlog
menu of recently added or changed files in the file system subtree of
.I phlog-directory.
.TP
5. Directory contents
menu of files and subdirectories of
.I directory.
.TP
6. Exits
menu of nexus subdirectories listed in file directory/.exits (null if
file absent). See EXITS.
.TP
7. Gopher footer
contents of file directory/.gophfoot (null if file absent). Gopher
menu-specific links, explanatory text, or other information.
.TP
8. Nexus link
link to nexus directory (See DIRECTORY STRUCTURE) (null for nexus 
gophermap)
.TP
9. Fortune
random fortune
.SH OPTIONS
.TP
\-p phlog-directory
root directory for files subject to listing in the phlog
section. Defaults to nexus directory.
.TP
\-n phlog-count
number of entries to be listed in phlog section. Defaults to 10.
.TP
\-o output-file
base name of file in directory for output gophermap entries. Defaults
to gophermap.
.TP
\-C
suppress output of directory contents section.
.TP
\-P
suppress output of phlog section.
.TP
\-V
display version number
.TP
\-h
display short help message
.SH DIRECTORY STRUCTURE
The nexus directory is the root directory of a user's subtree within
the Gopher server file system (/ftp/pub/users/$USER on SDF). A user's
Gopher subsite consists of his nexus directory, its subdirectory
hierarchy, and all files in that hierarchy. tirph-generated menus are
independent for each user's subsite.
.SH EXITS
Exits are gopher menu items that link to other subdirectories under
the same nexus independently of file system hierarchy and
links. Exits may be used to emulate a connection network like that
between virtual locations/rooms in a MUD.
.PP
Exits are generated for a directory's gophermap from entries a file
named .exits in the directory itself. Entries are comprised of a
single line of text in the following format:
.PP
.I subdirectory [ exit-tag ]
.PP
Where
.I subdirectory
is the base name (without slashes) of the target nexus subdirectory,
and 
.I exit-tag
is an optional string to be prepended to the subdirectory's title in
the exit menu entry.
.SH FILE TITLES
tirph derives titles for listed files by different methods depending
on the file's type and extension:
.TP
directories
contents of the first line of the directory's .title file, if
present. Otherwise, the directory's base name.
.TP
txt, org, blink
contents of the first line of the file.
.TP
html, htm, shtml
contents of the <H1> tag occurring in the file.
.TP
other
the file's base name.
.SH BLINK FILES
Blink (weB LINK) files are a means of storing references to WWW
resources. blink files are plain text files with a title for the
reference on the first line, the resource URI on the second line,
optionally followed by one or more commentary lines. Blink files are
identified by the file extention ".blink".
.PP
When tirph lists a blink file in the phlog or directory contents
section, it uses a selector linking to the web resource the blink
file references rather than to the blink file itself. 
.SH FILES
.TP
directory/.title
directory title
.TP
directory/.descripton
directory description
.TP
directory/.gophhead
gopher-specific header for directory
.TP
directory/.gophfoot
gopher-specific header for directory
.TP
directory/.exits
list of connected nexus subdirectories
.SH AUTHOR
David Meyer <papa@freeshell.org>