external/openurl/dist/OpenURL/OpenURL.guide

   1 @database OpenURL
   2 @author OpenURL Team
   3
   4 @Node "Main" "OpenURL"
   5
   6   @{b}OpenURL@{ub}
   7
   8
   9   @{b}@{fg fill}Introduction@{fg text}@{ub}
  10
  11     This library was created to make it easier for application
  12     programmers to include clickable URLs in their applications,
  13     about windows, etc. Current solutions to this problem
  14     typically are to launch an ARexx script or just support a few
  15     webbrowsers, with no room for configuration. This leads to
  16     countless reinventions of the wheel (how many
  17     SendURLToBrowser.rexx scripts do you have on your harddisk?).
  18
  19     This library solves the problem by giving application
  20     programmers a very simple API to handle (one function) and
  21     the user gets configurability with the included preferences
  22     program.
  23
  24     Original authors liked and use @{fg shine}MUI@{fg text}, therefore the included
  25     preference program uses MUI. This library is meant to be
  26     completely universal though, so programmers preferring other
  27     GUI engines are encouraged to program their own preference
  28     editor and send it to us, we'll happily include it.
  29
  30
  31   @{b}@{fg fill}Requirements@{fg text}@{ub}
  32
  33     - AmigaOS 3.0 or higher, AmigaOS 4.0 or MorphOS.
  34     - MUI 3.8 or higher, for the preference program only.
  35
  36
  37   @{b}@{fg fill}Features@{fg text}@{ub}
  38
  39     - Sends URL by ARexx if your browser is launched, if not, the
  40       library will launch the browser.
  41
  42     - Configuration supports a list of installed browsers, no
  43       Wind*ws "default browser" nonsense.
  44
  45     - mailto: URLs can optionally be handled by an email
  46       application.
  47
  48     - ftp: URLs can optionnaly be handled by an FTP client.
  49
  50     - Extremely simple API for applications.
  51
  52     - API also available for use from ARexx scripts.
  53
  54     - Complete source available for your enjoyment.
  55
  56
  57   @{b}@{fg fill}Installation@{fg text}@{ub}
  58
  59     To install the library, prefs and shell-tool do:
  60
  61     - backup LIBS:openurl.library, sys:Prefs/OpenURL, C:OpenURL
  62     - copy openurl.library LIBS:
  63     - copy Prefs/OpenURL sys:Prefs/
  64     - copy Prefs/OpenURL.info sys:Prefs/
  65     - copy OpenURL C:
  66
  67     or better use the installation script.
  68
  69
  70   @{b}@{fg fill}Preference Usage@{fg text}@{ub}
  71
  72     Using the preference program should hopefully be very easy. A
  73     few tips might be helpful though. The library will try
  74     contacting the browsers from top to bottom of the list, so
  75     put your favourite browser at the top (drag and drop).
  76
  77     The ARexx portname should be set to "BROWSER" even for
  78     browsers that call their ports "BROWSER.1", "BROWSER.2", etc.
  79     The library will look for any port named "BROWSER.x" where
  80     "x" is a number and ".x" is optional.
  81
  82     For developers: see autodocs.
  83
  84   @{b}@{fg fill}Command-line Usage@{fg text}@{ub}
  85
  86     Using the OpenURL command opens the openurl.library to pass
  87     URLs to the appropriate application depending on the URL's
  88     protocol and the specified OpenURL prefs settings. It can be
  89     executed from a Shell, AmigaDOS script, ARexx script or as a
  90     default tool in the icon for an html file. For example: entering
  91         @{i}OpenURL http://www.os4depot.net@{ui}
  92     in a shell will open the specified URL in the browser set in
  93     your OpenURL prefs.
  94
  95     OpenURL can be used as the default tool in an html project icon.
  96     Several Tooltypes, equivalant to the shell arguments, can also be
  97     used in a project icon. Refer to the Tooltype section below for a
  98     list of available Tooltypes. It can also be used as the default
  99     tool in a default project icon like "def_html" in the Prefs/Env-
 100     Archive/Sys (ENVARC:Sys) drawer. You can then open an html file
 101     that lacks a "real" icon by double-clicking on the html default
 102     icon that will be displayed when a WorkBench window is set to
 103     "Show All Files". OpenURL is not a WorkBench program and cannot
 104     be opened with a tool icon unless "Start From:" is set to "Shell"
 105     and "Prompt for input:" is selected.
 106
 107     The PUBSCREEN argument/tooltype will have no effect with most Amiga
 108     browsers since they have not option to open the browser on a named
 109     public screen with a Shell argument or WorkBench Tooltype. The URL
 110     and FILE Shell arguments have no WorkBench tooltype counterparts
 111     because the "URL" is the "FILE" represented by the project icon
 112     containing OpenURL as a default tool.
 113
 114     @{"u"}@{"b"}OpenURL Shell/Arguments@{"ub"}@{"uu"}
 115
 116       @{"b"}Format:@{"ub"} OpenURL [URL] <name> [NOWSHOW] [NOFRONT] [NEWWIN] [NOLAUNCH] [PUBSCREEN <name>] [FILE]
 117
 118       @{"b"}Template:@{"ub"} URL/A,NOSHOW/S,NOFRONT/S,NEWWIN/S,NOLAUNCH/S,PUBSCREEN/K,FILE/S
 119
 120       @{"b"}Example:@{"ub"} OpenURL "ram:openurl.html" NEWWIN FILE (Open a local html file)
 121
 122       @{"b"}Example:@{"ub"} OpenURL "www.os4depot" NEWWIN NOLAUNCH (Open Internet page)
 123
 124       @{"b"}ARGUMENT@{"ub"}     @{"b"}TYPE@{"ub"}    @{"b"}PRESENCE@{"ub"}        @{"b"}FUNCTION@{"ub"}
 125       URL/A        Text    Required        Quoted URL text ("www.os4depot.net")
 126       NOSHOW/S     Switch  Not Required    Do not uniconify browser
 127       NOFRONT/S    Switch  Not Required    Do not bring browser screen to front
 128       NEWWIN/S     Switch  Not Required    Open the URL in a new browser window
 129       NOLAUNCH/S   Switch  Not Required    Do not start browser if not open
 130       PUBSCREEN/K  Text    Not Required    Screen to open browser on
 131       FILE/S       Switch  Not Required    URL is a file
 132
 133
 134     @{"u"}@{"b"}OpenURL WorkBench/Tooltypes@{"ub"}@{"uu"}
 135
 136       @{"b"}Project Icon - Default Tool:@{"ub"} OpenURL
 137
 138       @{"b"}Project Icon - Start from:@{"ub"} WorkBench
 139
 140       @{"b"}TOOLTYPE@{"ub"}     @{"b"}TYPE@{"ub"}    @{"b"}PRESENCE@{"ub"}        @{"b"}FUNCTION@{"ub"}
 141       NOSHOW/S     Switch  Not Required    Do not uniconify browser
 142       NOFRONT/S    Switch  Not Required    Do not bring browser screen to front
 143       NEWWIN/S     Switch  Not Required    Open the URL in a new browser window
 144       NOLAUNCH/S   Switch  Not Required    Do not start browser if not open
 145       PUBSCREEN/K  Text    Not Required    Screen to open browser on
 146
 147     @{u}@{i}@{fg fill}Important Note@{fg text}@{ui}@{uu}: If the OpenURL prefs program is in your Shell command path
 148     ( SYS:Prefs ) you must use the complete path to the OpenURL command <C:OpenURL>
 149     instead of the <OpenURL> command name alone. Otherwise the OpenURL prefs
 150     will be opened instead of the OpenURL comand. This applies to ToolType
 151     usage as well as Shell execution.
 152
 153   @{b}@{fg fill}Legal stuff@{fg text}@{ub}
 154
 155     The openurl package is placed in the public domain. We assume
 156     no responsibility for what these programs might do, you are
 157     using them at your own risk.
 158
 159
 160   @{b}@{fg fill}Authors@{fg text}@{ub}
 161     Since version 7.2 :
 162     @{b}@{fg shine}OpenURL Team @{fg text}@{ub}
 163       Web: http://sourceforge.net/openurllib
 164
 165     @{b}@{fg shine}Troels Walsted Hansen@{fg text}@{ub}
 166       SnailMail: O.L. Aunesgate 15
 167                  9009 Tromsø
 168                  NORWAY
 169       Email:     troels@thule.no
 170       IRC nick:  Troels
 171
 172     @{b}@{fg shine}Alfonso Ranieri @{fg text}@{ub}
 173       Email:     alforan@tin.it
 174
 175     @{b}@{fg shine}Stefan Kost@{fg text}@{ub}
 176       Email:     ensonic@sonicpulse.de
 177 @EndNode
 178