home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / MISC / vh_1.4.lzh / VH / vh.1 < prev    next >
Text File  |  1994-02-10  |  8KB  |  177 lines
  1. .TH VH 1 "10 May 1993" "UNIX"
  2. .IX "vh" "" "vh \(em -- volks-hypertext browser for the Jargon File"
  3. .ds ud /usr/lib/vh
  4. .ds fv "2.9.6
  5. .SH NAME
  6. vh \- volks-hypertext browser for the Jargon File
  7. .SH SYNOPSIS
  8. \fBvh\fR [-cfgimrs] [-b key] [document]
  9. .SH DESCRIPTION
  10. This program is a handy hypertext browser, originally written for the
  11. Jargon File but convenient for use with text files marked up in the
  12. simple format dcumented below.  It allows you to page forward and back
  13. through a document, and supports reference chasing so that you can
  14. easily follow chains of "See" and "See also" pointers through the
  15. text.
  16.  
  17. Normal usage is simply to type the name of your document to the shell.
  18. Thus, `jargon' browses the Jargon File.  Interactive help explaining
  19. the keyboard commands is available from the screen.  If the program
  20. sees a mouse, a fairly complete `point-and-shoot' interface is also
  21. available.  Color will be used if it is available, but may be
  22. suppressed with the -m option.  If you are using this program under
  23. DOS and your CGA develops snow when the video RAM is written directly,
  24. use -s.
  25.  
  26. It is useful to know that there are two modes; one browses the text
  27. file, the other the entry index (if you chase a selection in the entry
  28. index you are popped to text mode at the corresponding entry).
  29. .SH MOUSE USAGE
  30. The following section applies only to systems with attached and active
  31. mice.  If you are using a Mac or some other system with a deficient
  32. mouse, the single mouse button is treated as a `left' button.
  33.  
  34. You will notice a scrollbar on the right edge of the screen.  One of
  35. the characters of the scrollbar is different from the rest.  This is
  36. called the `thumb' or `scroll box'.  As you move through the file, this
  37. gives you an approximate indication of where you are in the file.  If
  38. the thumb is one-third of the way down the screen, you are about
  39. one-third of the way through the file.  It works in both the text and
  40. index files.
  41.  
  42. If you have a mouse, you can click the left button directly on a
  43. reference on the screen and jump to it.  You can also scroll or
  44. page forward or backward by clicking on the scrollbar.  There are
  45. up and down arrows above and below the scroll bar for scrolling
  46. line by line.  Clicking on the scrollbar below the thumb will
  47. page forward, and clicking above it will page back.  You can also
  48. "drag" the thumb by clicking on it and holding, then moving up or
  49. down before releasing.  This allows you to jump quickly through
  50. the file.  Holding the mouse down on the arrows or above or below
  51. the thumb will cause the scrolling or paging action to repeat
  52. until you release the button.  This is one of only two places where
  53. holding the button has any special effect (the other is described below).
  54.  
  55. Clicking the right button will cause the program to backtrack the
  56. same way as the Esc or Backspace keys.
  57.  
  58. You may also click the left button on the function key prompts on
  59. the bottom line to get the same effect as pressing the function
  60. keys themselves.  The ^Q (Help) entry is special; if you click it
  61. with the mouse, it will come up, but disappear when you let go of the
  62. mouse button.  This is a feature, not a bug; if you want help to hang
  63. out till you tell it to go away, type control-Q.
  64.  
  65. In the text file only, if you click on the main screen (i.e. not
  66. on the scrollbar or the prompt line) outside of a reference in
  67. curly braces, the program will page forward one screen.
  68.  
  69. The -i option enables an incremental-lookup feature (but note that
  70. this feature may not be available in all ports).  In this mode, lookup
  71. and string search both behave like an Emacs incremental search.  That
  72. is, after you type each letter of a key, your viewpoint moves forward
  73. to the next key (if any) containing the substring you've already typed.  If
  74. there is no such key, the browser beeps and drops out of
  75. incremental-lookup mode.  String search works similarly, behaving
  76. almost exactly like an Emacs ^S.  As a reminder that you're in these
  77. incremental modes, highlights do not light up on the screens you pass
  78. through; when you want to leave the mode, press enter and the current
  79. page's highlights will light up.
  80.  
  81. The -b option runs vh in batch mode to retrieve the entry
  82. corresponding to a particular given key.  The entry, if any, is
  83. written to standard output.
  84.  
  85. The -f (filter) option accepts a list of entry headwords on stdin and
  86. sends those entries to stdout.
  87.  
  88. Finally, the -r option picks an entry at random and sends it to
  89. standard output.  This may be useful for `fortune cookie' applications.
  90. .SH INDEX GENERATION
  91. Two data files, the default text and index for the Jargon File, should live
  92. in \*(ud.  To generate an index from a new version, cd to this library
  93. directory.  Copy or move the textfile to \*(ud/jargon.txt and run the
  94. command
  95. .B jargon -g.
  96.  
  97. For experimental purposes, it is possible to override the default
  98. document name with a command-line argument.  Thus, assuming a file
  99. .B example.tex
  100. is in proper format, you may generate an index for
  101. .I example.txt
  102. with
  103. .B vh -g example
  104. and browse it with
  105. .B vh example
  106. .P
  107. When you have the `example' database ready for public use, simply link
  108. or copy vh to the name `example'.  If no arguments are given, this
  109. program tries to browse a database with the name it was invoked under.
  110.  
  111. The -c mode does some format and consistency checks on a text/index
  112. pair.  Use this if it looks as though your lookups are landing in the
  113. wrong places; it will let you know if your index is out of date.
  114. .SH TEXT FILE FORMAT
  115. `Proper format' means:
  116.  
  117. 1. References are surrounded by {} or {{}}.
  118.  
  119. If the first character of the text file is not a `=', the code also assumes:
  120.  
  121. 2. Reference targets begin with a `:' at the left margin and are bounded
  122. on the right by another `:' (an optional second `:' may follow that).
  123.  
  124. This second rule is useful for filtering out false hits from the index.
  125. .SH FILES
  126. A copy of vh called  `foo' would require the following:
  127. .TP 3.5i
  128. .I \*(ud/foo.txt
  129. Text of your document.
  130. .TP 3.5i
  131. .I \*(ud/foo.idx
  132. Index of your document.
  133. .TP 3.5i
  134. .I ./foo.cut
  135. Where entries selected by the ^Y (Print) command are appended to.
  136. .P
  137. The Jargon File can be obtained by FTP from various archive sites.
  138. A copy lives more or less permanently as
  139. .I pub/jargon298.ascii
  140. at
  141. .I prep.ai.mit.edu
  142. (18.71.0.38).
  143. Future updates will be made available there.
  144. .SH ENVIRONMENT VARIABLES
  145. .TP 3.5i
  146. .I VHPATH
  147. Search path for vh documents. Defaults to ".:/usr/lib/vh"
  148. .SH BUGS
  149. If a selection wraps around the right margin, only a mouse click on
  150. the part before the line wrap will chase it; clicks on the portion
  151. trailing into the next line simply cause a page forward.  This glitch
  152. was judged more trouble to fix than it's worth.
  153.  
  154. Use of the ESC key inhibits refresh under some curses(3) versions;
  155. thus, you might have to do a ^L to force screen update afterwards.
  156. Crocking around this in the obvious way would introduce screen flicker for
  157. everybody.  Use BS.
  158.  
  159. Because UNIX's pseudorandom-number generator isn't very good, the
  160. fortune-cookie mode under UNIX isn't either.
  161.  
  162. Output from a -f list may include alphabetical section headers which
  163. are not, strictly speaking, part of the desired text.
  164. .SH AUTHORS
  165. Concept, DOS support, and database code from the MS-DOS `jargon'
  166. program by Raymond D. Gardner <FidoNet 1:104/89.2>; new features,
  167. docs, and curses(3)-using UNIX code by Eric S. Raymond
  168. <eric@snark.thyrsus.com>.
  169. .SH SEE ALSO
  170. .I The New Hacker's Dictionary,
  171. by Eric S. Raymond (ed.), MIT Press 1991, ISBN 0-262-68069-6.  The
  172. Jargon File (version 2.9.6), nicely typeset and bound with additional
  173. front matter.
  174.  
  175. Please email your Jargon File entries and corrections to
  176. jargon@snark.thyrsus.com.
  177.