@DATABASE "AGHTW-Part3" @$VER: Amigaguide_How_To_Write_Pt3 01.06 (12.02.98) Copyright © 1997/1998 Frank P. Bunton @INDEX "AGHTW_Index/Index" @NODE "MAIN" "How To Write AG - Part 3" @TOC "AGHTW_Index/Main" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS - PART 3@{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} @{" Commands - Global & Local " LINK "GlobalLocal"} @{" Global Commands " LINK "Global"} @{" Local Commands " LINK "Local"} @{" Cross Referencing " LINK "Cross"} @{" HELP Command " LINK "HelpCom"} @{" INDEX Command " LINK "IndexCom"} @{" NEXT & PREV Commands " LINK "NextPrev"} @{" TOC Command " LINK "Toc"} @{" Word Wrapping " LINK "Wrapping"} @{" WORDWRAP Command " LINK "Wordwrap"} @{" SMARTWRAP Command " LINK "SmartWrap"} @{" CODE Command " LINK "Code"} @{" Fonts For Text " LINK "Fonts"} @{" Window Size " LINK "WinSize"} @{" Miscellaneous Non-Commands " LINK "MiscNon"} @{" Macros " LINK "Macros"} @{" MAIN INDEX " LINK "AGHTW_Index/Main"} @{JCENTER}=== End of Text === @ENDNODE @NODE "GlobalLocal" "How To Write AG - Global & Local Commands (Pt3)" @TOC "AGHTW_Index/Contents" @PREV "AGHTW_Part2/Beep" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS GLOBAL & LOCAL COMMANDS@{UB}@{UU} (This section does @{B}NOT@{UB} include @{"Attribute Commands" LINK "AGHTW_Part4/Attributes"}.) @{JLEFT} Commands are defined as either (remember that @{"# = @" LINK "AGHTW_Part1/Important"}):- - @{"GLOBAL" LINK "Global"} - they act on all nodes of the document and are @{"placed between" LINK "AGHTW_Part1/Header"5} #DATABASE and #NODE "Main". - @{"LOCAL" LINK "Local"} - they act only on the node in which they are contained and are @{"placed between" LINK "AGHTW_Part1/Nodes"17} #NODE "NodeName" and #ENDNODE It should be noted that some commands can be used as either GLOBAL or LOCAL depending on their placement. Lists of commands available are given under the @{"GLOBAL" LINK "Global"} or @{"LOCAL" LINK "Local"} headings and they are discussed under these headings:- @{" Cross Referencing " LINK "Cross"} @{" Style (Bold, Italic, Underlining) " LINK "AGHTW_Part4/Style"} @{" Colouring Text & Background " LINK "AGHTW_Part4/Colouring"} @{" Word Wrapping " LINK "Wrapping"} @{" TAB Commands " LINK "AGHTW_Part4/TabCommands"} @{" Justification Of Text " LINK "AGHTW_Part4/Justification"} @{" Fonts For Text " LINK "Fonts"} @{" Line and Paragraph Indicators " LINK "AGHTW_Part4/LinePara"} @{" Indent Commands " LINK "AGHTW_Part4/Indents"} @{" Window Size " LINK "WinSize"} @{" Miscellaneous Non commands " LINK "MiscNon"} @{" Macros " LINK "Macros"} @{JCENTER}=== End of Text === @ENDNODE @NODE "Global" "How To Write AG - Global Commands (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS GLOBAL COMMANDS@{UB}@{UU} @{JLEFT} Global commands are defined as those which affect all nodes in the whole of the document. We have already discussed the placement of global commands under the heading @{"Document Header" LINK "AGHTW_Part1/Header"23}. In summary, make sure that global commands:- - are on a line of their own - have the \@ as the first character of the line (no spaces before it) - are situated between #DATABASE and #NODE "MAIN" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) @{B}@{U}Global Commands Available@{UB}@{UU} @{" AUTHOR " LINK "MiscNon"25} All Versions @{" (C) " LINK "MiscNon"31} All Versions @{" DATABASE " LINK "AGHTW_Part1/Database"} All Versions @{" FONT " LINK "Fonts"17} Versions 39 and 40 - Can also be used as a LOCAL command @{" HEIGHT " LINK "WinSize"} All Versions @{" HELP " LINK "HelpCom"} Versions 39 and 40 @{" INDEX " LINK "IndexCom"} All Versions @{" MACRO " LINK "Macros"} Version 40 - Can also be used as a LOCAL command @{" MASTER " LINK "MiscNon"86} All Versions @{" ONCLOSE " LINK "AGHTW_Part2/OnOpenClose"} Version 40 - Can also be used as a LOCAL command @{" ONOPEN " LINK "AGHTW_Part2/OnOpenClose"} Version 40 - Can also be used as a LOCAL command @{" REM " LINK "MiscNon"37} All Versions - Can also be used as a LOCAL command @{" REMARK " LINK "MiscNon"37} All Versions - Can also be used as a LOCAL command @{" SMARTWRAP " LINK "SmartWrap"} Version 40 - Can also be used as a LOCAL command @{" TAB " LINK "AGHTW_Part4/Tabn"} Version 40 - Can also be used as a LOCAL command @{" $VER: " LINK "MiscNon"43} All Versions @{" WIDTH " LINK "WinSize"} All Versions @{" WORDWRAP " LINK "WordWrap"} Version 39 and 40 - Can also be used as a LOCAL command @{JCENTER}=== End of Text === @ENDNODE @NODE "Local" "How To Write AG - Local Commands (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS LOCAL COMMANDS@{UB}@{UU} @{JLEFT} These are the commands that affect only the node in which they are used. As @{"previously discussed" LINK "AGHTW_Part1/Nodes"17}, local commands are best placed immediately after the #NODE command (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) where they can be easily found although they appear to work if placed anywhere between the #NODE and #ENDNODE commands. There is also a sub group of local commands called @{"Text Attribute Commands" LINK "AGHTW_Part4/Attributes"}. @{B}@{U}Local Commands Available@{UB}@{UU} The local commands that can be used are:- @{" FONT " LINK "Fonts"17} Version 39 and 40 - Can also be used as a GLOBAL command @{" DNODE " LINK "AGHTW_Part1/DNode"} All Versions @{" ENDNODE " LINK "AGHTW_Part1/EndNode"} All Versions @{" MACRO " LINK "Macros"} Version 40 - Can also be used as a GLOBAL command @{" NEXT " LINK "NextPrev"} All Versions @{" NODE " LINK "AGHTW_Part1/Node"} All Versions @{" ONCLOSE " LINK "AGHTW_Part2/OnOpenClose"} Version 40 - Can also be used as a GLOBAL command @{" ONOPEN " LINK "AGHTW_Part2/OnOpenClose"} Version 40 - Can also be used as a GLOBAL command @{" PREV " LINK "NextPrev"} All Versions @{" REM " LINK "MiscNon"37} All Versions - Can also be used as a GLOBAL command @{" REMARK " LINK "MiscNon"37} All Versions - Can also be used as a GLOBAL command @{" SMARTWRAP " LINK "SmartWrap"} Version 40 - Can also be used as a GLOBAL command @{" TAB " LINK "AGHTW_Part4/Tabn"} Version 40 - Can also be used as a GLOBAL command @{" TITLE " LINK "AGHTW_Part1/Title"} All Versions @{" TOC " LINK "Toc"} All Versions @{" WORDWRAP " LINK "WordWrap"} Version 39 and 40 - Can also be used as a GLOBAL command @{JCENTER}=== End of Text === @ENDNODE @NODE "Cross" "How To Write AG - Cross Referencing (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS CROSS REFERENCING@{UB}@{UU} @{JLEFT} Apart from the normal @{"linking commands" LINK "AGHTW_Part2/Commands"}, there are some commands that will enable the Amigaguide document author to allow the reader to jump to other parts of document or to other documents. These commands are @{"HELP" LINK "HelpCom"} @{"INDEX" LINK "IndexCom"} @{"NEXT & PREV" LINK "NextPrev"} and @{"TOC" LINK "Toc"}. @{JCENTER}=== End of Text === @ENDNODE @NODE "HelpCom" "How To Write AG - Help Command (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS @{B}@{U}HELP Command Versions 39 and 40 - GLOBAL Command@{UU}@{UB} @{JLEFT} When a user clicks on the Amigaguide "HELP" button, a default help file called "Help.guide" or "Amigaguide.guide" is called up. This file's name and location varies according to versions:- @{U}Help File Name@{UU} @{U}Help File Location@{UU} Earlier versions help.guide S: Later versions Amigaguide.guide Help:English/Sys * * substitute your language for "English" * "Help:" is assigned at startup to "Sys:Locale/Help" In versions 39 and 40, the "HELP" command overrides the use of the above mentioned default help file and substitutes the author's own help file. It can be used in one of these ways:- #HELP "NodeName" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) #HELP "Path/Document/NodeName" (See @{"Path Names" LINK "AGHTW_Part2/PathNames"}) The first example above links to a node in the same document and the second to a node in an external document. @{"Click here" LINK "Miscellaneous/Helpdoc.guide/Main"} to enter a document that has an embedded #HELP command. @{U}Important Notes For HELP@{UU} Although I have seen it reported that HELP is a local command as well as a global command, I have only been able to get it to work as a global command @{B}EVEN IF LOCATED AS A LOCAL COMMAND!!@{UB}. If you have a HELP command that links to a node in the same document, then the default help will NOT be available at all. If you have a HELP command that links to a node in an external help document and that external document does NOT have a HELP command then the default help file WILL be accessible from within that external help document. So, where I feel my own help file is needed rather than the default one, I create an external help file rather than a help node in the same document and tell readers that they can read the default help file from there. @{JLEFT} @{JCENTER}=== End of Text === @ENDNODE @NODE "IndexCom" "How To Write AG - Index Command (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS @{B}@{U}INDEX Command All Versions - GLOBAL Command@{UU}@{UB} @{JLEFT} This command tells Amigaguide which node to link to the "Index" button at the top of the Amigaguide window. It is used like this:- #INDEX "NodeName" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) As with any other node link, you can link it to a node in an external document by using its @{"path name" LINK "AGHTW_Part2/PathNames"}:- #INDEX "Path/DocumentName/NodeName" These documents have this command line used as a global command:- #INDEX "AGHTW_Index/Index" Therefore, clicking in the "Index" button will take you to the node called "Index" in the main index file. @{U}Important Note For INDEX@{UU} Although I have seen it reported that INDEX is a local command as well as a global command, I have only been able to get it to work as a global command @{B}EVEN IF LOCATED AS A LOCAL COMMAND!!@{UB}. @{JCENTER}=== End of Text === @ENDNODE @NODE "NextPrev" "How To Write AG - Next & Prev Commands (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS @{B}@{U} @{B}@{U}NEXT and PREV All versions - LOCAL Commands@{UU}@{UB} @{JLEFT} If the commands NEXT and PREV are not used then, when the Amigaguide or Multiview buttons "Browse <" and "Browse >" are clicked, the reader is taken to the previous or next node (respectively) in the document. By next or previous I mean those that are physically on either side of the node being read. If the reader is at the first node then the "Browse <" button is shaded and unusable. Similarly, if the reader is at the last node then the "Browse >" button is shaded and unusable. If the document author wishes the reader to be taken elsewhere when using "Browse <" or "Browse >" then he/she can use the \@PREV or \@NEXT commands. For example:- #NEXT "NodeName" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) #PREV "NodeName" Or, if the next and previous nodes are to be in a document other than the one currently being read (e.g. from the last node of one document to the first node of another, or from the first node of one to the last node of another):- #NEXT "Path/DocumentName/NodeName" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) #PREV "Path/DocumentName/NodeName" If your Amigaguide document is all contained in the one disk file and the nodes are physically arranged in the order in which you wish them to appear when the "Browse <" or "Browse >" buttons are selected, then you do not need to use these two commands. However, if you have split your document into two or more disk files (as I have with this set) then you may wish to use NEXT and PREV in the first and last node of each file to link to the next and previous disk files. In this set I have used NEXT and PREV as described in the above paragraph and also to make "Browse <" or "Browse >" skip over nodes that are really sub nodes of others. For example, there is a sequence of nodes with these names in this document:- * Wrapping * WordWrap * SmartWrap WrappingExample WrappingExample2 * Code * Fonts FontsExample * WinSize But I have set up NEXT and PREV commands to take the user only to those nodes marked with an asterisk in the above list as the other nodes (without the *) are what I consider "sub nodes". In these "sub nodes" I have used:- #NEXT "" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) #PREV "" This effectively disables the "Browse <" or "Browse >" buttons by referring to a non existent node and makes sure the reader must use the "Retrace" button to get back to the main node. You could also use the NEXT and PREV commands if you tack on nodes at the end of a document that are logically related to nodes somewhere else within the document but I would consider this to be bad house keeping. It is easy enough to insert a new node into its correct logical position. @{JCENTER}=== End of Text === @ENDNODE @NODE "Toc" "How To Write AG - TOC Command (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS TOC - All versions - LOCAL Command@{UU}@{UB} @{JLEFT} This allows a node to be defined as the "Table Of Contents" (TOC). Normally, when you click on the "Contents" button at the top left of the Amigaguide/Multiview window, you are taken to the "MAIN" node. If you wish to change this to another node, then put this command in the node as a local command:- #TOC "NodeName" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) The above example will work if the node name is in the same document. You can also make it refer to a node in another document. For example:- #TOC "Sys:Documents/Contents/MAIN" (see @{"Path Names" LINK "AGHTW_Part2/PathNames"}) The above example would cause a click on the "Contents" button to take you to the "MAIN" node of the document called "Contents" that is stored in the drawer "Sys:Documents". As @{B}TOC@{UB} is a @{"Local" LINK "AGHTW_Part5/Local"} command only, it must be placed in @{B}EVERY@{UB} node in which a node other the that document's "MAIN" node is to be used as the "Table Of Contents". The TOC command could be useful if you have different Tables of Contents for different nodes in the document. For example, I have set up the "CONTENTS" button of these documents to take you to:- - The @{"MAIN menu" LINK "AGHTW_Index/Main"} from nodes accessible from that menu - The @{"CONTENTS menu" LINK "AGHTW_Index/Contents"} from nodes accessible from that menu The trouble with using the TOC command and/or the "CONTENTS" button is that, if you click on the "CONTENTS" button a lot then try the "RETRACE" button, you may have a lot of past history to go through to get back to where you want to be! @{JCENTER}=== End of Text === @ENDNODE @NODE "Wrapping" "How To Write AG - Word Wrapping (Pt3)" @TOC "AGHTW_Index/Contents" @{JCENTER}@{B}@{U}HOW TO WRITE AMIGAGUIDE DOCUMENTS WORD WRAPPING Versions 39 and 40@{UB}@{UU} @{JLEFT} Word wrapping of the text display can be achieved with the use of the commands:- @{" WORDWRAP " LINK "Wordwrap"} Versions 39 and 40 @{" SMARTWRAP " LINK "SmartWrap"} Version 40 only If a document is written so that there are no @{"line feed" LINK "AGHTW_Part5/LineFeed"} characters (@{"ASCII" LINK "AGHTW_Part5/Ascii"} code number 10) at the end of each @{"physical line" LINK "AGHTW_Part5/Physical"} but only at the end of paragraphs then Amigaguide/Multiview will allow the line to extend beyond the right edge of the window and you will need to use the bottom scroll bar and/or gadgets to read the part of the line beyond the right edge. In Amigaguide version 34 there was no alternative. Authors were supposed to make sure that there was a line feed character at the end of each physical line. In Version 39 and 40, proper paragraphs (i.e. @{"logical lines" LINK "AGHTW_Part5/Logical"} that are longer than the size of the display window) can be properly displayed by use of one of the commands @{"WORDWRAP" LINK "Wordwrap"} (v39 & 40) or @{"SMARTWRAP" LINK "SmartWrap"} (v40). The @{"CODE" LINK "Code"} command can also be used to turn off word wrapping. However, if you think there is a chance that your documents may be read by people still using Amigaguide earlier than version 39 then it would be best to format the document using line feeds at the end of each physical line and forget about word wrapping. There is nothing more annoying than having to continually move the horizontal scroll bar while reading a document!!! This document has been written in this way - line feeds at the end of each physical line and, apart from the "demonstration node" (discussed in the section on the @{"CODE Command" LINK "Code"12}), no word wrapping commands. @{JCENTER}=== End of Text === @ENDNODE @NODE "Wordwrap" "How To Write AG - WordWrap Command (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS WORDWRAP Versions 39 & 40 - LOCAL * or GLOBAL Command@{UU}@{UB} @{JLEFT} WORDWRAP is used on a line of its own like this:- #WORDWRAP (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) This command will word wrap lines so that all text is shown within the width of the display window. However, it will act on all line feed characters and start a new line with each line feed. Compare this with @{"SMARTWRAP" LINK "SmartWrap"} which ignores all but double line feeds or the @{"PAR" LINK "AGHTW_Part4/LinePara"13} command. If used as a @{"local command" LINK "AGHTW_Part5/Local"} (see * Note below), WORDWRAP will affect ALL text in the node, even text occurring @{B}before@{UB} the WORDWRAP command, @{B}unless@{UB} a @{"CODE" LINK "Code"} command (in @{B}version 40 only@{UB}) is found after the WORDWRAP command in which case text AFTER the CODE command (in that node only) will NOT be wrapped. If used as a @{"global command" LINK "AGHTW_Part5/Global"}, WORDWRAP will affect ALL text in ALL nodes unless@{UB} a @{"CODE" LINK "Code"} command (in @{B}version 40 only@{UB}) is found in one of the nodes in which case all text AFTER the CODE command (in that node only) will NOT be wrapped. @{B}@{U}* Note For Version 39@{UB}@{UU} In @{B}version 39@{UB} I have only be able to get WORDWRAP to work as a GLOBAL command even though I have seen it described elsewhere as a local as well as a global command for both versions 39 and 40. @{JCENTER}=== End of Text === @ENDNODE @NODE "SmartWrap" "How To Write AG - SmartWrap Command (Pt3)" @TOC "AGHTW_Index/Contents" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS SMARTWRAP Version 40 - LOCAL or GLOBAL Command@{UU}@{UB} @{JLEFT} SMARTWRAP is used on a line of its own like this:- #SMARTWRAP (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) This command will word wrap but, unlike @{"WORDWRAP" LINK "WordWrap"}, it will ignore all line feed characters and insert a space character in their place EXCEPT when two or more line feeds are found together. @{B}To force a new line@{UB}:- - use one @{"PAR" LINK "AGHTW_Part4/LinePara"13} command, or - two line feeds. @{B}To force a new line followed by a blank line@{UB}:- - use two PAR commands, or - one PAR command and two line feeds, or - three line feeds. This command is useful if a document has been written with @{"logical lines" LINK "AGHTW_Part5/Logical"} of a different size, especially a longer size, than the width of the display window. With SMARTWRAP such a document is displayed just as if no line feeds had been used and all text appears within the display window width. The SMARTWRAP command is demonstrated in the "demonstration node" discussed in the section on the @{"CODE Command" LINK "Code"12}. @{JCENTER}=== End of Text === @ENDNODE @NODE "Code" "How To Write AG - Code Command (Pt3)" @TOC "AGHTW_Index/Contents" @NEXT "Fonts" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS {CODE} Version 40 - Local ATTRIBUTE Command@{UU}@{UB} @{JLEFT} This command will TURN OFF word wrapping started by both WORDWRAP and SMARTWRAP. It is used on a line of its own like this:- #{CODE} (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) It is mainly of use when using SMARTWRAP but, for part of the text, you wish to display, for example, a table. This is best illustrated with an example which can be read by @{"clicking here" LINK "WrapExample"}. The {CODE} command only affects text appearing @{B}after@{UB} it. Once word wrapping is turned off in a node there does not appear to be any way to get it turned back on again. That is, another WORDWRAP or SMARTWRAP will @{B}NOT@{UB} change back to wrapped text. This is illustrated by clicking on the above "Clicking here" node label then, in the new node, clicking on another "Click here" label. @{JCENTER}=== End of Text === @ENDNODE @NODE "WrapExample" "How To Write AG - Example SMARTWRAP (Pt3)" @SMARTWRAP @TOC "AGHTW_Index/Contents" @NEXT "" @PREV "" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS EXAMPLE OF SMARTWRAP AND CODE@{UB}@{UU} @{JLEFT}This node has the SMARTWRAP command at the start of it. The following table will therefore appear jumbled up and not how it should appear. @{U}Heading One@{UU} @{U}Heading Two@{UU} Line 1 Line 1 Head 1 Line 1 Head 2 Line 2 Line 2 Head 1 Line 2 Head 2 Line 3 Line 3 Head 1 Line 3 Head 2 @{"Click here" LINK "WrapExample2"} to see how it would appear with the {CODE} command inserted just before the table. @{B}@{U}Note For Versions 34 & 39@{UB}@{UU} If you are reading this with version 34 or 39 then the above table, and that reached when clicking on "Click here", will appear quite normally! @{JCENTER}=== End of Text === @ENDNODE @NODE "WrapExample2" "How To Write AG - Example Of SMARTWRAP and CODE (Pt3)" @SMARTWRAP @TOC "AGHTW_Index/Contents" @PREV "" @NEXT "" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS EXAMPLE OF SMARTWRAP AND CODE@{UB}@{UU} @{JLEFT}This node has the SMARTWRAP command at the start of it. However, unlike the previous node, this time I have put a {CODE} command just before the table. @{CODE} @{U}Heading One@{UU} @{U}Heading Two@{UU} Line 1 Line 1 Head 1 Line 1 Head 2 Line 2 Line 2 Head 1 Line 2 Head 2 Line 3 Line 3 Head 1 Line 3 Head 2 @SMARTWRAP By the way, if you resize your display window to a much smaller width, you can see how SMARTWRAP is working in the paragraph before the table but @{B}NOT@{UB} in this paragraph which is @{B}AFTER@{UB} the {CODE} command @{B}AND @{UB}after another SMARTWRAP located after the table. @{JCENTER}=== End of Text === @ENDNODE @NODE "Fonts" "How To Write AG - Fonts (Pt3)" @TOC "AGHTW_Index/Contents" @PREV "Code" @NEXT "WinSize" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS CHANGING THE FONTS Versions 39 and 40@{UU}@{UB} @{JLEFT} Without any FONT command in the document, Amigaguide/Multiview will use whatever font has been set as the default font for the public screen on which it is opened. This is normally the Workbench screen. In AmigaDOS 2.0 onwards, the default Workbench font can be changed with the Fonts preferences editor. If you wish your Amigaguide document to use another font then you can use the following command in Amigaguide versions 39 and 40. @{B}@{U}FONT - Versions 39 and 40 - LOCAL or GLOBAL Command@{UU}@{UB} This command will set the font to be used in the Amigaguide windows. If used as a global command, all nodes will use the selected font unless there is a local FONT command. If used as a local command, then the selected font will be used only for the node in which it is located. It overrides any global FONT command. It is used in this way:- #FONT fontname.font size (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) For example, to select garnet size 16 you would use:- #FONT garnet.font 16 @{"Click here" LINK "FontExample"} for an example using the above command line. (Garnet 16 is on my original WB2.0, WB2.1 and WB3.1 Fonts disks so I hope you have it in YOUR Fonts: directory!) If Amigaguide cannot find the nominated font then it will use the default font. @{B}@{U}Authors Please Note!!!@{UB}@{UU} If your preferences use a "System Default Text" font size smaller than 8 then you will be seeing a lot more characters per line in your display window than a person using font size 8 which is the font size of the default settings that come with the Amiga. Thus you may unthinkingly put line feeds at the end of lines that are too long for many users who will then have to use the scroll bars and/or scroll gadgets to read the ends of the lines. If you use @{"WORDWRAP" LINK "WordWrap"} or @{"SMARTWRAP" LINK "SmartWrap"} it will only help users of Amigaguide versions 39 or 40 (respectively). Other users will be stuck with scrolling to line ends. I have seen many texts that do not use any word wrapping commands and/or which have far too many characters per line. Even setting the font size in the document itself will only help readers who use Amigaguide versions 39 and 40. @{B}Please@{UB} think about your readers!! @{JCENTER}=== End of Text === @ENDNODE @NODE "FontExample" "How To Write AG - Font Example (Pt3)" @FONT garnet.font 16 @TOC "AGHTW_Index/Contents" @NEXT "" @PREV "" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS EXAMPLE OF FONT COMMAND@{UB}@{UU} @{JLEFT} This node has been set up using the command:- #FONT garnet.font 16 (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) It should look different to all the other nodes in this document unless:- - you are using Amigaguide version 34, and/or - your public screen default font is also garnet 16, (@{B}surely@{UB} you wouldn't use a fancy font like this as a default??!?!?) and/or - you no longer have garnet 16 in your Fonts: directory. @{JCENTER}=== End of Text === @ENDNODE @NODE "WinSize" "How To Write AG - Window Size (Pt3)" @TOC "AGHTW_Index/Contents" @PREV "Fonts" @NEXT "MiscNon" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS WINDOW SIZE Version 34 (see below) - GLOBAL Commands@{UU}@{UB} @{JLEFT} There are two global commands that are supposedly for controlling the size of the window that Amigaguide/Multiview opens. They are:- #HEIGHT (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) #WIDTH where is the number of rows (text lines) for HEIGHT or the number of columns for WIDTH. @{B}WIDTH@{U}@{UU}@{UB} - I have not been able to get this command to work at all with any version or under any conditions. @{B}HEIGHT@{UB} - The only conditions under which I have been able to make this command work is with Amigaguide version 34 and then only when there are no Amigaguide or Multiview environmental variables in which default window sizes have been saved. If there are such variables existing then they appear to override the #HEIGHT command If anyone knows how to get these two commands to work properly then @{"I" LINK "AGHTW_Boring_Stuff/Author"} would appreciate their advice! @{B}@{U}So How To Get The Window Size Desired? (Version 40 Only!)@{UB}@{UU} The method I will now describe does not work in:- - @{B}Version 34@{UB} because, in that version, you cannot save window preferences as you can in later versions. - @{B}Version 39@{UB}@{UU} in the setup that I have been using for tests for some as yet unknown reason. I will look at how to get something working for v39 in a later version but I don't think it is important enough to hold up release of this version. So, for @{B}version 40@{UB}, read on. If you are uncertain of what happens when you select the menu item "Settings/Save As Defaults" then @{"click here" LINK "WinSize2"}. Let's say you want the Multiview display to be in a small window in the top left corner of the Workbench screen. To get a settings file containing the details for such a window just follow these steps. Some of them will need to be done in a Shell/CLI window (those lines starting with the > prompt) or you can use the equivalent commands in your directory utility program (e.g. Directory Opus or DirWork):- 1. Preserve your existing settings file by using this command:- > RENAME Envarc:Multiview/Workbench Envarc:Multiview/Workbench.orig 2. Resize and reposition the display window to the small window in the top left corner (or wherever else you decide). 3. Select the menu item "Settings/Save As Defaults". (This would have overwritten the original file in Envarc: if you had not renamed it.) 4. Copy the new settings file to a safe place (use whatever disk and directory name you like for the destination):- > COPY Env:Multiview/Workbench DiskName:SafeDirectory/Workbench 5. Restore the original settings file as follows:- > DELETE Envarc:Multiview/Workbench > RENAME Envarc:Multiview/Workbench.orig Envarc:Multiview/Workbench > COPY Envarc:Multiview/Workbench Env:Multiview/Workbench @{"Click here" RX "Miscellaneous/Demo_Of_Settings.rexx"} to see a window opened using a settings file obtained in the above manner. I have saved two such files in the "Miscellaneous" directory:- MV_Settings - from a Multiview window AG_Settings - from an Amigaguide window (I think that the one file would work with both Amigaguide and Multiview but I have not had time yet to fully confirm it so I have included both "just in case"!!) The above button assumes that this document is being read on the Workbench screen. If you have somehow managed to transfer it to another screen then the button will show the new document on the Workbench screen, not on the screen you are using. The above "Click here" button is set up like this:- \@{"Click here" RX "Miscellaneous/Demo_Of_Settings.rexx"} The file that is executed when you click on the button, i.e. that with the path and name "Miscellaneous/Demo_Of_Settings.rexx" can be read by @{"Clicking here" LINK "Miscellaneous/Demo_Of_Settings.rexx/MAIN"}. @{"Click here" LINK "WinSize3"} for a line by line description of this file if you cannot follow what it is doing. The main thing is that we do @{B}NOT@{UB} want to upset our readers by overwriting the window setting files that they may have carefully saved! So the script will only replace the file in Env: and will not touch the file in Envarc: - it will copy my own settings file to Env:Multiview/ or Env:Amigaguide/ and give it the name "Workbench" before calling Multiview or Amigaguide to open a new window. After that window is exited, the user's own settings file (if it exists) will be copied from Envarc: to Env: @{JCENTER}=== End of Text === @ENDNODE @NODE "WinSize2" "How To Write AG - Window Size (Pt3)" @TOC "AGHTW_Index/Contents" @PREV "" @NEXT "" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS WINDOW SIZE - EXPLANATION OF SAVING THE SETTINGS@{UB}@{UU} @{JLEFT} If you reposition and resize your display window to whatever you like then select the menu item:- Settings/Save As Defaults you will save that window size and position. The next time that you use Amigaguide or Multiview the saved window size will be used instead of the default window size. The settings are stored in a file with the same name as the screen on which the window is being displayed. For example, if it is using:- The Workbench screen - the file name is Workbench The DOPUS.1 screen - the file name is DOPUS.1 Multiview's own screen - the file name is Multiview (DOPUS.1 is the screen name for Directory Opus if it is the first copy of Directory Opus that is run. If you are using a second copy of Directory Opus that was started while another was already running then the screen name would be DOPUS.2, and so on.) By using screen names, Amigaguide/Multiview can "remember" different settings for different screens. The settings file is stored in these directories:- For Amigaguide - Envarc:Amigaguide/ and Env:Amigaguide/ For Multiview - Envarc:Multiview/ and Env:Multiview/ When the settings are saved the settings file is saved in @{B}BOTH@{UB} places. If the directories do not yet exist, then they are automatically created before the files are saved. For example, if you have Multiview running on the Workbench screen then these two files would be saved:- Env:Multiview/Workbench Envarc:Multiview/Workbench When the Amiga is booted up, everything in Envarc: (which is on the disk you boot from) is copied to Env: (which is in Ram:). When Amigaguide or Multiview are started up, they look in their own directory in Env: (but @{B}NOT@{UB} in Envarc:) for the window settings file. @{JCENTER}=== End of Text === @ENDNODE @NODE "WinSize3" "How To Write AG - Window Settings (Pt3)" @TOC "AGHTW_Index/Contents" @PREV "" @NEXT "" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS WINDOW SIZE - EXPLANATION OF WINDOW SETTING SCRIPT@{UB}@{UU} @{JLEFT} The script to operate the demonstration of window settings is explained below. The actual script lines are in bold (if you have version 39 or 40). Explanations in plain text follow lines that need explanations. @{B}/* ARexx Script to Reset Window Settings */ PortName = ADDRESS()@{UB} This preserves the ARexx port name of the program displaying this document in the variable name "PortName". It will be one of these depending on whether Multiview or Amigaguide is being used:- MULTIVIEW.1.1 AMIGAGUIDE.1.1 If you are running other copies of Amigaguide or Multiview then the "1.1" may be different. This does not matter as all this script does is pick out the "MULTIVIEW" or "AMIGAGUIDE" part of the port name. @{B}ADDRESS 'COMMAND'@{UB} This tells ARexx to send any non ARexx commands to AmigaDOS which has a port name of "COMMAND". @{B}IF LEFT(PortName,9) = 'MULTIVIEW' THEN DO @{UB} This looks at the left 9 characters of "PortName" and decides if they are equal to "MULTIVIEW". If so, the following 6 lines are activated. If not, then the script will jump down to the line starting "@{B}ELSE IF@{UB}". @{B} IF EXISTS('Env:Multiview') = 0 THEN 'MAKEDIR Env:Multiview'@{UB} This tests to see if the directory "Env:Multiview/" exists. If it doesn't, then the "MAKEDIR ... " command is sent to AmigaDOS to create the directory. @{B} 'COPY >Nil: Miscellaneous/MV_Settings Env:Multiview/Workbench'@{UB} This line sends to AmigaDOS the "COPY .... "command which puts my own settings file into the "Env:Multiview/" directory. @{B} 'MULTIVIEW Miscellaneous/Demo_Of_Settings.guide'@{UB} This line sends the command "MULTIVIEW ... " to AmigaDOS. The script will not proceed beyond this point until the new Multiview window is closed. @{B} IF EXISTS('Envarc:Multiview/Workbench') THEN, 'COPY >Nil: Envarc:Multiview/Workbench Env:Multiview/'@{UB} This line checks for the existence of the file "Envarc:Multiview/Workbench" and if it does exist, the "COPY .... " command is sent to AmigaDOS to copy the original "Workbench" file into the "Env:Multiview/" directory. This overwrites the file copied there by the previous "COPY" command and restores everything back to where it was before the script started. @{B}ELSE 'DELETE Env:Multiview/Workbench'@{UB} If the user does NOT have a settings file in Envarc: this line will operate. It ensures that my own settings file is deleted so that it will not be used for other Multiview operations. @{B} EXIT@{UB} The rest of the script is only of interest if "Multiview" is not being used so we can now EXIT the script. @{B}END@{UB} The above @{B}END@{UB} finishes of the @{B}THEN DO @{UB}in the line near the start that reads @{B}IF LEFT(PortName,9) = 'MULTIVIEW' THEN DO @{UB} With the exception of the "@{B}FAILAT@{UB}" lines, the next part of the script from "@{B}ELSE IF@{UB}" to "@{B}END@{UB}" is the same as the above lines used for "Multiview" except that "Amigaguide" is substituted for "Multiview" @{B}ELSE IF LEFT(PortName,10) = 'AMIGAGUIDE' THEN DO IF EXISTS('Env:Amigaguide') = 0 THEN 'MAKEDIR Env:Amigaguide' 'COPY >Nil: Miscellaneous/AG_Settings Env:Amigaguide/Workbench' OPTIONS FAILAT 217@{UB} This line sets the FAILAT level to 217. For some strange reason, Amigaguide sometimes fails with a return code of 216 when the close gadget is clicked. The ARexx scripts seems to keep going even if AmigaDOS reports an error level but using this command stops too many error messages appearing if Amigaguide was started from a Shell/CLI window. @{B}'AMIGAGUIDE Miscellaneous/Demo_Of_Settings.guide' OPTIONS FAILAT 10@{UB} This OPTIONS FAILAT line simply restores the failat level to the normal 10 in case any of the following commands fail. @{B}IF EXISTS('Envarc:Amigaguide/Workbench') THEN, 'COPY >Nil: Envarc:Amigaguide/Workbench Env:Amigaguide/' ELSE 'DELETE Env:Amigaguide/Workbench' EXIT END@{UB} The above @{B}END@{UB} finishes off the @{B}THEN DO @{UB}in the line further up that reads @{B}ELSE IF LEFT(PortName,10) = 'AMIGAGUIDE' THEN DO.@{UB} The next few lines are only reached if neither Multiview nor Amigaguide were being used (there are some PD/Shareware programs out there that will read Amigaguide type documents). @{B}CALL OPEN('OutWindow','CON:0/11/640/100/Demo Document Output Window')@{UB} This opens an output window for the message output by the following line. Normally, ARexx outputs to the Shell/CLI window in which it was started but as this document is meant to be started from an icon, there will be no output window unless we create one. @{B}CALL WRITELN('OutWindow','a'x'Sorry, you do not seem to be using either of', 'Amigaguide or Multiview'||'a'x'So I cannot open the window to display', 'the demonstration file')@{UB} This line outputs the message to tell the reader that he/she is not using Multiview or Amigaguide. @{B}DO UNTIL TIME('E') > 7 ; END@{UB} This is simply a 7 second delay to give the user a chance to read the message. @{B}CALL CLOSE('OutWindow')@{UB} And the final line closes the output window. @{JCENTER}=== End of Text === @ENDNODE @NODE "MiscNon" "How To Write AG - Miscellaneous Non Commands (Pt3)" @TOC "AGHTW_Index/Contents" @PREV "WinSize" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS MISCELLANEOUS NON-COMMANDS All Versions - GLOBAL Commands@{UU}@{UB} @{JLEFT} "Non-Commands"??? Well... these are items that do not do anything as in so far as the operation or appearance of the document in the Amigaguide/Multiview window is concerned. They simply allow the author to record information about him/herself as author and/or about the document and its copyright. In reality, if \@ is the first character of a line and Amigaguide/Multiview does not recognise what follows the \@ then that line is @{"completely ignored" LINK "AGHTW_Part1/Unrecognised"}. So you could really put anything into a line following the \@ but it would be best to stick to the following non-commands so that other people will know what you are doing. The non-commands that are part of the Amigaguide library or datatype files are:- @{B}@{U}AUTHOR - All Versions - GLOBAL Command@{UU}@{UB} To record the authors name. For example:- #AUTHOR Frank Bunton (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) @{B}@{U}(C) - All Versions - GLOBAL Command@{UU}@{UB} To record the copyright details. For example:- #(C) 1998 Frank P. Bunton (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) @{B}@{U}REM or @{B}REMARK - All Versions - Global & Local Commands@{UU}@{UB} To record comments about the document. For example:- #REM this is a comment line (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) @{B}@{U}$VER: - All Versions - GLOBAL Command@{UU}@{UB} To record the documents version number:- #$VER: DocumentName xx.xx (dd.mm.yy) Other comments (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) The VER: @{B}MUST@{UB} be in upper case!! The @{B}"Version String"@{UB} is everything that comes after the \@VER: which, in the above example, is:- DocumentName xx.xx (dd.mm.yy) Other comments There @{B}must@{UB} be a space between the \@$VER: and the start of the string The @{B}"DocumentName"@{UB} must not have any spaces in it. The @{B}"Version Number"@{UB} (the xx.xx) comprises two parts, before and after the dot (.). For example, 22.15 would be revision 15 of version 22. The @{B}"Date"@{UB} must be in () and must be in the format dd.mm.yy For example 12.03.98 for 12th March 1998. Although other date formats might appear to work, they will NOT work properly with all AmigaDOS versions of the VERSION command. (This is explained in one my other productions @{"AmigaDOS For Beginners" LINK "AGHTW_Boring_Stuff/OtherDocs"7}). The @{B}"Other Comments"@{UB} are anything you like to say about the document. But they must all be on the same line as the \@$VER: That is, there must not be any line feed characters before the end of the "Other Comments" The documents in this set have this line as their version string:- #$VER: Amigaguide_How_To_Write_xxx 01.05 (01.01.98) Copyright © 1997/1998 Frank P. Bunton (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) which would give this display if the AmigaDOS "VERSION" command were used on this document:- Amigaguide_How_To_Write_Pt3 01.05 ( 1/01/98) Copyright © 1997/1998 Frank P. Bunton @{B}@{U}MASTER - All Versions - GLOBAL Command@{UU}@{UB} This is supposed to be used to indicate the path and name of the original document from which the Amigaguide document was derived. For example:- #MASTER Sys:Docs/MyOriginalDocument (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) @{JCENTER}=== End of Text === @ENDNODE @NODE "Macros" "How To Write AG - Macros (Pt3)" @MACRO Bold "@{B}" @MACRO UnBold "@{UB}" @MACRO Underline "@{U}$1@{UU}" @MACRO Reverse "@{FG Back}@{BG Text}$1@{FG Text}@{BG Back}" @MACRO Multistyle "@{B}$1@{U}$2@{I}$3@{UB}@{UU}@{UI}" @TOC "AGHTW_Index/Contents" @NEXT "AGHTW_Part4/Attributes" @{B}@{U}@{JCENTER}HOW TO WRITE AMIGAGUIDE DOCUMENTS USING MACROS Version 40 - LOCAL or GLOBAL Command (NOTE - THIS SECTION IS BEST VIEWED WITH VERSION 40!!)@{UB}@{UU} @{JLEFT} The MACRO command is used to create a macro as follows:- #MACRO MacroName "Amigaguide commands" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) The macro can then be used in the Amigaguide document as follows:- #{MacroName} The macro command itself can be used as a @{"Local" LINK "AGHTW_Part5/Local"} or a @{"Global" LINK "AGHTW_Part5/Global"} Command but the macro name itself is only used as a @{B}LOCAL@{UB} command. It is best to use examples to describe what macros are and how to use them. All examples of macros shown below have actually been set up as real macros at the start of this node so that they can be demonstrated. If you are using Amigaguide version 34 then you will NOT be able to see their effect! @{B}@{U}Example Of A Simple Macro@{UB}@{UU} Let's say you wanted a macro to create bold text. Instead of inserting the commands:- #{B}Text to be bold#{UB} (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) You could create a couple of macros as follows:- #MACRO Bold "#{B}" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) #MACRO UnBold "#{UB}" Then you could use:- Some #{Bold}Text to be bold#{UnBold} style (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) which would appear as follows:- Some @{Bold}Text to be bold@{UnBold} style Note - if you are reading this with v34 or 39 then this line will NOT be in bold! This is a very round about and useless way of getting bold but its simplicity makes it a good way to explain how macros work! Macros are of far more use when used as compound macros. @{B}@{U}Example Of A Compound Macro@{UB}@{UU} You can combine two or more commands into the one macro and allow for the insertion of arguments by this means:- #MACRO Underline "#{U}$1#{UU}" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) This would allow for the turning on AND off of underlining with an argument being placed in the middle where the $1 appears. Thus if you used this line:- Some #{Underline "Text to be in underlined"} style It would appear like this:- Some @{Underline "Text to be in underlined"} style (@{B}Note@{UB} - If you are reading this with v34 then, in the above line, "Text to be in underline" will appear as a BUTTON!! With v39 all you will see is "Some style" with nothing between.) A more useful compound macro would be to get @{"reverse video" LINK "AGHTW_Part4/Reverse"} text:- #MACRO Reverse #{FG Back}#{BG Text}$1#{FG Text}#{BG Back} (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) This could then be used in a line like this:- Here is some #{Reverse "reverse video"} text which would appear in the display like this:- Here is some @{Reverse "reverse video"} text (@{B}Note@{UB} - If you are reading this with v34 then, in the above line, "reverse video" will appear as a button! With v39 all you will see is "Here is some text" You can use more than one argument by placing $1 $2 $3 etc., into the macro definition line. As an example:- #MACRO Multistyle "#{B}$1#{U}$2\@{I}$3#{UB}#{UU}#{UI}" So if you used:- This is #{Multistyle "bold " "underlined " "italic"} it would appear like this:- This is @{Multistyle "bold " "underlined " "italic"} (@{B}Note@{UB} - If you are reading this with v34 then the above line will read "This is bold" with the "bold" appearing as a button. With v39, it will read "This is multistyle" with "multistyle" appearing as a button.) Note that spaces @{B}outside@{UB} the inverted commas @{B}do not appear@{UB} in the output. If you want spaces, then put them @{B}inside the inverted commas!@{UB} I haven't yet worked out a @{B}practical@{UB} way to use more than one argument! Please let @{"me" LINK "AGHTW_Boring_Stuff/Author"} know if you have! @{B}@{U}Notes On The Use Of Macros@{UB}@{UU} A macro definition used as a @{"global" LINK "AGHTW_Part5/Global"} command will be active in ALL nodes. A macro definition used as a @{"local" LINK "AGHTW_Part5/Local"} command will be active only in the node in which it is used. If the same name is used twice, then the first used will be the effective one. This means that if the same name is used as a global macro and a local macro then the global macro will be the effective one. @{B}Don't forget that, if you want your document to be compatible with Amigaguide version 34 and 39, then you should not use macros but use the full command names each time! As indicated in the notes with each example, macros can cause some strange outputs in version 34 and 39!!@{UB} @{B}@{U}A Problem With Macros@{UB}@{UU} @{"Michael Schulz" LINK "AGHTW_Boring_Stuff/Credits"13} has reported to me that, if you set up a macro like this:- #MACRO Uline "#{U}$1#{UU}" (remember that @{"# = @" LINK "AGHTW_Part1/Important"}) and then use:- #{Uline "a very long string with more than 255 characters ......} then a system failure will result and a reboot is needed. I have not checked it our with other types of macros but I would expect the same problem would occur. Michael reported using amigaguide.datatype v40.12 which is the same as I use but I could not get problems until a string length of 298 characters was reached. And then the problem was not a system failure but a freeze up of Multiview when the node containing the macros is entered. Anyway, YOU HAVE BEEN WARNED - if you MUST use very long strings then keep them below 255 characters as your readers may experience problems. If you really must use long strings of more than 255 characters then you could use something like this:- #{Uline "String of 250 characters"}#{Uline "String of 250 characters"} Once again, this macro is @{B}VERY @{UB}simplistic and you would only use this sort of thing with more complex macros. Underlining would be done with:- #{U}A very long paragraph(s) .... .... with hundreds .... and hundreds .... of words #{UU} @{JCENTER}=== End of Text === @ENDNODE