home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 635.lha / ht_v3.2 / HyperText.htx < prev    next >
Text File  |  1992-03-29  |  18KB  |  473 lines
  1. \s "CONFIG"
  2. PSHTS"HypertextGfx/SHTS.pic"
  3. PSignature"HypertextGfx/Signature.pic"
  4. \e
  5.  
  6. \s "START"
  7.                          \p"SHTS"
  8.  
  9.  
  10.  
  11.                         \u\c3"The Simple HyperText System"\c1\n
  12.                                    v3.1
  13.                                     by
  14.                              \p"Signature"\l"Signature"                \l
  15.                              \l"Signature"                \l
  16.     The \uSimple HyperText System\n (SHTS) is an easy way to create \b\l"Text"text\l\n files
  17. containing \b\l"HyperText"hypertext\l\n links. I'm lousy at writing docs, so rather than
  18. explaining this, I'll demonstrate it. Click on any boldface word on this
  19. page. Then click on \b\l"Prev"'Previous page'\l\n at the bottom of the screen.
  20.  
  21.     Easy, huh?
  22.  
  23.     Some pages (like this one) are larger than the screen size. Look in the
  24. row at the bottom of the screen. You should see the words 'Up' and 'Down'.
  25. If one of these is in boldface, there is more text visible. Click on 'Up'
  26. or 'Down' to scroll the page. Alternatively, just click when the pointer
  27. appears as an arrow to scroll in the direction of the arrow.
  28.  
  29.     OK, here's the \ureal\n manual:
  30.  
  31.             \b\l"Setup"Setting up the SHTS program\l\n
  32.  
  33.             \b\l"Operation"How to use the SHTS program\l\n
  34.  
  35.             \b\l"Creation"Creating HyperText files\l\n
  36.  
  37.             \b\l"Bugs"Bugs\l\n
  38.  
  39.             \b\l"History"Revision History\l\n
  40.  
  41.             \b\l"Future"Things to Come\l\n
  42.  
  43.             \b\l"Credits"Where to send praise, flames, etc...\l\n
  44.  
  45.             \b\l"Index"Index\l\n
  46. \e
  47.  
  48. \s "Signature"
  49. If you're wondering if my signature \ureally\n looks like that, it does. Of
  50. course, the fact that I can't draw didn't help me when I tried to draw the
  51. computer image.
  52.                                 \p"Signature"
  53. \e
  54.  
  55. \s "HyperText"
  56. \uHypertext\n
  57.  
  58.     Hypertext looks like standard text. However, when you select a word or
  59. phrase in it, it cross-references to another section of text and displays
  60. that. This makes hypertext especially useful for reference works. However,
  61. almost anything can benefit from hypertext.
  62. \e
  63.  
  64. \s "Text"
  65. \uText\n
  66.  
  67.     By text, I mean plain, vanilla, ASCII text.
  68. \e
  69.  
  70. \s "Prev"
  71. \uPrevious Page\n
  72.  
  73.     Selecting 'Previous Page' moves you to the last page you were looking
  74. at. Selecting it again goes one past that, and so on. SHTS stores a list
  75. of the last 20 pages you were at.
  76. \e
  77.  
  78. \s "Setup"
  79. \uSetting up the SHTS program\n
  80.  
  81.     The introduction of graphics into the SHTS has  regrettable made it
  82. somewhat more complicated. (But still not \utoo\n complicated! :-) I am now
  83. using \b\l"iff.library"iff.library\l\n to display pictures. I would rather use the standard
  84. system calls, but I can't get them to work, and \b\l"iff.library"iff.library\l\n is simpler
  85. anyway.
  86.  
  87.     Therefore, you need to copy iff.library to your libs: directory. (Of
  88. course, since the program won't run without it there, you must already have
  89. done this.)
  90.  
  91.     In addition, a SHTS file that uses graphics in it will need to have the
  92. graphics files where it can find them. This file expects them to be in a
  93. directory names "HypertextGfx". For neatness, you may wish to place all
  94. graphics files in a directory with "HypertextGfx:" assigned to it. In fact,
  95. I hereby recommend that anyone who makes a SHTS file with graphics have the
  96. file look for pictures in "HypertextGfx:".
  97. \e
  98.  
  99. \s "Operation"
  100. \uHow to use the SHTS program\n
  101.  
  102.     By this point, you already know the basics of SHTS. Since there isn't
  103. much to SHTS but the basics, that makes you an expert already! :-) However,
  104. I'll go over even the simple stuff here.
  105.  
  106.     To start SHTS, just type 'hypertext' from a CLI. The command line format
  107. is:
  108.  
  109.             Hypertext [i] <filename>
  110.  
  111.     If you do not specify a filename, SHTS will use a file requester to ask
  112. you for one.
  113.     The i option causes SHTS to load in interlace mode.
  114.  
  115.     By clicking on a word on the screen that has a link attached to it, you
  116. move to a different page. The convention is that words in boldface have links
  117. attached to them. However, authors of SHTS files may not follow this rule.
  118. (Although I hope that everyone does.) Whenever you move the mouse over a word
  119. with an attached link, the pointer will change to a crosshairs.
  120.  
  121.     If a page is larger than the screen size, clicking on the words 'Up' and
  122. 'Down' at the bottom of the screen will scroll the page. If either word is in
  123. boldface, there is more text to be seen in that direction. If the mouse is
  124. over the text and not over a link, it will appear as an arrow. Clicking the
  125. mouse when the arrow is showing will scroll the text in the direction of the
  126. arrow.
  127.     A note on the arrows: the hotspot on them is located in the center of the
  128. pointer, not at the tip of the arrow. I have found that this placement offers
  129. the best 'feel' to the interface.
  130.  
  131.     Clicking on 'Previous Page' at the bottom of the screen will move you
  132. back to the last page you viewed. Pressing it again will move you one page
  133. before that, and so on. A list of the last 20 pages you viewed is stored.
  134.  
  135.     Clicking on 'Restart' at the bottom of the screen will jump you to the
  136. first page in the file.
  137.  
  138.     Clicking on 'Load' at the bottom of the screen will bring up a file
  139. requester. Select a file from there to load it. WARNING: my implementation
  140. here is less than perfect. If you select 'Cancel', you will not return to the
  141. file you were viewing; instead, the program will quit.
  142. \e
  143.  
  144. \s "Bugs"
  145. \uBugs\n
  146.  
  147.     I know of only one bug in SHTS right now, and I'm not certain if the
  148. problem lies in the program or my system.
  149.  
  150.     When using CSH, starting SHTS with the CSH run or rback commands will
  151. crash the system. I have been unable to find any reason for this. If anyone
  152. out there can tell me what is going wrong, I'll try to fix it.
  153.  
  154.     One bug that you may experience that is \unot\n in SHTS involves using the
  155. Magic File Requester by Stefan Stuntz. Whenever the MFR is invoked, the
  156. system loses a kilobyte or two of memory. I am documenting this here so that
  157. people with the MFR don't think that it's \umy\n program that's buggy! :-)
  158. \e
  159.  
  160. \s "iff.library"
  161. \uiff.library\n
  162.  
  163.     Iff.library is a library (what else?) by Christian A. Weber. It makes the
  164. task of using IFF format files simple for the programmer. The library is very
  165. small, making it a painless addition to the system. I am using iff.library
  166. because I cannot figure out the 2.0 iffparse.library.
  167.  
  168.     \uWARNING!\n The version of iff.library included with this archive is \unot\n
  169. the latest version. I don't have the latest version. The archive which I got
  170. this out of was on an AmigaWorld Tech Journal disk. Everything in the archive
  171. was for the latest version, except the library itself. Go figure.
  172. \e
  173.  
  174. \s "Creation"
  175. \uCreating HyperText files part I -- Pages\n
  176.  
  177.     My hypertext files are organized into "pages". You can view one page
  178. at a time. Selecting a link opens another page. Selecting \b\l"Prev"'Previous Page'\l\n
  179. bounces you back to the last page you were at.
  180.  
  181.     Each SHTS page has a name. The reader does not look at this name. This
  182. is used to specify where a link is going. The first page displayed is named
  183. "START". There \imust\n be a page named START in the file. Case counts!
  184.  
  185.     To specify the start of a page in the file, create a line like this:
  186. \\s "START"
  187.  
  188.     Whatever is inside the quotes is the name of your page.
  189.     To end a page, create a line like this:
  190. \\e
  191.  
  192.     A page may have any number of lines.
  193.                                                             \b\l"Creation2"Continue...\l\n
  194. \e
  195.  
  196. \s "Creation2"
  197. \uCreating HyperText files part II -- Type styles\n
  198.  
  199.     Text in the page may be set in different type styles. The control
  200. commands for changing type style are:
  201.  
  202.             \\n -- normal
  203.             \\u -- \uunderlined\n
  204.             \\b -- \bbold\n
  205.             \\i -- \iitalic\n
  206.  
  207.     Just embed any of those sequences in your text to change the style.
  208.  
  209.     You may also change the color of your text. The command for changing the
  210. text color is: \\c#. '#' may be 0, 1, 2, or 3. These numbers correspond to
  211. the following numbers:
  212.  
  213.             0 - grey
  214.             1 - black
  215.             2 - white
  216.             3 - blue
  217.  
  218.     To print a '\\', use two backslashes one after the other, like this: \\\\.
  219.  
  220.                                                              \b\l"Creation3"Continue...\l\n
  221. \e
  222.  
  223. \s "Creation3"
  224. \uCreating HyperText files part III -- Links\n
  225.  
  226.     A hypertext link is created in much the same way as type styles are set.
  227.     You start and end links with:   \\l
  228.     After the first \\l, you must specify a page to link to. Put the name
  229. of the page in quotes.
  230.  
  231.     Example of a hypertext link:
  232.             \\l"Page 1"This will link to page 1.\\l
  233.  
  234.     This will display the text "This will link to page 1.", and when clicked
  235. on will jump to the page named "Page 1".
  236.     You should put links in boldface to show the reader that they are links.
  237.  
  238.     Beware! It is possible to create a link that encompasses several lines.
  239. This seems to interfere with screen display. I hope to fix this at some
  240. point, to allow links with height as well as length. For now, however, \udo not
  241. create multiline links\n!
  242.  
  243.                                                              \b\l"Creation4"Continue...\l\n
  244. \e
  245.  
  246. \s "Creation4"
  247. \uCreating HyperText files part IV -- Graphics\n
  248.  
  249.     You may include \b\l"ILBM"ILBM\l\n format files in the text. This is a two-step
  250. process: first you must declare the files to use. Second, you place the
  251. pictures in the text.
  252.  
  253.     Currently, only four-color pictures are allowed. This will change. The
  254. colors are restricted to the standard Workbench colors. I realize that this
  255. limits the usefulness of this feature. As I said: this will change.
  256.  
  257.     Pictures \ualways\n appear on top of text.
  258.  
  259.     Brushes are fine.
  260.  
  261. \uSTEP 1: Declaring the files\n
  262.  
  263.     I have added a section to SHTS files specifically for this purpose. This
  264. section is a page names "CONFIG". If there is no CONFIG page, SHTS will
  265. assume that there are no pictures. Eventually, I will expand the config page
  266. to include other options.
  267.  
  268.     To load a picture, begin a line in the CONFIG page with 'P'. The P \umust\n
  269. be capitalized. \uImmediately\n after the P, type the name by which the picture
  270. will be known. After the name, place the name of the picture to be loaded,
  271. surrounded by quotes.
  272.  
  273.     Here is an example from this file:
  274.  
  275. PSignature"HypertextGfx/Signature.pic"
  276.  
  277.     This declares a picture names "Signature" (case counts) from the file
  278. Signature.pic in the HypertextGfx directory.
  279.  
  280. \uSTEP 2: Placing the picture\n
  281.  
  282.     Placing the picture is very easy. Place a \\p in the text. Follow it
  283. with the name of the picture, in quotes.
  284.  
  285.     An example:
  286.  
  287.         Here is my signature: \\p "Signature"
  288.  
  289.     This will produce the following:
  290.  
  291.         Here is my signature: \p "Signature"
  292.  
  293.  
  294.     Course completed. Click here \b\l"START"[ ]\l\n to go to the start of the file.
  295. \e
  296.  
  297. \s "CATS"
  298. \uCATS\n
  299.  
  300.     Commodore Amiga Technical Services
  301. \e
  302.  
  303. \s "ILBM"
  304. \uILBM files\n
  305.  
  306.     ILBM stands for \uI\nnter\ul\neaved \uB\nit\um\nap.
  307.  
  308.     ILBM files are a varient of the IFF format. They are used to store
  309. graphics. The files that DeluxePaint saves are in ILBM format.
  310.  
  311.     For more information, send $20 to \b\l"CATS"CATS\l\n, and you will learn everything
  312. you ever wanted to know about IFF and ILBM, and more.
  313. \e
  314.  
  315. \s "Credits"
  316. \uCredits\n
  317.  
  318.     This program was entirely made by me, Damien Neil.
  319.  
  320.     Please send me a message telling me if you like it, and what you think
  321. I should add to it. This is the first program I have made and distributed.
  322. I really want to know what people think of it.
  323.  
  324.     This is public domain. You may do anything with it that you want to,
  325. including selling it for large sums of money. (Of course, if anyone asks
  326. \ume\n for it, I'll send it to them for $1, that being about the cost of a disk
  327. and postage.)
  328.  
  329.     I take \uno\n responsability for anything this program does to you. If it
  330. reformats your hard drive, too bad. (It won't though :-)
  331.  
  332.     I reserve the right to release yet another version every few days. :-)
  333.  
  334.     If you want the source code, ask for it and I'll send it to you. However,
  335. if you are a beginning programmer, you \udon't\n want it. Trust me. It'll give
  336. you bad habits you'll be trying to get rid of for the rest of your life. :-)
  337. (Assuming, of course that you can understand >1000 lines of code with \uno\n
  338. comments...)
  339.  
  340. My address: Damien Neil             A.NEIL2 (on GEnie)
  341.             320 Wells Hill Rd.
  342.             Lakeville, CT
  343.             06039
  344. \e
  345.  
  346. \s "History"
  347. \uHistory\n
  348.  
  349.     3.2     Fixed a nasty bug that cropped up -- I wasn't freeing any of the
  350.             memory I allocated to store the file! (I managed to delete the
  351.             line that called my CloseFile() routine.)
  352.  
  353.             Made a few changes in the algorithm I use to change mouse coords
  354.             to character coords. The previous one was offset upwards a bit.
  355.  
  356.             Changed around the way I close a file a bit. I now free the file
  357.             immediately after reading the data. Before, the file was only
  358.             closed when the user stopped reading it.
  359.  
  360.             As promised, SHTS now has colored text. Quite easy to implement.
  361.  
  362.             SHTS can now be run in interlace. This was \ureally\n easy. To give
  363.             you an idea as to how simple this was: I added 9 lines of code,
  364.             4 of which have only one character on them. Of those 9 lines,
  365.             only 2 are directly involved with changing the resolution. (Now
  366.             why didn't I put this in earlier?)
  367.  
  368.             The mouse pointer now changes depending on its location. When
  369.             loading, it becomes the standard clock image. When over a link,
  370.             it becomes a crosshairs. When over the text, but not on a link,
  371.             it becomes an up or down arrow.
  372.  
  373.             Added the 'Restart' option.
  374.  
  375.     3.1 (U) Assorted bug fixes.
  376.  
  377.             The program now stores a list of all blocks. This speeds up
  378.             linking tremendously. (I had a file with > 1000 lines. It was
  379.             taking almost a second to jump to blocks at the bottom of the
  380.             file!)
  381.  
  382.             If you hold down the button on 'Up' or 'Down', the text will
  383.             scroll continuously.
  384.  
  385.     3.0     Yes, it's here! GRAPHICS! This was \umuch\n easier than I thought
  386.             it would be. I managed it by ignoring iffparse.library and using
  387.             iff.library.
  388.  
  389.             Bug fix: A \umajor\n problem here. If you got v2, you know about
  390.             it. The scrolling routines were \itotally\n messed up. Any
  391.             attempt at scrolling a page upwards would throw all the link
  392.             zones off kilter. <sigh> I have no idea how I missed this.
  393.             Anyway, its fixed now.
  394.  
  395.     2.0     Added text scrolling. This should have been in here from the
  396.             start.
  397.  
  398.             The screen now uses the default font. I'm still forcing topaz
  399.             80 for the page text. I may change this is the future, but
  400.             don't count on it. For me to do so, I would need to add a word
  401.             wrap function. (Yes, yes, I know I should do that too. However,
  402.             I would have to rewrite my scroll routines to accomodate it.)
  403.  
  404.             I now load the entire file into memory to view it. This should
  405.             speed access significantly.
  406.  
  407.             Bug fix: When you tried to use the 'Load' option, the file
  408.             requester would appear on the Workbench screen, not the
  409.             program screen. This problem came from using FR_Bypass -- if
  410.             that program was running, the requester appeared in the right
  411.             place. Now I just close the screen when loading a file. (OK,
  412.             so I'm lazy.)
  413.  
  414.     1.2 (U) I just decided that I was kidding myself with the 1.1 fix. Until
  415.             I can support scrolling text, I'm going to force the screen to
  416.             use topaz 80. Sorry about this. I hope to get scrolling text in
  417.             here soon.
  418.  
  419.             Bug fix: when you loaded a file over an old one, the screen was
  420.             not cleared.
  421.  
  422.             Bug fix: the close routines were 'foo'.
  423.  
  424.     1.1 (U) Bug fix: SHTS now does not gag on system fonts with a point
  425.             size greater than 8. However, a large font can force text off
  426.             the bottom of the screen. In other words, this still needs work,
  427.             since large fonts will render files unreadable.
  428.  
  429.     1.0     Initial release
  430. \e
  431.  
  432. \s "Future"
  433. \uThings to Come\n
  434.  
  435.     I have many ideas that I want to implement.
  436.  
  437.         o Sound? If I can figure out how to do it (and I havn't even \uthought\n
  438.           about it yet) I'll stick in a way to play 8SVX samples.
  439.  
  440.         o A scripting language. I want to throw in commands that can be
  441.           embedded in a file to give the author more control over the path
  442.           the reader takes through the text.
  443.  
  444.         o True support for all screen resolutions.
  445.  
  446.         o Pictures with more than 4 default colors.
  447.  
  448.     What else should I put in? Tell me! Send me a letter or E-MAIL if there's
  449. something you want. For my address, click here: \b\l"Credits"[ ]\l
  450. \e
  451.  
  452. \s "Index"
  453. \uIndex\n
  454. \b
  455.     \l"CATS"CATS\l
  456.     \l"Credits"Credits\l
  457.     \l"Creation4"Graphics\l
  458.     \l"History"History\l
  459.     \l"HyperText"HyperText\l
  460.     \l"iff.library"iff.library\l
  461.     \l"ILBM"ILBM\l
  462.     \l"Creation3"Links\l
  463.     \l"Creation"Pages\l
  464.     \l"Prev"Previous Page\l
  465.     \l"Setup"Setup\l
  466.     \l"START"Start\l
  467.     \l"Text"Text\l
  468.     \l"Future"Things to Come\l
  469.     \l"Creation2"Type styles\l
  470. \n
  471. \e
  472.  
  473.