APL Wiki|
Size: 2651
Comment: Update
|
Size: 3773
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ## page was renamed from UserCommand_Adoc ## page was renamed from UserCommandAdoc |
## page was copied from UserCommands/ADOC <<TableOfContents>> |
| Line 7: | Line 8: |
| Obviously it makes sense to make ADOCs services available as a User Command. | Obviously it makes sense to make ADOC's services available as a User Command. |
| Line 12: | Line 13: |
| When User Commands got introduced in Dyalog with version 12.1, the User Commands where expected to reside in a sub folder `Salt\Spice` inside the Dyalog installation folder. This means that the script `ADOC.dyalog` attached to this page must go into this directory. Only then the User Commd "ADOC" is recognized. | In order to make `ADOC` available as a user command the script `ADOC_UC.dyalog` ("UC" for User Command) attached to this page must go somewhere where Dyalog is able to find it. There are to options: |
| Line 14: | Line 15: |
| That script, which represents the ADOC User Command, assumes that there is a sibling folder of your APL installation folder available named `UserCommands`. Please make sure that the [[ADOC]] script is copied into this folder `UserCommands`. This enables the User Command script to address the real ADOC script `{MyDyalogInstallationFolder}..\UserCommands\ADOC`. | * Move it into `Salt\Spice` inside the Dyalog installation folder. That's where the Dyalog User Commands are located. * Create a particular folder for your own User Commands. |
| Line 16: | Line 18: |
| For example, in case your version of APL is installed in `C:\Program Files (x86)\Dyalog\Dyalog APL 12.1 Unicode` which is the default on Windows 7 64 bit, then the folder `UserCommands` is supposed to be located at `C:\Program Files (x86)\Dyalog\UserCommands`. | Although the first option is certainly easier, it's actually the second one which is recommended. There are a couple of reasons: * Messing Dyalog scripts with your scripts is not a good idea. * When a new version of Dyalog arrives you are in trouble. * Having a separate folder for your own User Commands allows you to overwrite a Dyalog User Command with an improved version you are not going to loose in case of an update or a new version. To make your own User Command folder work you have to do a couple of things: 1. Add the folder to the SALT search path. 1. Create another folder which is going to host the "real thing". A recommended name is "!UserCommandCode". 1. Copy the script `ADOC.dyalog` from the [[ADOC]] page into that folder. 1. Create a registry entry pointing to that new folder with the name `HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder` Note that the script attached to this page only deals with two issues: * Figure out what command the user wants to invoke, "Browse" or "List". * Find the real work horse and call it, see below. In order to achieve that the script `ADOC_UC.dyalog` reads the `HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder` from the Windows registry. It then tries to load the "real" ADOC script from that folder. Note that not only our examples given on this page but also the code in `ADOC_UC.dyalog` all refer to version 12.1 Unicode of Dyalog. If your are using a different version of Dyalog of course you must change the script, otherwise it's not going to work. |
| Line 27: | Line 49: |
| ADOC ADOC.Browse Creates full documentation and displayes it in the default browser ADOC.List Prints syntax of all public stuff to the session |
ADOC ADOC.Browse Creates full documentation and displayes it in the default browser. ADOC.HELP Displays help regarding ADOC. ADOC.List Prints syntax of all public stuff to the session. |
| Line 32: | Line 55: |
| Script location: ........\SALT\Spice\ADOC | Script location: ........\....\....\ADOC |
| Line 34: | Line 57: |
| Gathers all sort of information from a class script, compiles an HTML page with these pieces of information and displays it in a browser. Use the -b flag to specify a browser different from your default browser. |
Gathers information from a class script, compiles an HTML page with these pieces of information and displays it in your default browser. |
| Line 41: | Line 63: |
| Script location: ........\SALT\Spice\ADOC | Script location: ........\...\...\ADOC |
| Line 46: | Line 68: |
| ]ADOC.Browse ADOC -b=Opera | ]ADOC.Help |
| Line 48: | Line 70: |
Shows extensive information about ADOC. It's basically doing `ADOC.Browse ADOC`. |
|
| Line 52: | Line 76: |
| [[attachment:ADOC.dyalog | Download]] the script. | [[attachment:ADOC_UC.zip | Download]] the script. |
| Line 55: | Line 79: |
| The script is version 1.0.1 from 2010-05-07 | The script is version 1.2.0 from 2011-08-04 |
| Line 59: | Line 83: |
| -- KaiJaeger <<DateTime(2011-08-04T19:54:50Z)>> |
User Command ADOC (Dyalog)
Overview
ADOC is a utility useful to generate documentation (semi-) automatically from class scripts as well as namespace scripts.
Obviously it makes sense to make ADOC's services available as a User Command.
This page offers a small class script ADOC which is designed to do exactly that.
Assumptions
In order to make ADOC available as a user command the script ADOC_UC.dyalog ("UC" for User Command) attached to this page must go somewhere where Dyalog is able to find it. There are to options:
Move it into Salt\Spice inside the Dyalog installation folder. That's where the Dyalog User Commands are located.
- Create a particular folder for your own User Commands.
Although the first option is certainly easier, it's actually the second one which is recommended. There are a couple of reasons:
- Messing Dyalog scripts with your scripts is not a good idea.
- When a new version of Dyalog arrives you are in trouble.
- Having a separate folder for your own User Commands allows you to overwrite a Dyalog User Command with an improved version you are not going to loose in case of an update or a new version.
To make your own User Command folder work you have to do a couple of things:
- Add the folder to the SALT search path.
Create another folder which is going to host the "real thing". A recommended name is "UserCommandCode".
Copy the script ADOC.dyalog from the ADOC page into that folder.
Create a registry entry pointing to that new folder with the name HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder
Note that the script attached to this page only deals with two issues:
- Figure out what command the user wants to invoke, "Browse" or "List".
- Find the real work horse and call it, see below.
In order to achieve that the script ADOC_UC.dyalog reads the HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder from the Windows registry. It then tries to load the "real" ADOC script from that folder.
Note that not only our examples given on this page but also the code in ADOC_UC.dyalog all refer to version 12.1 Unicode of Dyalog. If your are using a different version of Dyalog of course you must change the script, otherwise it's not going to work.
Samples
Given that the two different ADOC scripts went into the right folders, this would be a sample session:
]?ADOC
"??" for general help, "?CMD" for more specific info on command CMD
Group Name Description
===== ==== ===========
ADOC ADOC.Browse Creates full documentation and displayes it in the default browser.
ADOC.HELP Displays help regarding ADOC.
ADOC.List Prints syntax of all public stuff to the session.
]?ADOC.Browse
Command "ADOC.Browse". Syntax: 1 arguments; accepts switches -b=
Script location: ........\....\....\ADOC
Gathers information from a class script, compiles
an HTML page with these pieces of information
and displays it in your default browser.
]?ADOC.List
Command "ADOC.List".
Script location: ........\...\...\ADOC
Prints a list with all sorts of information to the session
about all public stuff given in the script specified in the right argument
]ADOC.Help
Watch your browser
Shows extensive information about ADOC. It's basically doing `ADOC.Browse ADOC`.
Download
Download the script.
Version
The script is version 1.2.0 from 2011-08-04
Author: KaiJaeger
-- KaiJaeger 2011-08-04 19:54:50