Re: Applications and Packages, WRI Strikes Out!
- To: mathgroup at smc.vnet.net
- Subject: [mg131063] Re: Applications and Packages, WRI Strikes Out!
- From: "djmpark" <djmpark at comcast.net>
- Date: Thu, 6 Jun 2013 23:19:48 -0400 (EDT)
- Delivered-to: l-mathgroup@mail-archive0.wolfram.com
- Delivered-to: l-mathgroup@wolfram.com
- Delivered-to: mathgroup-outx@smc.vnet.net
- Delivered-to: mathgroup-newsendx@smc.vnet.net
- References: <komok1$1uv$1@smc.vnet.net> <31514341.35502.1370518383101.JavaMail.root@m06>
Well I'm tempted but this seems to be a function that is so tightly integrated with regular Mathematica and WRI procedures that I hesitate to learn and use an outside method. Do you handle multiple package files in one Application? The automatic link button on usage messages? Links to notebooks that use private Application style sheets? Automatic Options tables on the Function pages? Out of place loading of `Private` definitions when all that is needed is the exported symbols with their Context? CellID links that will open a notebook to a selected cell in a closed section rather than keeping it hidden? Workbench 2.0 does allow one to use various editors for package.m notebooks including the "System Editor", which is the one I believe you are talking about. It allows Titles and the various levels of Sections with openers. You can also have Text cells and switch between Code cells and Input cells for easier editing. The Workbench editor, called "Mathematica Source Editor" is sometimes convenient to use. It has a number of features such as formatting commands, flagging of warnings and errors, Tooltip information on functions and a feature that highlights every occurrence of a name in the file once one instance has been selected. (The most common warning I get is leaving unused local variables in Modules.) One can also set the editor to show line numbers. There is also a Text editor, which I have never used. There appears to me to be a marked tendency of developers, because of the obscurity and difficulties of the WRI documentation facilities, to develop their own form of documentation. I think this is a mistake because users will know the WRI paradigm, which takes a little learning itself, and it's unfair to ask them to learn new paradigms - one for each Application. (I believe what you are doing, David, does follow the WRI paradigm.) If you are doing serious work, which involves writing Mathematica routines and developing written material, then it can really pay to document with Guide and Function pages within an Application format. You can cram a lot of useful information on a Function page, including test cases (disguised as examples or maybe in an explicit Test Case section). It should be intrinsically easy to learn how to do this and, once one learns, not that difficult to implement because one would be developing most of the content in any case. The problem is that now the documentation methods are highly tuned for WRI's own requirements. The Workbench procedures for users appear to be a spinoff. They are not easily applied to the needs of Application development and use. The present WRI package and user documentation facilities are ill-designed, buggy, unintuitive and unstable. WRI has been dangling this out there for a number of years. It's time to finish the job and do it right. David Park djmpark at comcast.net http://home.comcast.net/~djmpark/index.html From: David Bailey [mailto:dave at removedbailey.co.uk] Please note that I have written up a complete method for generating package documentation without using the Workbench. If anyone has difficulty, please let me know. I don't think the workbench will ever really be integrated into Mathematica - not least because it can't display the complete Mathematica character set! I haven't tried the workbench for years, but when I did, I found it used a totally different nomenclature - I agree completely with David Park. I can't imagine why anyone would want to edit their package files in the workbench, when there is a superb package file editor built right in to Mathematica! This will read a .m file, display it in StandardForm, let you edit it and execute code as if it were a notebook. You can also add headings (but not colour), and when you save the result, any output cells are discarded and the headings are stored as specially coded Mathematica comments. This means the next time you edit the package file, the headings come back up again immediately. Unless I really want to save the output, I use .m files for almost everything. Often I find it is more convenient not to save the output - just re-execute the .m file (which needn't hold a package, of course) when I re-load it. I'm not sure if WRI downplay this feature because the workbench 'competes' with it, but honestly, they should forget the workbench, and build on Mathematica! I know the idea of the workbench is that people can do mixed language programming, but I have developed a lot of Java/Mathematica code using Notepad++ to edit the Java, and the above mentioned package editor. David Bailey http://www.dbaileyconsultancy.co.uk