bible.1

   1 .\" @(#)$Header: /home/matthew/cvs/bible-kjv-4.10/bible.1,v 2.2 2005/01/22 19:15:02 matthew Exp $
   2 .\"
   3 .\" This file is provided for unrestricted use provided that this
   4 .\" legend is included on all tape media and as a part of the
   5 .\" software program in whole or part.  Users may copy, modify or
   6 .\" distribute this file at will.
   7 .\"             -- Chip Chapin, September 4, 1989
   8 .\"
   9 .TH BIBLE 1 "January 8, 1993"
  10 .SH NAME
  11 bible \- Lookup words and verses in the Bible (King James version)
  12 .SH SYNOPSIS
  13 .B bible
  14 .RB [ \-f ]
  15 .RB [ \-l
  16 .IR columns ]
  17 .RB [ \-m
  18 .IR memlimit ]
  19 .RB [ \-p
  20 .IR path-list ]
  21 .RB [ \-d
  22 .IR datafile-name ]
  23 .RI [ verse-reference(s) ]
  24 .SH DESCRIPTION
  25 .I Bible\^
  26 writes the text of specified Bible verses to stdout.
  27 The text used is the Authorized (King James) version.
  28 Commands
  29 may be given either on the command line, or interactively.
  30 .I Bible\^
  31 also supports instant searches for verses containing a particular
  32 word, or combination of words.
  33 The program
  34 uses a specially-compressed form of the text that allows for rapid
  35 random access, while still compressing the original 4.4 Mbyte text into
  36 less than 1.8 Mbytes
  37 (plus the "concordance" data file, which requires nearly 900 Kbytes).
  38 .SS Options
  39 The options to
  40 .I bible\^
  41 are:
  42 .TP 15 "\w'\-t\ prefix\ \ 'u"
  43 .B \-f
  44 Toggles special output formatting (pretty-printing).
  45 By default, pretty-printing is
  46 .B on\^
  47 (a change from earlier versions).
  48 When pretty-printing is
  49 .BR off\^ ,
  50 .I bible\^
  51 precedes each verse with its book/chapter/verse
  52 reference.  When pretty-printing is
  53 .BR on\^ ,
  54 the book name and chapter are printed on a line by themselves,
  55 and only when the chapter or book changes.
  56 The start of each verse is indented and preceded by the verse number.
  57 The book and chapter names are separated from the text
  58 by blank lines to facilitate post-processing by other tools such as
  59 .IR adjust .
  60 Pretty-printing activates automatic line breaks (
  61 .BR \-l )
  62 .TP
  63 .BI \-l \ columns
  64 When pretty-printing is
  65 .BR off ,
  66 .I bible\^
  67 prints one verse per line, even though the text may be much longer than
  68 will fit on a single line of a display.
  69 This is very handy when the output will be processed by other
  70 programs, but it doesn't look very nice.
  71 The
  72 .BR \-l
  73 option sets a limit on the length of an output line, causing
  74 .I bible\^
  75 to break lines (only between words) to fit.  The
  76 .I columns
  77 argument is optional; if it is not specified,
  78 .I bible\^
  79 will use the value of the COLUMNS environment variable
  80 minus one.
  81 If COLUMNS is not set a default value of 79 is used.
  82 .TP
  83 .BI \-m \ memlimit
  84 .I Bible\^
  85 normally allocates up to 1 megabyte for buffers to store uncompressed
  86 text.
  87 If the
  88 .B \-m
  89 option is present,
  90 .I bible\^
  91 will set the limit to
  92 .I memlimit
  93 kilobytes.
  94 .TP
  95 .BI \-p \ path-list
  96 .I Bible\^
  97 normally searches for the text data file first in the current directory,
  98 and then in
  99 .BR /usr/lib .
 100 The
 101 .B \-p
 102 option may be used to change the search path.
 103 .I Path-list
 104 should be a list of directories, each separated by a space (be sure
 105 to escape them from the shell).
 106 .TP
 107 .BI \-d \ filename
 108 .I Bible\^
 109 normally expects to find the text data in a file named
 110 .BR bible.data ,
 111 and the concordance data in
 112 .BR bible.data.conc .
 113 If the
 114 .B \-d
 115 option is present,
 116 .I bible\^
 117 will look for a text data file named
 118 .IR filename ,
 119 and a concordance data file named
 120 .IR filename.conc
 121 instead.
 122 .RE
 123 .SS Verse References
 124 .I Bible\^
 125 accepts verse references in a variety of forms,
 126 including single verses and verse ranges.
 127 For example:
 128
 129     Jn3:16, john3:16,17 ps1:1-6
 130
 131 Most recognizable abbreviations are allowed, and spelling errors are
 132 ignored if the book can be made out in the first few characters.
 133 No distinction is made between upper and lower case.
 134 Multiple references may be provided on an input line, delimited by spaces
 135 or commas.
 136 .PP
 137 Verse and chapter will be silently coerced into a realistic range, e.g.
 138 "Ps1:87" will be treated as Psalm 1:6 since there are only six verses in
 139 Psalm 1, and
 140 "Rev99:99" will be treated as Revelation 22:21 (the last verse in the
 141 Bible).
 142 A book name by itself is assumed to be a reference to chapter 1, verse 1 of that
 143 book, i.e. "Acts" is the same as "Acts1:1".
 144 Similarly, a book and chapter without a verse is assumed to refer to verse
 145 one of that chapter.
 146 .PP
 147 A range of verses may be printed by giving a starting and ending reference,
 148 separated by a hyphen ("-").
 149 For example, "Gen1:1-Rev22:21" will dump the entire text (about 4.4 MB).
 150 .PP
 151 .I Bible\^
 152 keeps track of your current context and will attempt to interpret references
 153 in that context.
 154 For example if you request "John1:1", followed by "3:16", and then "17",
 155 the second reference is assumed to be within the book of John, and the third
 156 is assumed to be within chapter 3 of that book.
 157 An empty reference, e.g. a blank line on the input, will show the
 158 next verse following the last one displayed.
 159
 160 More examples of legal verse references:
 161
 162     psalms1
 163
 164     Psalms
 165
 166     Romans3:23 5:8 6:23
 167
 168     1
 169
 170     5:1
 171
 172     1-22
 173
 174 .SS Concordance (Word Searches)
 175 .I Bible\^
 176 includes a concordance, with which you can immediately find all
 177 the verses in which a word appears.
 178 The
 179 .BI ?? word
 180 command will select all the references that include
 181 .IR word .
 182 .I Bible
 183 will display the number of matching references, if any, but since the
 184 number could be quite large, it won't actually list the references
 185 until you ask.
 186 .PP
 187 In order to list the references from a word search, the
 188 .B ?list
 189 (or
 190 .BR ?l )
 191 command is used.  Likewise, to print the full text of the verses
 192 selected by a word search, use the
 193 .B ?view
 194 (or
 195 .BR ?v )
 196 command.
 197 .PP
 198 The lists for multiple words may
 199 be combined using the
 200 .B ?and
 201 .I word
 202 and
 203 .B ?or
 204 .I word
 205 commands.  First create a reference list using the
 206 .B ??
 207 command.  For example,
 208
 209     ??faith
 210
 211 will find 231 references to the word "faith".  To narrow the list further,
 212 the command
 213
 214     ?and love
 215
 216 will inform you that, while there were 281 references to "love", only
 217 16 of them were also in the previous reference list (i.e. contained
 218 both words).
 219 The "combined list" of 16 references produced by the
 220 .B ?and
 221 .I word
 222 command is the intersection of the two lists, and replaces the
 223 original reference list.
 224 .PP
 225 The
 226 .B ?list
 227 and
 228 .B ?view
 229 commands will now apply to the combined list.  You can continue to apply
 230 the
 231 .B ?and
 232 command to the combined list.  For example,
 233
 234     ?and hope
 235
 236 will further narrow the combined list to only two references.  Typing
 237 .B ?view
 238 then displays the full text:
 239
 240     1 Thessalonians 1
 241
 242       3 Remembering without ceasing your work of faith, and labour of
 243     love, and patience of hope in our Lord Jesus Christ, in the
 244     sight of God and our Father;
 245
 246     1 Thessalonians 5
 247
 248       8 But let us, who are of the day, be sober, putting on the
 249     breastplate of faith and love; and for an helmet, the hope of salvation.
 250 .PP
 251 The
 252 .B ?or
 253 .I word
 254 command is similar to
 255 .BR ?and ,
 256 but it produces a combined reference list that is the union of the two
 257 lists.  In other words, the list includes those verses in which either of
 258 the words appears.  For example
 259
 260     ??angels
 261     ?or angel
 262
 263 will find all 283 verses in wich either word is used.
 264 .PP
 265 By default, reference lists cover the entire Bible.
 266 But for those times when it is useful to limit them to a particular
 267 section of the text,
 268 .B bible
 269 provides the
 270 .B ?in
 271 .I verse range
 272 command.  For example
 273
 274     ?in mt1:1-rev22:21
 275
 276 will limit future reference lists to the New Testament.  If you have a
 277 current reference list, references that fall outside the limits will
 278 be dropped.  Note that only a contiguous range of verses may be used.
 279 To reset the limits so that the whole text is searched, the command is
 280 .B ?in
 281 .BR all .
 282 .SS Interactive Use
 283 For interactive use, invoke
 284 .I bible\^
 285 without any verse references on the command line.  You should see a prompt
 286 displayed:
 287
 288     Bible(KJV) [Gen1:1]>
 289
 290 Typing
 291 .B ?
 292 will print a command summary.
 293
 294 The program accepts three types of interactive command input:
 295 .RS
 296 .TP 3
 297 \(bu
 298 Bible verse references, as described above.
 299 .PD 0
 300 .TP
 301 \(bu
 302 Concordance (word search) commands, also described above.
 303 These commands are:
 304 .BR ?? ,
 305 .BR ?list ,
 306 .BR ?view ,
 307 .BR ?and ,
 308 .BR ?or ,
 309 and
 310 .BR ?in .
 311 .PD 0
 312 .TP
 313 \(bu
 314 Miscellaneous program control commands:
 315
 316 .TP 15 "\w'\-t\ prefix\ \ 'u"
 317 .B ?, ?h, ?help
 318 Prints help text.
 319 .TP
 320 .B ?f
 321 Toggles output formatting modes.
 322 .TP
 323 .BI ?w file
 324 Begin writing program output to a file.  If file exists, output is
 325 appended to what's there already.
 326 .TP
 327 .B ?w
 328 Stop writing to a file.
 329 .TP
 330 .B \>, \<
 331 Toggle the
 332 .I direction
 333 (forward or backward) in which
 334 .I bible
 335 will move through the text when a blank line is entered.
 336 .TP
 337 .B \q, ?bye, ?exit, ?quit, ?q
 338 End the program.
 339 .RE
 340 .PD
 341 .SH BUGS
 342 References to the one-chapter books of Philemon and 3 John
 343 are non-standard in that they require a dummy chapter number.  For
 344 example, use Phm1:5 instead of Phm5 to get verse 5.
 345 .PP
 346 The possessive form
 347 .B 's
 348 is handled strangely by the Concordance.  The apostrophe has been
 349 removed and the
 350 .B s
 351 has been treated as if it were a separate word.
 352 So, for example, if you wanted to find all references to
 353 "refiner's" you would have to first search for "refiner"
 354 (using the command
 355 .BI ?? refiner)
 356 and then combine it with a search for "s"
 357 .RB ( ?and
 358 .IR s ).
 359 .PP
 360 The convention for handling partial verse specifications can be
 361 clumsy.  A book name by itself, e.g. "Matthew" is taken as a reference to
 362 verse 1:1 of that book.  So
 363 .B ?in
 364 .I matt
 365 results in a range limit of a single verse (Mt1:1) instead of the
 366 whole book as one might hope.  Similarly,
 367 .B ?in
 368 .I mt-rev
 369 results in a range of Matthew 1:1 to Revelation 1:1, instead of extending
 370 all the way to Revelation 22:21.
 371 .SH FILES
 372 /usr/lib/bible.data
 373 .br
 374 /usr/lib/bible.data.conc
 375 .SH SEE ALSO
 376 Rev3:20
 377 .SH AUTHOR
 378 Chip Chapin, Hewlett Packard Company (chip@cup.hp.com).
 379 .PP
 380 The current version uses Lempel-Ziv-Welch compression on the data file,
 381 though I modified the "compress" program to emit checkpoints at known intervals
 382 to facilitate random access to the data.
 383 I call this simple technique "windowed compression", and it could be used for
 384 any similar application.
 385 The data file can still be uncompressed using the standard "compress"
 386 utility if my file header is removed.
 387 .PP
 388 I would like to gratefully acknowledge the contribution of the authors of the
 389 .I compress
 390 program, which I modified for use in the text storage component of
 391 .IR bible .
 392 As listed
 393 in the
 394 .I compress
 395 sources they are:
 396 Spencer W. Thomas,
 397 Jim McKie,
 398 Steve Davies,
 399 Ken Turkowski,
 400 James A. Woods,
 401 Joe Orost.
 402 .PP
 403 Matthew Vernon <matthew@debian.org> has substantially updated a the
 404 code of this package. His alterations are made available under the
 405 terms of the GNU General Public Licence, version 2 or later, as
 406 published by the Free Software Foundation.
 407
 408
 409
 410
 411