Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]


Groups > comp.soft-sys.math.mathematica > #14748 > unrolled thread

Applications and Packages, WRI Strikes Out!

Started by"djmpark" <djmpark@comcast.net>
First post2013-06-05 07:16 +0000
Last post2013-06-11 06:26 +0000
Articles 9 — 5 participants

Back to article view | Back to comp.soft-sys.math.mathematica


Contents

  Applications and Packages, WRI Strikes Out! "djmpark" <djmpark@comcast.net> - 2013-06-05 07:16 +0000
    Re: Applications and Packages, WRI Strikes Out! David Bailey <dave@removedbailey.co.uk> - 2013-06-06 11:23 +0000
      Re: Applications and Packages, WRI Strikes Out! Michael Weyrauch <michael.weyrauch@gmx.de> - 2013-06-07 03:16 +0000
        Re: Applications and Packages, WRI Strikes Out! David Bailey <dave@removedbailey.co.uk> - 2013-06-08 06:32 +0000
      Re: Applications and Packages, WRI Strikes Out! "djmpark" <djmpark@comcast.net> - 2013-06-08 06:33 +0000
    Re: Applications and Packages, WRI Strikes Out! David Annetts <david.annetts@iinet.net.au> - 2013-06-06 11:50 +0000
    Re: Applications and Packages, WRI Strikes Out! "djmpark" <djmpark@comcast.net> - 2013-06-07 03:15 +0000
      Re: Applications and Packages, WRI Strikes Out! David Bailey <dave@removedbailey.co.uk> - 2013-06-08 06:32 +0000
    Re: Applications and Packages, WRI Strikes Out! Syd Geraghty <sydgeraghty@mac.com> - 2013-06-11 06:26 +0000

#14748 — Applications and Packages, WRI Strikes Out!

From"djmpark" <djmpark@comcast.net>
Date2013-06-05 07:16 +0000
SubjectApplications and Packages, WRI Strikes Out!
Message-ID<komok1$1uv$1@smc.vnet.net>
One usage of Mathematica could be as an integrated research, developmental,
educational and communication medium for mathematics and technical subjects.
It's great advantages are its active calculation and dynamics and the
ability to document (with Workbench) and preserve active usable knowledge.
It is an organized method to build up capability. I always thought this was
an implied vision and goal for Mathematica but perhaps I am mistaken.

 

The fact is that the Workbench/Application facilities are only just barely
adequate and then only with ad hoc methods suggested by WRI people, which
either produce error messages (that we are supposed to ignore) or don't work
at all, or that require redoing hundreds of pages of documentation! Much of
the work has to be done by editing underlying expressions. The whole thing
is ill-designed, neglected and shoddily implemented. WRI can add all the
doo-dads they want but without the Application capability Mathematica is
just a super fancy calculator, dynamic information retriever, and minor
programming language for stand-alone results that will be copied out to
other media.

 

Here is an example of poor design. In any application it may be convenient
to break the routines into a collection of sub-packages. From a computer
science point of view the sub-packages should be organized hierarchically so
that as each package is read in it only uses public symbols from packages
already read in. But this is not always convenient and also because of the
historical development of an application a packageA may use a symbol from
packageB and vice versa. Or this may involve other intermediate packages.

 

This is supposed to be taken care of by the second form of the BeginPackage
statement with the list of "needs" contexts needed for the package. The
documentation says: "The interpretation of symbol names depends on context.
BeginPackage thus affects the parsing of input expressions." You can say
that again. But the entire matter is misleading. What the BeginPackage
package needs is the contexts of all the exported symbols used in the
`Private` section, else they will go into the `Private` context of the
current package being loaded. But what WRI does is actually load the entire
packages, along with their own `Private` definitions. This produces a
tangled web that is very difficult to analyze. It definitely produces
multiple definitions of routines, some with exported symbols put into the
`Private` context, and you just have to hope that Mathematica uses the
proper definition. In fact, it won't always. Why doesn't WRI have a
restricted interpretation of "needs" in the BeginPackage statement that just
picks off the exported context names and does not load the definitions? The
`Private` definitions should only be loaded in their own package code where
the developer has supposedly named all the contexts that are needed for it.
Is there some reason that couldn't be done? I hate "computer science" and
pay WRI lots of money to do it. Why can't they do it?

 

I fault Stephen Wolfram for his neglect of facilities for Mathematica
Application development. It appears that nothing has been done for over two
years. There are many problems in the design, implementation and
documentation of Application development in Workbench. When it is so
unstable we don't even know if the entire paradigm might change. 

 

David Park

djmpark@comcast.net 

http://home.comcast.net/~djmpark/index.html 

[toc] | [next] | [standalone]


#14761

FromDavid Bailey <dave@removedbailey.co.uk>
Date2013-06-06 11:23 +0000
Message-ID<koprg8$cgp$1@smc.vnet.net>
In reply to#14748
On 05/06/2013 08:16, djmpark wrote:
> One usage of Mathematica could be as an integrated research, developmental,
> educational and communication medium for mathematics and technical subjects.
> It's great advantages are its active calculation and dynamics and the
> ability to document (with Workbench) and preserve active usable knowledge.
> It is an organized method to build up capability. I always thought this was
> an implied vision and goal for Mathematica but perhaps I am mistaken.
>
>
>
> The fact is that the Workbench/Application facilities are only just barely
> adequate and then only with ad hoc methods suggested by WRI people, which
> either produce error messages (that we are supposed to ignore) or don't work
> at all, or that require redoing hundreds of pages of documentation! Much of
> the work has to be done by editing underlying expressions. The whole thing
> is ill-designed, neglected and shoddily implemented. WRI can add all the
> doo-dads they want but without the Application capability Mathematica is
> just a super fancy calculator, dynamic information retriever, and minor
> programming language for stand-alone results that will be copied out to
> other media.
>

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


[toc] | [prev] | [next] | [standalone]


#14767

FromMichael Weyrauch <michael.weyrauch@gmx.de>
Date2013-06-07 03:16 +0000
Message-ID<korj9h$jcp$1@smc.vnet.net>
In reply to#14761
David,

>
> 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!

well, one really good reason is the multiple Undo facility in the 
workbench as well as the interface to a versioning system. And the 
possibility to produce standard documentation as foreseen by Wolfram.

I personally like the code formatting in the workbench. And also I find
it extremely convenient to use.

So, while I agree that the build-in code editor is very good as well,
I still think for larger projects the Workbench is a good tool and easy 
to use.

Certainly, I have to live with some nuisances e.g. that the greek 
characters appera as \[Alpha] etc., but as far as I am concerned this
is not a real problem.

I understand that the critisism of David Park points mainly to
documentation creation, but that does not justify to call the whole
system "ill-designed, neglected and shoddily implemented". I cannot see 
that.

Michael

[toc] | [prev] | [next] | [standalone]


#14775

FromDavid Bailey <dave@removedbailey.co.uk>
Date2013-06-08 06:32 +0000
Message-ID<kouj5o$su9$1@smc.vnet.net>
In reply to#14767
On 07/06/2013 04:16, Michael Weyrauch wrote:
> David,
>
>>
>> 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!
>
> well, one really good reason is the multiple Undo facility in the
> workbench as well as the interface to a versioning system. And the
> possibility to produce standard documentation as foreseen by Wolfram.
>
> I personally like the code formatting in the workbench. And also I find
> it extremely convenient to use

The lack of multiple UNDO is an extraordinary omission, as is the lack 
of a documented way to produce standard documentation inside 
Mathematica. Unfortunately, I feel these omissions may be motivated by a 
desire to make the workbench more attractive.

I created my own code layout mechanism, so I don't miss this feature.

Versioning might indeed need a different tool - but maybe something more 
dedicated to that task.

To be fair, I tried the workbench years ago, and simply gave up. Maybe 
this disqualifies me from commenting on later versions, but I suspect a 
lot of people may have had a similar experience. I'd only want to try it 
again, if it could display maths properly.

David Bailey
http://www.dbaileyconsultancy.co.uk


[toc] | [prev] | [next] | [standalone]


#14777

From"djmpark" <djmpark@comcast.net>
Date2013-06-08 06:33 +0000
Message-ID<kouj71$sud$1@smc.vnet.net>
In reply to#14761
Several instances of what I consider "ill-design".

1) WRI has not thought out the process of having multiple packages within a
single Application. There is often convenience in grouping routines into
different sub-packages even though this grouping might not be perfect from a
"computer science" perspective. The logic of the BeginPackage statement is
not correctly designed. The second argument or "needs" portion of the
statement should not be establishing definitions from the `Private` section
of the needed package. It should only be establishing the exported symbols.
The only `Private` definitions that should be established should be from the
first argument of the BeginPackage statement. It doesn't seem to me that
this would be difficult to implement. WRI is under the impression that going
to multiple files but putting all symbols in a single context will solve the
problem of symbols going mistakenly into the `Private` context. This is
false. It has nothing to do with the context of exported symbols. It has to
do with the order and unnecessary establishment of routine definitions from
`Private` sections of packages. (To avoid the problems in my current project
I went back to a single package file.)

2) I always develop routines in regular Mathematica, outside of Workbench,
and when I think they're ready I move them to the Workbench files.
Nevertheless, I sometimes find that I want to modify them later. (One of the
advantages of writing Function pages is that if one finds it difficult to
explain a routine or generate meaningful examples then it is a sure sign
that the routine is ill-designed.) So I sometimes find that I'm temporarily
debugging and testing on a Function page. Or this could be done in a regular
notebook in the Workbench folder. But if one evaluates a << package`
statement within Workbench it doesn't load the Workbench package files; it
loads the files from the currently deployed package. It does this even
though I set the Version number in Workbench to a higher value. What sense
does it make to have code files in Workbench where we can modify them if
when we reload the package it uses the unchanged deployed version? One can
use the "Run Package" button but with multiple packages we may want to just
reload the entire Application. And the "Run Package" method does not work if
one uses the WRI method of multiple files with a single context.

3) WRI tries to force users into the box specially designed for their own
documentation: Guide pages, Function pages and Tutorial pages. But user
Application projects will often take a distinctly different coloring.
Specifically, they may want folders with notebooks in their own style sheets
- say a book, or papers or lessons or tutorials done in their own style.
These may be the larger part of the total content of the Application.
Although it is possible to make some links "by hand" I believe the general
linking and indexing process does not handle this.

Several instances of "shoddily implemented ".

1) I believe that in Workbench 1 there was a facility for automatically
generating Function page tables for a routines Options. This no longer works
in Workbench 2 and it has to be done by hand.

2) CellID seems like a good idea and Workbench has links to CellID. However,
if the linked cell is in a closed section or lower level subsection the
notebook is not opened to expose the cell. So the reader still has to search
for it. Links to Cell Tags does expose the actual cell. But it's easier to
make links if one doesn't have to establish a long list of cell tags.

3) The user is hit with a number of warning messages when first using the
DocumentationTools Palette - something about StyleNames. And the
PacletInfo.m files shows warnings even though one is following the WRI
recommendations.

4) The whole matter of using multiple packages is not properly implemented
but that is partly a design fault.

So "shoddily" is probably an overstatement and I apologize for that. Much of
Workbench does work but there is a high standard needed to entice more users
to embrace the Application approach and I believe there is a much larger
group of users that would benefit from it.

Instance of "neglect".

My Workbench 2 version does not appear to be dated but it seems to me that
it's been over two years since there has been an update. As far as I know,
none of the issues concerning user Applications, as opposed to internal WRI
documentation, are being considered or addressed. Also, there is the issue
of long term stability. Users will be hesitant to work within the
Application paradigm if they are not confident they are working in a stable
environment. This means it needs serious initial design with strong feedback
and not just casual in-house design.

I wouldn't complain about it if I didn't think that WRI was basically on the
right track. I just wish they would finish it and polish it.


David Park
djmpark@comcast.net 
http://home.comcast.net/~djmpark/index.html 



From: Michael Weyrauch [mailto:michael.weyrauch@gmx.de] 

I understand that the critisism of David Park points mainly to documentation
creation, but that does not justify to call the whole system "ill-designed,
neglected and shoddily implemented". I cannot see that.

Michael


[toc] | [prev] | [next] | [standalone]


#14765

FromDavid Annetts <david.annetts@iinet.net.au>
Date2013-06-06 11:50 +0000
Message-ID<kopt1f$d9u$1@smc.vnet.net>
In reply to#14748
Hi David,

My recollection was that the late Jens-Per Kuska posted to MathGroup how 
to do this.

D.

On 6/06/2013 19:29, David Bailey wrote:
> On 05/06/2013 08:16, djmpark wrote:
>> One usage of Mathematica could be as an integrated research, developmental,
>> educational and communication medium for mathematics and technical subjects.
>> It's great advantages are its active calculation and dynamics and the
>> ability to document (with Workbench) and preserve active usable knowledge.
>> It is an organized method to build up capability. I always thought this was
>> an implied vision and goal for Mathematica but perhaps I am mistaken.
>>
>>
>>
>> The fact is that the Workbench/Application facilities are only just barely
>> adequate and then only with ad hoc methods suggested by WRI people, which
>> either produce error messages (that we are supposed to ignore) or don't work
>> at all, or that require redoing hundreds of pages of documentation! Much of
>> the work has to be done by editing underlying expressions. The whole thing
>> is ill-designed, neglected and shoddily implemented. WRI can add all the
>> doo-dads they want but without the Application capability Mathematica is
>> just a super fancy calculator, dynamic information retriever, and minor
>> programming language for stand-alone results that will be copied out to
>> other media.
>>
> 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
>
>
>

[toc] | [prev] | [next] | [standalone]


#14772

From"djmpark" <djmpark@comcast.net>
Date2013-06-07 03:15 +0000
Message-ID<korj8s$jcm$1@smc.vnet.net>
In reply to#14748
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



[toc] | [prev] | [next] | [standalone]


#14776

FromDavid Bailey <dave@removedbailey.co.uk>
Date2013-06-08 06:32 +0000
Message-ID<kouj6c$sub$1@smc.vnet.net>
In reply to#14772
On 07/06/2013 04:15, djmpark wrote:
> 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?
>

Although I have a package which I use privately to create documentation, 
I have simply published information about how to use various functions 
that are built into Mathematica:

http://www.dbaileyconsultancy.co.uk/m_documentation/m_documentation.html

Or examine the standard package "DocumentationSearch`".

Their names gave away their functionality - it wasn't a hard job. The 
crucial task is to create the special table that lets your symbols 
respond to F1 in the same way as the built in symbols.

My impression is that the WB probably actually calls Mathematica to 
implement this functionality - otherwise why are these functions present 
in Mathematica!

My explorations were sufficient for my needs, and certainly don't cover 
the extras you describe, but I think it is highly likely that all those 
features are also actually implemented inside Mathematica!

David Bailey
http://www.dbaileyconsultancy.co.uk


[toc] | [prev] | [next] | [standalone]


#14810

FromSyd Geraghty <sydgeraghty@mac.com>
Date2013-06-11 06:26 +0000
Message-ID<kp6fv4$ndu$1@smc.vnet.net>
In reply to#14748
Dear David,

On Jun 6, 2013, at 8:19 PM, djmpark <djmpark@comcast.net> wrote:

> 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


There is a certain irony to be noted in reading Stephen Wolfram's latest blog on the history of Mathematica regarding the importance of documentation for users of Mathematica who wish to develop applications and extensions of the system for use by the Mathematica community.

http://blog.wolfram.com/2013/06/06/there-was-a-time-before-mathematica/

To quote Stephen from the blog:

"Meanwhile, just as for SMP, I'd assembled a team, and started the actual implementation of Mathematica. I'd also started a company this time with me as CEO. Every day I'd write lots of code. (And to my chagrin, quite a bit of that code is still running in Mathematica today, especially in the pattern matcher and evaluator). But my biggest focus was design. And following a practice I'd started with SMP, I wrote documentation as I developed the design. I figured if I couldn't explain something clearly in documentation, nobody was ever going to understand it, and it probably wasn't designed right. And once something was in the documentation, we knew both what to implement, and why we were doing it."

Clearly Stephen recognized and embraced 25 years ago the importance of Documentation in software system development. The irony is that Mathematica users 25 years on feel facilities for producing their own package documentation do not match the exemplary standards of so much else that we admire in Mathematica 9.

There may well be a lot of Stephen's original code still in the Mathematica Documentation facilities which might explain David's valid criticism of the present WRI package and user documentation facilities.


Cheers .... Syd

Syd Geraghty B.Sc, M.Sc.

sydgeraghty@mac.com

Mathematica 9.0.1 for Mac OS X x86 (64-bit) (January 24, 2013)
Release ID 9.0.1.0 (4055646, 4055073)
MacOS X V 10.8.2 Mountain Lion
Mac mini 6,2 Late 2012
2.6 GHz Intel Core i7, 8 GB 1600 MHz DDR3
Graphics  Intel HD Graphics 4000 768 MB

[toc] | [prev] | [standalone]


Back to top | Article view | comp.soft-sys.math.mathematica


csiph-web