--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- lifted from man+troff by doclifter -->
+<refentry xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' xml:id='strfileman'>
+<!-- $NetBSD: strfile.8,v 1.3 1995/03/23 08:28:45 cgd Exp $ -->
+
+<!-- Copyright (c) 1989, 1991, 1993
+The Regents of the University of California. All rights reserved. -->
+
+
+<!-- This code is derived from software contributed to Berkeley by
+Ken Arnold. -->
+
+<!-- Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+3. All advertising materials mentioning features or use of this software
+must display the following acknowledgement:
+This product includes software developed by the University of
+California, Berkeley and its contributors.
+4. Neither the name of the University nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission. -->
+
+<!-- THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE. -->
+
+<!-- @(#)strfile.8 8.1 (Berkeley) 6/9/93 -->
+
+<!-- This man page has been heavily modified, like the files it refers
+to, by Amy Lewis. Changes to command line, and a different style of
+macros for Linux systems. -->
+
+<refmeta>
+<refentrytitle>STRFILE</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='source'>June 9, 1993 [Apr. '97]</refmiscinfo>
+<refmiscinfo class='manual'>4th Berkeley Distribution</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>strfile</refname>
+<refpurpose>create a random access file for storing strings</refpurpose>
+</refnamediv>
+<refnamediv>
+<refname>unstr</refname>
+<refpurpose>dump strings in pointer order</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+<refsynopsisdiv xml:id='synopsis'>
+<cmdsynopsis>
+ <command>strfile</command> <arg choice='opt'>-iorsx </arg>
+ <arg choice='opt'><arg choice='plain'>-c </arg><arg choice='plain'><replaceable>char</replaceable></arg></arg>
+ <arg choice='plain'><replaceable>sourcefile</replaceable></arg>
+ <arg choice='opt'><replaceable>outputfile</replaceable></arg>
+</cmdsynopsis>
+<cmdsynopsis>
+ <command>unstr</command> <arg choice='opt'><arg choice='plain'>-c </arg><arg choice='plain'><replaceable>char</replaceable></arg></arg>
+ <arg choice='plain'><replaceable>datafile.[ext]</replaceable></arg>
+ <arg choice='opt'><replaceable>outputfile</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 xml:id='description'><title>DESCRIPTION</title>
+<para><emphasis role='strong' remap='B'>strfile</emphasis>
+reads a file containing groups of lines separated by a line containing
+a single percent `%' sign (or other specified delimiter character) and
+creates a data file which contains a header structure and a table of
+file offsets for each group of lines. This allows random access of the
+strings.</para>
+
+<para>The output file, if not specified on the command line, is named
+<emphasis remap='I'>sourcefile.dat</emphasis>.</para>
+
+<para>The purpose of
+<emphasis role='strong' remap='B'>unstr</emphasis>
+is to undo the work of
+<emphasis role='strong' remap='B'>strfile</emphasis>.
+It prints out the strings contained in the sourcefile, which is
+<emphasis remap='I'>datafile.ext</emphasis>
+without its extension, or
+<emphasis remap='I'>datafile</emphasis>
+if no extension is specified (in this case, the extension
+<markup>.dat</markup>
+is added to the name of the datafile) in the order
+that they are listed in the header file
+<emphasis remap='I'>datafile</emphasis>.
+If no
+<emphasis remap='I'>outputfile</emphasis>
+is specified, it prints to standard output; otherwise it prints
+to the file specified.
+<emphasis role='strong' remap='B'>unstr</emphasis>
+can also universally change the delimiter character in a strings file.
+It is possible to create sorted versions of input files by using
+<emphasis role='strong' remap='B'>strfile -o</emphasis>
+and then using
+<emphasis role='strong' remap='B'>unstr</emphasis>
+to dump them out in the table order.</para>
+
+<refsect2 xml:id='options'><title>Options</title>
+<para>The options are as follows:</para>
+<variablelist remap='TP'>
+ <varlistentry>
+ <term><emphasis role='strong' remap='B'>-c </emphasis><emphasis remap='I'>char</emphasis></term>
+ <listitem>
+<para>Change the delimiting character from the percent sign to
+<emphasis remap='I'>char</emphasis>.
+This option is available for both
+<emphasis role='strong' remap='B'>strfile</emphasis> and <emphasis role='strong' remap='B'>unstr</emphasis>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role='strong' remap='B'>-i</emphasis></term>
+ <listitem>
+<para>Ignore case when ordering the strings.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role='strong' remap='B'>-o</emphasis></term>
+ <listitem>
+<para>Order the strings in alphabetical order. The offset table will be
+sorted in the alphabetical order of the groups of lines referenced.
+Any initial non-alphanumeric characters are ignored. This option
+causes the STR_ORDERED bit in the header
+<emphasis remap='I'>str_flags</emphasis>
+field to be set. (It also now really does sort! It didn't used to).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role='strong' remap='B'>-r</emphasis></term>
+ <listitem>
+<para>Randomize access to the strings. Entries in the offset table will be
+randomly ordered. This option causes the STR_RANDOM bit in the header
+<emphasis remap='I'>str_flags</emphasis>
+field to be set. (And really does randomize)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role='strong' remap='B'>-s</emphasis></term>
+ <listitem>
+<para>Run silently; don't give a summary message when finished.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role='strong' remap='B'>-x</emphasis></term>
+ <listitem>
+<para>Note that each alphabetic character in the groups of lines is rotated
+13 positions in a simple caesar cypher. This option causes the
+STR_ROTATED bit in the header
+<emphasis remap='I'>str_flags</emphasis>
+field to be set. Note that it
+<emphasis role='strong' remap='B'>does not</emphasis>
+rotate the strings--that operation must be performed separately.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 xml:id='header'><title>Header</title>
+<para>The format of the header is:</para>
+
+<para>#define VERSION 1
+<!-- br -->
+unsigned long str_version; /* version number */
+<!-- br -->
+unsigned long str_numstr; /* # of strings in the file */
+<!-- br -->
+unsigned long str_longlen; /* length of longest string */
+<!-- br -->
+unsigned long str_shortlen; /* shortest string length */
+<!-- br -->
+#define STR_RANDOM 0x1 /* randomized pointers */
+<!-- br -->
+#define STR_ORDERED 0x2 /* ordered pointers */
+<!-- br -->
+#define STR_ROTATED 0x4 /* rot-13'd text */
+<!-- br -->
+unsigned long str_flags; /* bit field for flags */
+<!-- br -->
+char str_delim; /* delimiting character */</para>
+
+<para>All fields are written in network byte order.</para>
+</refsect2>
+</refsect1>
+
+<refsect1 xml:id='bugs'><title>BUGS</title>
+<para>Fewer now, one hopes. However, fortunes (text strings) beginning with a
+blank line appear to be sorted between random letters. This includes
+ASCII art that contains no letters, and first lines that are solely
+non-alphanumeric, apparently. I've no idea why this should be.</para>
+</refsect1>
+
+<refsect1 xml:id='other_uses'><title>OTHER USES</title>
+<para>What can you do with this besides printing sarcastic and obscene messages
+to the screens of lusers at login or logout?</para>
+
+<para>There
+<emphasis role='strong' remap='B'>are</emphasis>
+some other possibilities. Source code for a sample program,
+<emphasis role='strong' remap='B'>randstr</emphasis>,
+is included with this distribution: randstr splits the difference between
+<emphasis role='strong' remap='B'>unstr</emphasis> and <emphasis role='strong' remap='B'>fortune</emphasis>.
+It reads a single, specified file, and randomly selects a single text
+string.</para>
+<variablelist remap='IP'>
+ <varlistentry>
+ <term>1</term>
+ <listitem>
+<para>Include
+<emphasis remap='I'>strfile.h</emphasis>
+into a news reading/posting program, to generate random signatures.
+<citerefentry><refentrytitle>Tin</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+does something similar, in a much more complex manner.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>2</term>
+ <listitem>
+<para>Include it in a game. While strfile doesn't support 'fields' or
+'records', there's no reason that the text strings can't be consistent:
+first line, a die roll; second line, a score; third and subsequent lines,
+a text message.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>3</term>
+ <listitem>
+<para>Use it to store your address book. Hell, some of the guys I know
+would be as well off using it to decide who to call on Friday nights (and
+for some, it wouldn't matter whether there were phone numbers in it or not).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>4</term>
+ <listitem>
+<para>Use it in 'lottery' situations. If you're an ISP, write a script to
+store login names and GECOS from
+<filename>/etc/passwd</filename>
+in strfile format, write another to send 'congratulations, you've won'
+to the lucky login selected. The prize might be a month's free service,
+or if you're AOL, a month free on a real service provider.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 xml:id='see_also'><title>SEE ALSO</title>
+<para><citerefentry><refentrytitle>byteorder</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>fortune</refentrytitle><manvolnum>6</manvolnum></citerefentry></para>
+</refsect1>
+
+<refsect1 xml:id='history'><title>HISTORY</title>
+<para>The
+<emphasis role='strong' remap='B'>strfile</emphasis>
+utility first appeared in 4.4BSD. This version was heavily modified,
+much of it in ways peculiar to Linux. Work has since been done to make
+the code more generic, and has so far been tested to work with SunOS
+4.x. More platforms are expected to be supported as work continues.</para>
+</refsect1>
+</refentry>
+
projects / fortune-mod / commitdiff