home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 649b.lha / Magnetic_Pages_v1.30 / Displayer / Displayer.docs < prev    next >
Text File  |  1992-05-20  |  19KB  |  401 lines
  1.               M A G N E T I C  P A G E S: Displayer (V1.30)
  2.              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. Introduction
  5. ~~~~~~~~~~~~
  6.     This is the program used to view a magazine. In addition to displaying
  7. the magazine, the reader may save text as a standard ascii file, save an
  8. entire page as an IFF picture, or print the text and/or graphics on a page.
  9.  
  10.  
  11. Running the Displayer
  12. ~~~~~~~~~~~~~~~~~~~~~
  13.     The Displayer can be run from the CLI or the Workbench. In addition to
  14. the actual magazine articles, the Displayer requires a special control file
  15. which contains information about the magazine contents. This control file
  16. is created using the Organiser and unless you have this program you can't
  17. make a magazine.
  18.  
  19. Running from CLI:
  20.     The displayer has one argument, the AmigaDos path/name of the control
  21. file. This control file may be called anything and located anywhere on the
  22. disk. eg.
  23.  
  24.             1> Displayer My_Mag
  25.  
  26.             ^               ^
  27.             |               |
  28.             |                Control file name
  29.             |
  30.              CLI prompt
  31.  
  32.     Note that you don't need to use the AmigaDOS RUN command. It will
  33. detach itself from the CLI automatically.
  34.  
  35. Running from Workbench:
  36.     To run the Displayer from Workbench, simply give your Control file a
  37. project icon and specify the Displayer as the 'Default Tool'. You can use
  38. icon supplied on this disk or make your own using IconEdit. You can have
  39. several different magazines on a disk, each with their own control file and
  40. icon.
  41.  
  42.  
  43. Memory Requirements
  44. ~~~~~~~~~~~~~~~~~~~
  45.     An optimum setup is an Amiga with 512k of Chip ram and 512k of Fast Ram.
  46. However it will run on all other configurations. It is up to the magazine
  47. editor to make sure that all articles can be displayed on a 512k machine.
  48.     When an article is loaded, the Displayer will try and load it all into
  49. Fast ram. Then when a page is displayed, any graphics, sound or music needed
  50. for the page will be copied into Chip ram. As the graphics are copied to
  51. Chip Ram they will also be decompressed.
  52.     If the Displayer is running on an Amiga with only chip ram, then all
  53. data must have been loaded into Chip Ram. This means it's not necessary to
  54. copy sound/music data from Fast Ram before playing it. If possible, two
  55. copies are still made on an all chip machine because when you move to
  56. another article you want any background sound/music to continue playing,
  57. and the original article containing the sound/music will be erased by the
  58. new article. If however there isn't enough ram for two copies of the data,
  59. the sound/music is played using the data contained in the article but when
  60. the reader loads in a new article, the sound/music will be stopped and the
  61. article erased.
  62.  
  63.  
  64. Using the Displayer
  65. ~~~~~~~~~~~~~~~~~~~
  66.  
  67. Moving around a magazine:
  68.     The most basic operation is moving around the magazine. On a standard
  69. text page, you can use the menus or gadgets. On a custom graphics page you
  70. have to use the menu commands. The menu bar is hidden so it is important
  71. that people realise this is the only method of getting off a graphics page.
  72. The commands for moving around the magazine are as follows:
  73.  
  74. Menu        Gadget   KeyBoard
  75. ~~~~        ~~~~~~   ~~~~~~~~
  76. Next Page     >     Cursor Right         - Takes you to the next page in an
  77.                                            article. If you are on the last
  78.                                            page of an article, you will be
  79.                                            taken to the first page of the
  80.                                            next article.
  81.  
  82. Prev Page     <     Cursor Left         - Takes you to the previous page in
  83.                                           an article. If you are on the first
  84.                                           page of an article, you will be
  85.                                           taken to the last page of the
  86.                                           previous article.
  87.  
  88. 1st Page      |<    SHIFT + Cursor Left - Takes you to the 1st page of an
  89.                                           article. If you are already on
  90.                                           page one of an article or the
  91.                                           article only contains one page,
  92.                                           this command has no effect.
  93.  
  94. Last Page     >|    SHIFT + Cursor Right -Takes you to the last page of an
  95.                                           article. If you are already on
  96.                                           the last page of an article or the
  97.                                           article only contains one page,
  98.                                           this command has no effect.
  99.  
  100. Next Article  >>    Cursor Up           - Takes you to the next article in
  101.                                           the magazine. If you are at the
  102.                                           last article of the magazine, you
  103.                                           will be taken back to the first
  104.                                           article.
  105.  
  106. Prev Article  <<    Cursor Down         - Takes you to the previous article
  107.                                           in the magazine. If you are on the
  108.                                           first article of the magazine, you
  109.                                           will be taken to the last article.
  110.  
  111. Contents  Contents  Space Bar           - This depends on the layout of the
  112.                                           magazine and where you currently are.
  113.                                           For example a magazine may be
  114.                                           divided up into various sections.
  115.                                           Eg Articles, Reviews, Feedback,
  116.                                           Art Gallery, etc. There may also
  117.                                           be a main contents page which has
  118.                                           icons on it that allow you to branch
  119.                                           to the different sections. Once you
  120.                                           have branched to a section (eg
  121.                                           articles) you should be able to get
  122.                                           back to the main contents by
  123.                                           selecting the Contents command.
  124.  
  125.  
  126.     As well as moving through a magazine sequentially, a well designed
  127. magazine will be divided up into different sections, each with their own
  128. contents page. On a contents page, you can select an article to read, or
  129. branch to another section by clicking on icons (boxes) on the page. A box
  130. that can be clicked on will respond with a push-button effect or with
  131. several frames of animation. To get back to the previous contents page,
  132. select the 'Contents' command.
  133.  
  134.  
  135. Sound/Music:
  136.     Some pages may play a piece of sound or music when you turn to them.
  137. This is nothing to be frightened about, it is perfectly normal. If it is
  138. a long piece of music or sound, or it has been told to repeat continuously
  139. it may not stop until you exit the magazine. You can turn the sound off
  140. yourself at any stage by toggling the menu item 'Sound On' in the 'Other'
  141. menu.
  142.     Some pages may also have boxes on them which will play sound/music
  143. when you click on them.
  144.  
  145.  
  146. Sleep:
  147.     Allows you to free almost all memory used by the magazine. A small window
  148. will be displayed in the top right corner of the Workbench screen. To return
  149. to the magazine click in this window once with the left mouse button and then
  150. once with the right button.
  151.  
  152.  
  153. Save as IFF:
  154.     This menu command allows you to save one or several pages as IFF
  155. pictures. If you want to save off one page, simply enter the filename
  156. at the prompt.
  157.     To save off a whole article, you use the same procedure. Each page will
  158. be saved as filename.PAGENUM, where filename is the AmigaDos path/name you
  159. entered at the prompt and PAGENUM is the page number. Only pages from the
  160. current page to the end of the article will be saved. For example if an
  161. article has 6 pages and you are on page 3 when you select 'Save as IFF',
  162. only pages 3,4,5 and 6 will be saved.
  163.  
  164.  
  165. Save Text:
  166.     This menu command allows you to save a page of text or all the text
  167. from an article. The text will be saved as a standard ASCII file. Simply
  168. enter the filename at the prompt.
  169.  
  170.  
  171. Print:
  172.     This menu command allows you to print a page, an article, a section
  173. or the whole magazine. There are two printing modes available.
  174.  
  175. 'Text Only'    will only print out the text on a page.
  176. 'Screen Dump'  will print out the whole page as a graphics dump, similar to
  177.                printing on Deluxe Paint.
  178.  
  179. 2 Pages/Single Sheet - If this gadget is selected, 2 text pages will be
  180.                        printed on every sheet of paper. Otherwise every page
  181.                        will be printed on a new sheet of paper. This gadget
  182.                        has no effect when printing in the 'Screen Dump' mode.
  183.  
  184.    Note that when you are printing a whole article, section or the entire
  185. magazine, printing will always begin with the page you are currently on. This
  186. means that if you have to abort printing part way through, you can resume from
  187. where you left off.
  188.  
  189.  
  190. Text Search:
  191.     This command allows you to search the magazine for a particular word or
  192. sentence. You can choose to search the current page, article, section or
  193. entire magazine. When you select this command a requester containing
  194. several gadgets will be displayed. Firstly enter the word or string of words
  195. you want to search for. The 'Case Sensitive' gadget allows you to distinguish
  196. between upper and lowercase characters. If this gadget is selected, the
  197. strings 'keeP Nz Nuclear free' and 'Keep NZ Nuclear Free' would not match.
  198. If 'Case Sensitive' is not selected the previous strings would match.
  199.     When searching the magazine any multiple spaces encountered between words
  200. are removed. This is because the text in a magazine is often right-justified
  201. which causes extra spaces to be inserted between words. This means the
  202. strings 'Keep NZ Nuclear Free' and 'Keep     NZ Nuclear  Free' will match.
  203. Also any sentences that are split over 2 or more lines, text boxes or pages
  204. will be found.
  205.     To begin a search click on the 'Find' gadget. Unlike the Print command
  206. searching will always start at the beginning of an article, section or
  207. magazine. If a match is found, the appropriate page will be displayed and
  208. the matching text will be highlighted. To continue searching for the next
  209. occurence of the string, click on the 'Next' gadget. When no more matches
  210. can be found, the message 'No Match Found' will be displayed. To search
  211. for a new string or to start searching from the beginning again, click on the
  212. 'Find' gadget.
  213.     If you are searching a section or the whole magazine, you can abort the
  214. search by clicking on the 'Exit' gadget. Note that there may be a slight
  215. delay after clicking on 'Exit' and the current article will have to be
  216. reloaded.
  217.  
  218.                      -----------------------------------
  219.  
  220. Customising the Displayer
  221. ~~~~~~~~~~~~~~~~~~~~~~~~~
  222.  
  223.     It is possible to customise the Help File and all the menu, gadget and
  224. requester text used in the Displayer. This allows you to translate the
  225. text into your own language, should it be different from English. It also
  226. allows you to change the terminology used within the Displayer, should you
  227. be using Magnetic Pages for something other than a disk magazine.
  228.  
  229. Help File
  230. ~~~~~~~~~
  231.  
  232.     When you request Help from within the Displayer, it will load a special
  233. text file from disk and display it in the Help Window. You can customise
  234. this file to suit your own requirements using a text editor such as
  235. Az (my favourite!), Ed, MicroEmacs, or CED.  The help file is called
  236. Displayer_Help. You cannot change its name and it must be in the same
  237. directory as the Displayer.
  238.     The help window can display 38 columns and 20 rows. You can have up to
  239. 20 pages of help information. Within the Help text you can use the standard
  240. ANSI control codes to change the text style and colour.
  241.  
  242.                     The following ANSI control codes are supported.
  243.                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  244.  
  245.                 ESC [0m  - Resets text to default colour and plain style
  246.                 ESC [3m  - Italics On
  247.                 ESC [23m - Italics Off
  248.                 ESC [4m  - Underline On
  249.                 ESC [24m - Underline Off
  250.                 ESC [1m  - Boldface On
  251.                 ESC [22m - Boldface Off
  252.                 ESC [3nm - Set foreground colour (where n = 0 - 9)
  253.                 ESC [4nm - Set background colour (where n = 0 - 9)
  254.                 ESC [6"m - Shadow On    { Note: Normal ANSI uses 6"Z
  255.                 ESC [5"m - Shadow Off     and 5"Z for Shadow control. }
  256.  
  257.                 ESC = Ascii code 27 and appears as an inverse left square
  258.                       bracket when using Workbench 1.3 or a small square
  259.                       when using Worbench 2. There should be no space
  260.                       between ESC and the [.
  261.  
  262.     In addition to the above escape sequences there are some special ones
  263. that I've defined to allow you to display the title bar gadgets in the Help
  264. text. This is so the user can see exactly what the gadget looks like that
  265. you are describing. The special codes are as follows:
  266.  
  267.     ESC [G0m - Display the 'Go to the first page of an article' gadget.
  268.     ESC [G1m - Display the 'Go to the last page of an article' gadget.
  269.     ESC [G2m - Display the 'Next article' gadget.
  270.     ESC [G3m - Display the 'Next page' gadget.
  271.     ESC [G4m - Display the 'Contents' gadget.
  272.     ESC [G5m - Display the 'Previous page' gadget.
  273.     ESC [G6m - Display the 'Previous article' gadget.
  274.  
  275.     Have a look at the standard Help file for an example of how to use the
  276. escape codes.
  277.     Once you have set up the Help file as you want it, you can crunch it
  278. with PowerPacker to save disk space.
  279.  
  280. Other Languages
  281. ~~~~~~~~~~~~~~~
  282.     It is possible to redefine all the text used in the Displayer program.
  283. The Displayer comes with English built in. When the Displayer starts up,
  284. it looks for a file called Displayer_Text. This file must be in the same
  285. directory as the Displayer and it cannot be renamed. If it finds this file
  286. it will use the text in it and automatically reformat all the menus, gadgets,
  287. and requester text. If it doesn't find this file, it defaults to English.
  288.     The format of this file is quite simple. It is a plain text file, with
  289. each text string separated by a line feed. There is a sample file included
  290. on this disk called Displayer_Text.example. This is an English version of
  291. all the text used in the Displayer. You should edit this file with a text
  292. editor (translating the text into your own language) and then save it as
  293. Displayer_Text. Below I've listed this file and added comments to explain
  294. what the text is used for. Note that you cannot have comments in the real
  295. file.
  296.  
  297. Project                   ; The Menu Text. These are in order from top left
  298. Sleep                     ; to bottom right.
  299. Save As IFF  »
  300. Page...                   ; Save as IFF Sub Menu
  301. Article...
  302. Save Text    »
  303. Page...                   ; Save Text Sub Menu
  304. Article...
  305. Print        »
  306. Page...                   ; Print Sub Menu
  307. Article...
  308. Section...
  309. All...
  310. About...
  311. Quit
  312. Move To                   ; The Move To Menu starts here.
  313. Next Page
  314. Prev Page
  315. 1st Page
  316. Last Page
  317. Next Article
  318. Prev Article
  319. Contents
  320. Other                     ; The Other Menu starts here.
  321. Sound On
  322. Text Search  »
  323. Page...                   ; Text Search Sub Menu.
  324. Article...
  325. Section...
  326. All...
  327. Help...
  328. CONTENTS        ; This is for the CONTENTS Gadget in the titlebar.
  329. OK              ; This is for the OK or confirmation gadget used in requesters.
  330. CANCEL          ; This is for the CANCEL gadget used in requesters.
  331. CONTINUE        ; This is used for the gadget in Error requesters.
  332. Find            ; Icon in the Text Search requester.
  333. Next            ; Icon in the Text Search requester.
  334. Prev            ; Icon in the Help requester.
  335. Exit            ; Icon in the Text Search and Help Requesters.
  336. Save Page as an IFF Picture.         ; Title for the file requester.
  337. Save Article as IFF Pictures.        ; Title for the file requester.
  338. Enter Filename:                      ; Used in the file requester.
  339. Save Page of Text.                   ; Title for the file requester.
  340. Save Article Text.                   ; Title for the file requester.
  341. Print Page                           ; Title for the print requester.
  342. Print Article                        ; Title for the print requester.
  343. Print Section                        ; Title for the print requester.
  344. Print All                            ; Title for the print requester.
  345. Text Only                            ; Used in the print requester.
  346. Graphic Dump                         ; Used in the print requester.
  347. 2 Pages/Single Sheet                 ; Used in the print requester.
  348. STOP PRINTING                 ; The icon used to abort a printing operation.
  349. Search Page                          ; Title for the Text Search requester.
  350. Search Article                       ; Title for the Text Search requester.
  351. Search Section                       ; Title for the Text Search requester.
  352. Search All                           ; Title for the Text Search requester.
  353. Case Sensitive                       ; Used in the Text Search requester.
  354. Enter a Search String                ; Used in the Text Search requester.
  355. This version belongs to:             ; Used in the small loading window.
  356. Usage: MP_Displayer [CONTROL FILE]      ; The following are error messages.
  357. Unable to Load Control File
  358. Unable to Open Article
  359. Error Reading Article
  360. Out of Memory Error
  361. This Article has been Encrypted?
  362. File Loaded was not an Article
  363. Unable to Open File
  364. Error Writing File
  365. Unable to Open Page
  366. Error: Article not in List
  367. Can't Create Printer Request
  368. Can't Open Printer Device
  369. User Canceled Dump                  ; Printing Error.
  370. Not A Graphics Printer              ; Printing Error.
  371. Wierd Printer Error                 ; Printing Error.
  372. Illegal Dimensions                  ; Printing Error.
  373. Wierd Printer Error                 ; Printing Error.
  374. No Memory For Variables             ; Printing Error.
  375. No Memory For Buffer                ; Printing Error.
  376. No Match Found                   ; Displayed when a Text Search finds nothing.
  377. Error Loading the Help File!
  378.  
  379.  
  380.     The Displayer reformats all the Menus and Gadgets automatically, so you can
  381. make the text strings longer or shorter. Note however, if you make them too big
  382. then they may overrun some of the gadgets and windows. You have to take
  383. particular care when designing the menus. If you are going to use low
  384. resolution screens, make sure that the menus will fit on. A low res screen
  385. is half the width of the standard text screen.
  386.     Finally once you've redefined the text and save it as Displayer_Text, you
  387. can save disk space by crunching the file with PowerPacker.
  388.  
  389.  
  390. Upgrades
  391. ~~~~~~~~
  392.     The Displayer is by no means perfect. I will continue to work on it when
  393. I get the time. I'm not promising anything but if enough interest is shown
  394. in Magnetic Pages, then there are many new features I'd like to add.
  395.  
  396.     If you have any suggestions, or complaints please let me know when you
  397. register.
  398.  
  399.                                                             Mark Gladding.
  400.  
  401.