Re: Comments on the .m file editor
- To: mathgroup at smc.vnet.net
- Subject: [mg87920] Re: Comments on the .m file editor
- From: Chris Chiasson <chris.chiasson at gmail.com>
- Date: Sat, 19 Apr 2008 23:53:14 -0400 (EDT)
- References: <fu9fss$cdu$1@smc.vnet.net> <fuc828$a56$1@smc.vnet.net>
On Apr 19, 2:47 am, "David Park" <djmp... at comcast.net> wrote: > 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 > djmp... at comcast.nethttp://home.comcast.net/~djmpark/ > > "Will Robertson" <wsp... 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 The new .m file editor is useful when building large projects combining Mathematica with revision control software (like subversion). Instead of a .m and a .nb to keep track of, there is only the .m. Since the .m is in plaintext (let's not go into how a .nb is also "plaintext"), it is easier to run commands like unix's diff on the code tree to see what changed. In order for this to work right, the .m file must be indented in a way that promotes readability... In the past, using .m files had the disadvantage of non-interactivity (unless one was using emacs, et al.), but much of that is mitigated with the new .m file editor. Not that I am really an active Mathematica user anymore...