chiark / gitweb /
Put things into git
[bible-kjv.git] / 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