Date: Jun 6, 2013 11:15 PM
Author: David Park
Subject: Re: Applications and Packages, WRI Strikes Out!
Well I'm tempted but this seems to be a function that is so tightlyintegrated with regular Mathematica and WRI procedures that I hesitate tolearn and use an outside method. Do you handle multiple package files in oneApplication? The automatic link button on usage messages? Links to notebooksthat use private Application style sheets? Automatic Options tables on theFunction pages? Out of place loading of `Private` definitions when all thatis needed is the exported symbols with their Context? CellID links that willopen a notebook to a selected cell in a closed section rather than keepingit hidden?

Workbench 2.0 does allow one to use various editors for package.m notebooksincluding the "System Editor", which is the one I believe you are talkingabout. It allows Titles and the various levels of Sections with openers. Youcan also have Text cells and switch between Code cells and Input cells foreasier editing. The Workbench editor, called "Mathematica Source Editor" issometimes convenient to use. It has a number of features such as formattingcommands, flagging of warnings and errors, Tooltip information on functionsand a feature that highlights every occurrence of a name in the file onceone instance has been selected. (The most common warning I get is leavingunused local variables in Modules.) One can also set the editor to show linenumbers. There is also a Text editor, which I have never used.

There appears to me to be a marked tendency of developers, because of theobscurity and difficulties of the WRI documentation facilities, to developtheir own form of documentation. I think this is a mistake because userswill know the WRI paradigm, which takes a little learning itself, and it'sunfair to ask them to learn new paradigms - one for each Application. (Ibelieve what you are doing, David, does follow the WRI paradigm.)

If you are doing serious work, which involves writing Mathematica routinesand developing written material, then it can really pay to document withGuide and Function pages within an Application format. You can cram a lot ofuseful information on a Function page, including test cases (disguised asexamples or maybe in an explicit Test Case section). It should beintrinsically easy to learn how to do this and, once one learns, not thatdifficult to implement because one would be developing most of the contentin any case.

The problem is that now the documentation methods are highly tuned for WRI'sown 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 anumber of years. It's time to finish the job and do it right.

Please note that I have written up a complete method for generating packagedocumentation without using the Workbench. If anyone has difficulty, pleaselet 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 atotally different nomenclature - I agree completely with David Park.

I can't imagine why anyone would want to edit their package files in theworkbench, when there is a superb package file editor built right in toMathematica! This will read a .m file, display it in StandardForm, let youedit 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 arediscarded and the headings are stored as specially coded Mathematicacomments. This means the next time you edit the package file, the headingscome back up again immediately.

Unless I really want to save the output, I use .m files for almosteverything. Often I find it is more convenient not to save the output - justre-execute the .m file (which needn't hold a package, of course) when Ire-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 onMathematica!

I know the idea of the workbench is that people can do mixed languageprogramming, but I have developed a lot of Java/Mathematica code using Notepad++ to edit the Java, and the above mentioned package editor.