Re: Comments on the .m file editor
- To: mathgroup at smc.vnet.net
- Subject: [mg87898] Re: Comments on the .m file editor
- From: "David Park" <djmpark at comcast.net>
- Date: Sat, 19 Apr 2008 03:38:09 -0400 (EDT)
- References: <fu9fss$cdu$1@smc.vnet.net>
I don't see the advantages of writing package with the .m file editor. Normally I don't even look at the .m file. I would be interested in hearing comments from some of the sophisticated users about when writing .m files directly might be advantagous. Normally a routine should be written and debugged in a regular Mathematica ..nb notebook. A debugging method that works for almost all cases and is very easy to use is just to insert temporary Print statements into the routine. When a routine is debugged, and a usage message and SyntaxInformation are written it can just be moved to a package.nb notebook with Initialization cells that has been saved as an Auto Generated Package. That is by far the easiest method. You can put (* comments *) anywhere in a Mathematica expression but one very negative feature of Mathematica is that if one uses Shift-Ctrl-N or Shift-Ctrl-I to convert and reformat a cell it strips out all the comments. I think comments should be considered a permanent part of an expression and never stripped out by such reformating. -- David Park djmpark at comcast.net http://home.comcast.net/~djmpark/ "Will Robertson" <wspr81 at gmail.com> wrote in message news:fu9fss$cdu$1 at smc.vnet.net... > Hello, > > As essentially a new user of Mathematica since v6, I'd like to share a > couple of comments about using Mathematica itself to write .m packages > directly. I'm only using v6.0.1 because I can't afford the bug-fix > update right now, so a couple of these comments may no longer be > relevant. > > Firstly, the positives: It's great to be able to write code in an > editor that explicitly understands the syntax. Brace matching and > selection are good, and syntax colouring is excellent. > > Being able to write comments in outline mode is also great; especially > with "input cells" that aren't part of the package but allow you to > execute code; this makes testing and code exposition very convenient > because it can be done inline with the code itself. > > Now, the negatives. The first complaint is more ignorance than > anything: I've got no idea how to use the debugger. It's great that > it's there, but I don't understand how it's supposed to be used. Are > there any tutorials on this feature? > > Next: the editor *really* needs to make up its mind whether it's going > to support "nice" Mathematica symbols or not. It's ridiculous that > typing "-> " gives you a nice arrow, but then closing and re-opening > the file gives you the literal ascii. Worse, typing a complex > expression involving Greek letters and subscripts and accents looks > fine to start with but then turns into an unreadable mess when > re-opening the package. > > Since Mathematica can understand the FullForm in package files, I can't > see the harm in displaying it nicely in the .m file editor. Similarly, > the lack of nice spacing in the typesetting of the code is a shame and > makes packages look uglier -- usually requiring extra whitespace (and > effort) to be readable. > > Finally, the editor doesn't like code that has comments inserted > mid-way through. For example, paste this into a file test.m: > > (* ::Package:: *) > code[hello, > (* ::Text:: *) > (*some explanation*) > there] > > Open it in Mathematica, then select all, cut, and paste (this procedure > emulates you typing in those lines manually). Close and reopen the file > and you'll see that Mathematica has inserted two blank lines in the > code. Yuck. > > Furthermore, this sort of construction kills syntax colouring, which is > a big shame. > It also breaks the "Run Package" button, which tries to evaluate the > package cell by cell (instead, it should simply execute `<<"test.m"`). > > I don't think that cells should be restricted to contain self-contained > chunks of code when large packages deserve better comments than an > essay right before the Module with inline comments like (* we're doing > stuff here *). If those sorts of comments was the only way to document > the code then we may as well not even bother with cells, to be frank. > > *** > > To sum up: the .m file editor is pretty neat but two main additions > would make it much better: explicit support for breaking cells up with > comments whereever you like (including syntax checking and colouring > across cell breaks); and typesetting as in the the notebook editor > (including the extended symbols). In the very least, it shouldn't > interpret typeset symbols unless it intends to preserve them. The > typesetting doesn't affect anyone trying to edit the thing in plain > text and makes the whole thing much nicer to use. > > After all, without nice typesetting we may as well go back to notebooks > with initialisation cells, which have even less ability to be commented > nicely by splitting up cells partway through. > > Any comments from others also using the editor? > > Best regards, > Will Robertson > >