Differences between revisions 16 and 32 (spanning 16 versions)
⇤ ← Revision 16 as of 2011-08-04 19:54:50 →
Size: 3730
Editor: KaiJaeger
Comment: New version of the User Command script
← Revision 32 as of 2017-07-17 17:07:46 → ⇥
Size: 4240
Editor: KaiJaeger
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
<<TableOfContents>> = User Command ADOC =
Line 3: Line 3:
= User Command ADOC (Dyalog) = || '''Note:''' With version 16.0 ADOC became an official Dyalog user command||
Line 11: Line 12:
== 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:

 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.		 Refer to UserCommands/WhereShouldTheyGo for advice how to organize your User Commands.
Line 43: Line 18:
      ]?ADOC
"??" for general help, "?CMD" for more specific info on command CMD		       ]?ADoc
Command "TOOLS.ADoc". Syntax:
Accepts modifiers -browser= -summary[=] -title=
 Modifier 'summary' accepts only values "full"
                                                                                               
Automated documentation generation
]??ADoc ⍝ for syntax details
]???ADoc ⍝ to view the complete ADoc documentation in a browser window
                                                                                               
Script location: ...
Line 46: Line 29:
 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
Command "TOOLS.ADoc". Syntax:
Accepts modifiers -browser= -summary[=] -title=
 Modifier 'summary' accepts only values "full"
                                                                                                   
Gathers information about one or more classes and/or namespaces.
Either compiles an HTML page which is then displayed in a browser (default) or prints summarizing
information to the session (-summary).
                                                                                                   
 -title={text} Add a custom title with the content {text}
 -browser={path} Use the non-default browser specified
 -summary[=full] Return summarized information about the object members (optionally including full
                  functions headers)
                                                                                                   
Examples:
    ]ADoc MyClass ⍝ single class
    ]ADoc MyClass FilesAndDirs ⍝ two classes
    ]ADoc MyClass -title="My Doc" ⍝ custom title
    ]ADoc MyClass -browser="c:\opera.exe" ⍝ custom browser
    ]ADoc MyClass -summary ⍝ basic info about #.MyClass
                                                                                                   
]???ADoc ⍝ to view the complete ADoc documentation in a browser window
                                                                                                   
Script location: ...
Line 52: Line 54:
      ]?ADOC.Browse
Command "ADOC.Browse". Syntax: 1 arguments; accepts switches -b=
Script location: ........\....\....\ADOC		       ]???ADoc
Line 56: Line 56:
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`.		 Shows extensive information about ADOC in your default browser.
Line 75: Line 61:
[[attachment:ADOC_UC.zip | Download]] the script. This user command cannot be downloaded on its own. It is part of the ADOC download: only together with the workspace can the user command be executed. See http://download.aplwiki.com
Line 78: Line 64:
The script is version 1.2.0 from 2011-08-04 The User Command script is version 2.38 from 2017-06-27.
Line 82: Line 68:
-- KaiJaeger <<DateTime(2011-08-04T19:54:50Z)>>

User Command ADOC

Note: With version 16.0 ADOC became an official Dyalog user command

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.

Refer to UserCommands/WhereShouldTheyGo for advice how to organize your User Commands.

Samples

Given that the two different ADOC scripts went into the right folders, this would be a sample session: 

      ]?ADoc
Command "TOOLS.ADoc". Syntax:                                                                  
Accepts modifiers -browser= -summary[=] -title=                                                
 Modifier 'summary' accepts only values "full"                                                 
                                                                                               
Automated documentation generation                                                             
]??ADoc   ⍝ for syntax details                                                                 
]???ADoc  ⍝ to view the complete ADoc documentation in a browser window                        
                                                                                               
Script location: ...                                                                                               

]??ADoc
Command "TOOLS.ADoc". Syntax:                                                                      
Accepts modifiers -browser= -summary[=] -title=                                                    
 Modifier 'summary' accepts only values "full"                                                     
                                                                                                   
Gathers information about one or more classes and/or namespaces.                                   
Either compiles an HTML page which is then displayed in a browser (default) or prints summarizing  
information to the session (-summary).                                                             
                                                                                                   
 -title={text}    Add a custom title with the content {text}                                       
 -browser={path}  Use the non-default browser specified                                            
 -summary[=full]  Return summarized information about the object members (optionally including full
                  functions headers)                                                               
                                                                                                   
Examples:                                                                                          
    ]ADoc MyClass                          ⍝ single class                                          
    ]ADoc MyClass FilesAndDirs             ⍝ two classes                                           
    ]ADoc MyClass -title="My Doc"          ⍝ custom title                                          
    ]ADoc MyClass -browser="c:\opera.exe"  ⍝ custom browser                                        
    ]ADoc MyClass -summary                 ⍝ basic info about #.MyClass                            
                                                                                                   
]???ADoc  ⍝ to view the complete ADoc documentation in a browser window                            
                                                                                                   
Script location: ...

      ]???ADoc

Shows extensive information about ADOC in your default browser.

Download

This user command cannot be downloaded on its own. It is part of the ADOC download: only together with the workspace can the user command be executed. See http://download.aplwiki.com

Version

The User Command script is version 2.38 from 2017-06-27.

Author: KaiJaeger

CategoryDyalogUserCommands

UserCommands/Adoc (last edited 2019-05-30 07:31:15 by KaiJaeger)