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 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@comcast.net
http://home.comcast.net/~djmpark/index.html



From: David Bailey [mailto:dave@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