@DATABASE "AGHTW-Part5" @$VER: Amigaguide_How_To_Write_Pt5 01.04 (05.12.97) Copyright © 1997 Frank P. Bunton @INDEX "AGHTW_Index/Index" @NODE "MAIN" "How To Write AG - Part 5" @TOC "AGHTW_Index/Main" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS - PART 5@{UB}@{UU} @{JLEFT} This node should not normally be displayed if you started off from the index file. But in case you started off this file as an individual document, you can now access the following items:- @{JCENTER} @{" Debugging " LINK "Debugging"} @{" Problems With Amigaguide Documents " LINK "Problems"} @{" To Do and To Checked " LINK "ToDo"} @{B}@{U}Definitions Of Terms:-@{UB}@{UU} @{" ASCII Codes " LINK "Ascii"} @{" Line Feed Character " LINK "LineFeed"} @{" Commands " LINK "Commands"} @{" Commands - Global " LINK "Global"} @{" Commands - Local " LINK "Local"} @{" Commands - Text Attribute " LINK "Attribute"} @{" Lines - Logical " LINK "Logical"} @{" Lines - Physical " LINK "Physical"} @{" Nodes " LINK "Nodes"} @{" MAIN INDEX " LINK "AGHTW_Index/Main"} === End of Text === @ENDNODE @NODE "Debugging" "How To Write AG - Debugging (Pt5)" @TOC "AGHTW_Index/Contents" @PREV "AGHTW_Part4/MiscAtt" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS USING THE DEBUGGING FEATURE AMIGAGUIDE/MULTIVIEW VERSION 40 ONLY@{UB}@{UU} @{JLEFT} Note - This feature does not seem to work in version 39 and earlier. Just as I was putting version 1.04 of this project to rest, I had an e-mail from @{"Richard Burke" LINK "AGHTW_Boring_Stuff/Credits"40} telling me about the DEBUGGING ability in version 40. To get it to work, you must first set the environmental variable:- Env:Amigaguide/Debug to hold the value:- ON You can do this by entering in Shell/CLI:- > Setenv Env:Amigaguide/Debug ON (This does @{B}NOT@{UB} seem to work if you use Env:@{B}Multiview@{UB}/Debug.) After this, any attempt to use Amigaguide or Multiview to load an Amigaguide document that has certain types of errors will result in a window opening with an error report. I do not want to hold up the release of this version while I fully investigate this feature but, so far, I have been able to get it to tell me about missing arguments to commands, missing ENDNODE commands and a few other things. For example, for a document that had @{"Problem 1" LINK "Problems"8} it told me:- Path/Filename, Line 6, Error 4: line too long Path/filename, Line 6, Error 6: missing endnode(s) Both errors relating to the one problem! It did NOT tell me about errors in a document that had @{"Problem 2" LINK "Problems"18} and @{"Problem 5" LINK "Problems"120}. Apart from the above, and with the help of @{"Richard Burke" LINK "AGHTW_Boring_Stuff/Credits"40}, I have so far found error reporting in these situations:- - When the @{"DATABASE" LINK "AGHTW_Part1/Database"18} command is used without the "Document Name" argument. - In certain situations where @{"unrecognised commands" LINK "AGHTW_Part1/Unrecognised"55} are found. - In cases where a @{"local command" LINK "AGHTW_Part1/Nodes"38} is not placed within a node. If anyone knows any more about this feature, e.g. lists of errors and types of errors that will be reported, @{"I" LINK "AGHTW_Boring_Stuff/Author"} would appreciate their advice. Full credit will be given to any such informants for information that I use in later versions. @{JCENTER}=== End of Text === @ENDNODE @NODE "Problems" "How To Write AG - Problems (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS PROBLEMS WITH AMIGAGUIDE FORMATTED DOCUMENTS@{UB}@{UU} @{JLEFT} @{B}PLEASE@{UB} can Amiga International take note of these problems and have them corrected in future versions!! @{B}@{U}1. Missing Line Feed After Last \@ENDNODE - All versions@{UB}@{UU} The LAST ENDNODE @{B}MUST@{UB} have a line feed code after it. If not, Amigaguide will not work properly or will not work at all!! In @{B}version 34 and 39@{UB} the last node will be shown without any text in it. In @{B}version 40@{UB} Multiview/Amigaguide fails to load altogether with the error message "Not enough data". @{B}@{U}2. Unbalanced Inverted Commas in Link Commands - Version 40@{UB}@{UU} * If a string after LINK has an opening " but no closing " as in:- \@{"Button Text" LINK "NodeName} then, in @{B}version 40@{UB}, problems can occur such as a GURU visitation, or the button won't work and Amigaguide/Multiview freezes up, or the button does not show up at all. (I have experienced all these problems but have not yet worked out the circumstances under which they all occur.) In @{B}version 34 and 39@{UB} there do not appear to be any problems. * If there is an extra inverted comma as in:- \@{"Button Text" LINK "NodeName"40"} then, in @{B}version 40@{UB}, the same sort of problems as described above can occur. In @{B}version 34 and 39@{UB} there do not appear to be any problems and the nominated line number is reached. * If there is an extra inverted comma as in:- \@{"Button Text"" LINK "NodeName"40} then, in @{B}version 40@{UB}, the same sort of problems as described above can occur. In @{B}version 34 and 39@{UB} there is a button but no action is taken when the button is clicked (except that, in version 34, the @{"Amiga's alert" LINK "AGHTW_Part2/Beep"29} is activated). @{B}@{U}3. Target Lines Near End Of Nodes - All Versions@{UB}@{UU} When using a @{"node link to a line number" LINK "AGHTW_Part2/LinkCommand"31}, as in:- \@{"Button Text" LINK "NodeName"40} the target line usually appears as the top line in the window. For example, @{"this button" LINK "AGHTW_Index/IndexTopics"15} should put the following line from the "Topics Index" at the top of the window:- If using version 34 - "Amiga Alert (Beep)" If using version 39/40 - The ~~~~ line above it If the target line is near the end of the node then the target line may appear further down the window than the top line as there are not enough lines between the last line of text and the ENDNODE command. For example, @{"this button" LINK "AGHTW_Index/IndexTopics"317} is aimed at line 317 of the "Topics Index" that reads "Word Wrapping" but, if you click the button, you will note that "Word Wrapping" is down near the bottom (the last button in the list). This is a fault with Amigaguide/Multiview design. To overcome it, you must put as many blank lines as necessary between the last line of text and the #ENDNODE command. I have @{"done this" LINK "AGHTW_Boring_Stuff/Using"75} with a lot of nodes in this set. For example, @{"this button" LINK "AGHTW_Part1/Versions"53} should take you to the node "Amigaguide Versions" and show this line:- "Commands that are applicable ..." for version 34 one line above this for version 39/40 Another problem with using jumps to line numbers is that, for the same line number, version 34 takes you to @{"one line further down" LINK "AGHTW_Part2/LinkCommand"48} the text than does versions 39 or 40 (as illustrated in the previous paragraph). Another problem is that, if your document is to be read by other people, then you do not know what window size they will be using. If you use a smaller window than others (less number of lines of text) then your target line might still end up below the top of the window that the reader is using. You should really allow for a maximum size window. But then the readers may be using a very small font! I won't guarantee that all @{B}MY @{UB}links in this document will get @{B}YOU @{UB}to the intended target lines!! @{B}@{U}4. Target Lines - Aiming For@{UB}@{UU} The method by which we can @{"aim a button at a particular line" LINK "AGHTW_Part2/LinkCommand"31} in a node is cumbersome and prone to error as it means that any subsequent amendments to the text in a node can throw out the references. Thus, the more corrections made to a document the more tedious it is to go through it and correct all the node links that have line numbers in them. Also, if @{"WORDWRAP" LINK "AGHTW_Part3/WordWrap"} or @{"SMARTWRAP" LINK "AGHTW_Part3/SmartWrap"} is used, and the reader uses a different window size to the author, then the line number references can easily be completely thrown out and wrong lines will be reached. What is really needed is a method of placing some sort of marker into the text which indicates the spot within the node to which the jump is to be made. For example, a command such as:- #TARGET (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) which could be placed at the correct position in the text and then reached with:- #{"button name" LINK "NodeName" targetname} @{B}@{U}5. Space between \@{ and "@{UB}@{UU} If you set up a link with a space between the opening curly bracket and the first inverted comma as in:- #{ " Button Name " LINK "LabelName"} (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) then, if you are using @{B}version 40@{UB}, the button @{B}will NOT appear@{UB} in the display!!! (In @{B}versions 34 and 39@{UB} it works O.K.!!) The above line is a used in the following button:- If a button does @{B}NOT@{UB} appear between the arrows --> @{ "Button Name " LINK "LabelName"} <-- then you are using version 40 (Workbench 3.1) The problem does @{B}NOT@{UB} appear to be there in @{B}versions 34 and 39@{UB}. So, no matter what version you use, to ensure compatibility, @{B}ALWAYS@{UB} make sure you enter it without the space as in:- #{" Button Name " LINK "LabelName"} @{B}@{U}6. Non Recognition of the ".guide" suffix by ONOPEN and ONCLOSE@{UB}@{UU} @{"RX" LINK "AGHTW_Part2/Rx"} @{"recognises the script suffix" LINK "AGHTW_Part2/Rx"33} ".guide" for ARexx script files but @{"@ONOPEN and @ONCLOSE" LINK "AGHTW_Part2/OnOpenClose"45} @{B}do NOT@{UB}!! WHY?!?!? @{B}@{U}7. Non Alignment Of Link Buttons@{UB}@{UU} Each version of Amigaguide/Multiview seems to treat the number of pixels in the buttons differently. This is demonstrated by these examples:- @{B}This set look normal in version 34@{UB}:- @{"False Button" LINK ""} @{"False Button" LINK ""} @{"False Button" LINK ""} Normal text @{"False Button" LINK ""} Normal Text Normal Text Normal Text @{"False Button" LINK ""} @{"False Button" LINK ""} @{"False Button" LINK ""} Normal Text @{"False Button" LINK ""} Normal text Normal text @{B}This set look normal in version 39@{UB}:- @{"False Button" LINK ""} @{"False Button" LINK ""} @{"False Button" LINK ""} Normal text @{"False Button" LINK ""} Normal Text Normal Text Normal Text @{"False Button" LINK ""} @{"False Button" LINK ""} @{"False Button" LINK ""} Normal Text @{"False Button" LINK ""} Normal text Normal text @{B}This is as close as I can get it in version 40@{UB}:- @{"False Button" LINK ""} @{"False Button" LINK ""} @{"False Button" LINK ""} Normal text @{"False Button" LINK ""} Normal Text Normal Text Normal Text @{"False Button" LINK ""} @{"False Button" LINK ""} @{"False Button" LINK ""} Normal Text @{"False Button" LINK ""} Normal text Normal text In versions 34 and 39 it seems it is possible to get this sort of thing aligned up to look O.K. in that version but it will look non-aligned in other versions!! In version 40 it is not possible to get it aligned up properly at all!! @{B}@{U}8. Cut Off Letters With Bold, Italic@{UB}@{UU} Some letters have their right edges cut off in some circumstances when they are the last letter before the end of the special style. For example, these lines might have the right edges of the last "O" and "Y" cut off:- @{B}LAST LETTER O WITH BOLD O@{UB} @{I}LAST LETTER Y WITH ITALIC Y@{UI} In my experience, this happens most of the time in version 40 but only sometimes in version 39. In version 34 it does not happen because v34 does not support bold! It is also possible that the font you are using could affect the incidence of this problem. To overcome this problem you can leave a space between the last letter and the command:- \@{B}LAST LETTER O WITH BOLD O \@{UB} \@{I}LAST LETTER Y WITH ITALIC Y \@{UI} which would appear like this:- @{B}LAST LETTER O WITH BOLD O @{UB} @{I}LAST LETTER Y WITH ITALIC Y @{UI} @{B}@{U}9. Macros Can't Handle Large Numbers Of Characters In Their Arguments@{UB}@{UU} See details under the heading @{"A Problem With Macros" LINK "AGHTW_Part3/Macros"133}. (Thanks @{"Michael" LINK "AGHTW_Boring_Stuff/Credits"13}.) @{B}@{U}10. Incorrect Return with "Retrace" In Some Circumstances@{UB}@{UU} In versions 34 & 39, the "Retrace" button does not always take you back to where you were (as discussed @{"here" LINK "AGHTW_Boring_Stuff/Using"85}). @{B}@{U}11. Any Other Problems??@{UB}@{UU} Please let @{"me" LINK "AGHTW_Boring_Stuff/Author"} know of any other problems so that I can include them with full credit being given to you. @{JCENTER}=== End of Text === @ENDNODE @NODE "ToDo" "How To Write AG - Items To Be Checked (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS ITEMS TO DO AND TO BE CHECKED@{UB}@{UU} @{JLEFT} @{B}@{U}Items That I Need More Information About Before They Can be completed@{UB}@{UU} If anyone can help me complete these items then please @{"let me know" LINK "AGHTW_Boring_Stuff/Author"} so that I can update this document. You will be given full credit in the revision. The points on which I need more information are:- 1. Are there any problems in @{"using Amigaguide with AmigaDOS/Workbench 1.3" LINK "AGHTW_Part1/Versions"11} and earlier? 2. What versions of "amigaguide.library" and "amigaguide.datatype" are there other than those @{"listed earlier" LINK "AGHTW_Part1/Versions"22}? (Version numbers, i.e. 34, 39, 40 NOT revision numbers). 3. Is there any way to use the @{"DNODE" LINK "AGHTW_Part1/DNode"} in normal Amigaguide format documents? 4. Can a @{"link to a sound file" LINK "AGHTW_Part2/OtherLinks"50} give the sound when it is clicked or is it really necessary to have it open another window with a sound icon in it which must then be clicked? By this I mean when using the LINK command and not by the use of SYSTEM as described under the heading @{"Links To Other File Types In Early Versions Of Amigaguide" LINK "AGHTW_Part2/OtherLinksEarly"}. 5. Is there any way to get the @{"HEIGHT and WIDTH" LINK "AGHTW_Part3/WinSize"} commands to work? 6. Why do \@{LINE} and \@{PAR} both appear to @{"act in the same way" LINK "AGHTW_Part4/LinePara"20}? 7. Why doesn't \@{PARI} work on any paragraph @{"but the first" LINK "AGHTW_Part4/Pari"} 8. What is the \@{BODY} command @{"supposed to do" LINK "AGHTW_Part4/MiscAtt"23}? 9. I would like to add a section on the use of @{B}ARexx with Amigaguide & Multiview@{UB} at some time in the future but, as yet, I have been unable to locate any information on what internal ARexx commands are available in which versions of Amigaguide and Multiview and what they do. Anyone who is able to help expand this project in this way please contact @{"me" LINK "AGHTW_Boring_Stuff/Author"}. @{JCENTER}=== End of Text === @ENDNODE @NODE "Ascii" "How To Write AG - Definition Of Terms - ASCII Codes (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS ASCII Codes@{UB}@{UU} @{JLEFT} ASCII (pronounced "askey") is an acronym for "American Standard Code for Information Interchange". It is a system whereby all characters are assigned a code number (all information is stored in computer memory as numbers). Printable characters have numbers ranging from 32 to 127. For example:- A = 65 a = 97 Z = 90 z = 122 Code numbers 0 to 31 are control characters such as:- BELL = 7 TAB = 9 Line Feed = 10 Carriage Return = 13 @{JCENTER}=== End of Text === @ENDNODE @NODE "LineFeed" "How To Write AG - Definition Of Terms - Line Feed (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS LINE FEED CHARACTER@{UB}@{UU} @{JLEFT} The line feed character is @{"ASCII code" LINK "Ascii"} number 10. On the Amiga, it is normally inserted into the text by pressing the RETURN key. @{JCENTER}=== End of Text === @ENDNODE @NODE "Commands" "How To Write AG - Definition Of Terms - Commands (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS COMMANDS@{UB}@{UU} @{JLEFT} Commands are words that are embedded in the Amigaguide document that give Amigaguide/Multiview some type of instruction. For instance, to jump to another node or to display the text in bold type. There are two broad types of commands - @{"Global" LINK "Global"} and @{"Local" LINK "Local"} with a sub group of local commands called @{"Text Attribute Commands" LINK "Attribute"} @{JCENTER}=== End of Text === @ENDNODE @NODE "Global" "How To Write AG - Definition Of Terms - Global Commands (Pt5)" @TOC "AGHTW_Index/Contents" @{JLEFT} @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS GLOBAL COMMANDS@{UB}@{UU} @{JLEFT} These are commands that affect all nodes in the whole of the document. They must be placed at the start after the #DATABASE command and before the #NODE "MAIN" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}). @{JCENTER}=== End of Text === @ENDNODE @NODE "Local" "How To Write AG - Definition Of Terms - Local Commands (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS LOCAL COMMANDS@{UB}@{UU} @{JLEFT} These are the commands that affect only the node in which they are used. They are must be placed after the #NODE "NodeName" and before the #ENDNODE (remember that @{"# = @" LINK "AGHTW_Part1/Important"}). Although they seem to work if put anywhere within the node, the best place would be immediately after the #NODE "NodeName" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) and before the text as they will be easier to locate. @{JCENTER}=== End of Text === @ENDNODE @NODE "Attribute" "How To Write AG - Definition Of Terms - Attribute Commands (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS COMMANDS - TEXT ATTRIBUTE@{UB}@{UU} @{JLEFT} These are commands which affect the appearance of the text (e.g. bold, italic, underlining, colouring, and others). They are a sub group of @{"Local Commands" LINK "Local"} and can be placed @{B}anywhere@{UB} within the text. @{JCENTER}=== End of Text === @ENDNODE @NODE "Logical" "How To Write AG - Definition Of Terms - Logical Lines (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS LINES - LOGICAL@{UB}@{UU} @{JLEFT} A "Logical Line" is a string of text that ends with the @{"line feed" LINK "LineFeed"} character. It may be longer than the @{"physical line" LINK "Physical"} that appears in a display window. If so, then what happens depends on the program that is displaying the line. Some programs will cause a logical line to extend beyond the right edge of the window. In this case you will have to use the scroll bar (if there is one). Amigaguide/Multiview does this in versions earlier than 39 and in versions 39 onwards if one of the commands @{"WORDWRAP" LINK "AGHTW_Part3/WordWrap"} or @{"SMARTWRAP" LINK "AGHTW_Part3/SmartWrap"} is not used. In other programs, such as The AmigaDOS program "Ed", the use of some sort of key combination is needed to see the rest of the logical line. Some programs will wrap the logical line over to the next physical line breaking words in half if necessary. This is how the Shell/CLI window treats logical lines. Some programs will do an intelligent word wrap and not split words when wrapping a logical line onto the next physical line. Most word processors do this as does Amigaguide/Multiview versions 39 onwards when either @{"WORDWRAP" LINK "AGHTW_Part3/WordWrap"} or @{"SMARTWRAP" LINK "AGHTW_Part3/SmartWrap"} is used. @{JCENTER}=== End of Text === @ENDNODE @NODE "Physical" "How To Write AG - Definition Of Terms - Physical Lines (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS LINES - PHYSICAL@{UB}@{UU} @{JLEFT} A "Physical Line" is one row of text in a display window. It may or may not have a @{"line feed character" LINK "LineFeed"} at the end of it. Compare this with a @{"logical line" LINK "Logical"} which may extend beyond the one physical line and is only ended by a line feed character. @{JCENTER}=== End of Text === @ENDNODE @NODE "Nodes" "How To Write AG - Definition Of Terms - Nodes (Pt5)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS DEFINITIONS OF TERMS NODES@{UB}@{UU} @{JLEFT} A node is a part of the Amigaguide document that is defined by having:- - The command @{"NODE" LINK "AGHTW_Part1/Node"} at the start of the node - The command @{"ENDNODE" LINK "AGHTW_Part1/EndNode"} at the end of the node @{JLEFT} All text appearing between these two commands is part of that node and will appear in the display window when a @{"link" LINK "AGHTW_Part2/LinkCommand"} to the node is selected, although some of it may be beyond the size of the window and the scroll bars may be needed to read it. Only one node of a document can be viewed at a time (unless you have an Amigaguide version earlier than 39 and the document has an @{"ALINK" LINK "AGHTW_Part2/ALink"} command in it). @{JCENTER}=== End of Text === @ENDNODE