Feature Requests item #1664436, was opened at 2007-02-20 10:46 Message generated for change (Comment added) made by molvisions You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=379136&aid=1664436&group_id=23629
Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: None Group: None Status: Open Priority: 5 Private: No Submitted By: molvisions (molvisions) Assigned to: Nobody/Anonymous (nobody) Summary: jmoldoc Initial Comment: hi, the Jmol scripting language has grown quite complex since it reached and surpassed the RasMol/Chime set. I would like to suggest that some form of built-in documentation be considered. the most useful format for inline documentation, in my opinion, would follow the same lines as perldoc and javadoc; in other words, syntax would be available from within the Jmol scripting window as: jmoldoc select jmoldoc faq etc. any thoughts? tim ---------------------------------------------------------------------- >Comment By: molvisions (molvisions) Date: 2007-02-23 16:36 Message: Logged In: YES user_id=920824 Originator: YES Drilling down to the doc entry for a specific command is exactly the content that should be presented. what may be confusing is that I am after a different _presentation_ of that content; namely, one that can be accessed with a few keystrokes from a Jmol script editor (console, or the script window of the app, or even perhaps javascript). I assumed my perldoc example would be immediately clear, but obviously I am not communicating my ideas well. ---------------------------------------------------------------------- Comment By: Bob Hanson (hansonr) Date: 2007-02-23 16:02 Message: Logged In: YES user_id=1082841 Originator: NO It does sound like this is what Tim is after. I don't do the update step for integrating the DOCBOOK output of the web page into the application help. I'm sure that's out of date. Nico (I think) was doing that. Basically we have seen the application as a bit of an orphan without much attention. I see it as a developer tool for testing scripts, writing files, etc., more than an actually field-useful program. But an inline option such as this would make it that much more useful to developers. So I'm all for doing this if the DocBook data can be used directly. Bob ---------------------------------------------------------------------- Comment By: Rene Kanters (rkanters) Date: 2007-02-23 15:52 Message: Logged In: YES user_id=905185 Originator: NO Hi Bob, I think your last paragraph where you propose for the application to support a help command to drill into that DocBook specifically for Jmol script commands, e.g., help command xxxxxx, giving you THAT command's help section is a good suggestion. Am I misunderstanding how the documentation is maintained when I thought that the documentation you have online, e.g., at http://www.stolaf.edu/academics/chemapps/jmol/docs/?ver=11.0#isosurface, should already be part of the help pages in the application? René ---------------------------------------------------------------------- Comment By: Bob Hanson (hansonr) Date: 2007-02-23 15:37 Message: Logged In: YES user_id=1082841 Originator: NO OK, I suggest you start with the isosurface command. ;) So this would be an app-only interface. That sounds good to me. ---------------------------------------------------------------------- Comment By: molvisions (molvisions) Date: 2007-02-23 15:13 Message: Logged In: YES user_id=920824 Originator: YES hi Bob, thanks for posting your explanation. I will take a look at your files and try to come up with a proposal and proof of concept. as an example, if you type 'perldoc -f shift' at a command prompt (I changed split to shift simply because it is a shorter doc), you get this explanation of how to use Perl's shift command: shift ARRAY shift Shifts the first value of the array off and returns it, short- ening the array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the @_ array within the lexical scope of subroutines and formats, and the @ARGV array at file scopes or within the lexical scopes established by the "eval ''", "BEGIN {}", "INIT {}", "CHECK {}", and "END {}" constructs. See also "unshift", "push", and "pop". "shift" and "unshift" do the same thing to the left end of an array that "pop" and "push" do to the right end. python has a similar feature. I use this when I know what I want to do, but can't recall command syntax or details of its use. this describes almost all situations that arise when I'm writing code (and apparently, given the widespread popularity of inline docs, this is true for other folks as well). to me, this minimal interface is very useful: it is fast, concise, exactly on point, and accessible from within my development environment - which means that it does not disrupt my workflow. of course, if I don't know what I want to do, I go visit the help pages, which is why in no way do I advocate demolishing the Jmol help as it exists. I merely want to provide an (additional) interface that is more accessible to script developers. this may not concern the wider user base of Jmol. perhaps only a few of us need to write scripts that cut across all, or nearly all of Jmol's capabilities. if I only wrote scripts dealing with crystallographic symmetry, for example, I'd probably know all the relevant commands cold, and this discussion would seem trite. so I apologize if this request, and my persistence, seems off-base. but I feel this issue is important enough to relinquish my usual, comfortable spot on the sidelines and make a pitch for it. thanks for listening, tim ---------------------------------------------------------------------- Comment By: Bob Hanson (hansonr) Date: 2007-02-23 13:24 Message: Logged In: YES user_id=1082841 Originator: NO OK, so I'm glad the content seems appropriate to you. To my knowledge the content is complete. Certiainly for 10.2 and 11.0 it is complete; as I develop new commands and options in 11.1.x there can be a delay. For example, I just entered information relating to invertSelected and rotateSelected yesterday. As I said in the previous posting, I do hope you are not suggesting dumping the Excel basis. For me, this has been a dream--just very easy entry of new information. When we went to 11.0 and then 11.1, it was just a matter of identifying the version in a column on the spreadsheet, and out comes the options to view the help for whatever version one is running. If there is any replacement, then the thing to do is use the DOCBOOK output of the Excel/JavaScript "factory" as the basis, not the Excel. We would just abandon the Excel, I think. I'm just worried that we will take something that is trivial to manage and make it harder or at least much less flexible. And the last thing I want is two parallel running systems. The process goes like this: I have an Excel document that has a series of worksheets -- one for definitions, one for commands, and one for examples. You can find a copy of it at http://www.stolaf.edu/academics/chemapps/jmol/docs/scripts.xls. These pages each have a Column A that is clipped out manually (or using a macro, but I haven't found that necessary since for me clipping a column and putting it into a file takes absolutely less than 2 seconds from an open DOS command prompt). So we have three JavaScript files: defs.js, cmds.js, and exam.js. There is also a file code.js that handles all the processing. That's pretty much it. If you want HTML, you just load the page; if you want XML, you just add ?xml to the link; if you want docbook, you just add ?docbook. These versions are all produced by the JavaScript in code.js. The maintenance is typically just (1) edit the Excel and (2) save a new cmds.js. I have an FTP scripter that sends that to the website automatically along with any other updated pages (new.htm, especially), and the job is done. I'm trying to imagine what you are really interested in, and I can't see what you are seeing. Are you imagining, for example, a ... Sorry, I just don't see it. I thought perhaps I would say that you might be imagining that you type help <command name> and you get something just for that command, in ASCII, HTML, XML, I'm not sure. Would it be the same content as you see at the interactive documentation site, or would it be more terse, more "bare bones"? I know you know this scripting language better than anyone, so I'm not sure what you are after. Certainly I go to the help page all the time; maybe because I wrote it I can always find what I'm looking for quickly. That could be. Personally, I learn by example, so that's why I've tried to make the documentation interactive and why the new.htm page is designed to show you exactly what commands do what. But maybe there's a way of producing something like what you want. One thing I'm wondering if you have not realized is there: Do you ever run the Jmol app itself? I find this THE way for me to work on developing complex scripts. And there you have a Help menu that I THINK pretty much should do the job, since it is, in fact, from the DocBook code. Could a satisfactory solution be to just tie an APPLICATION (not applet, since you suggest you don't want to have to be online) help command to drill into that DocBook specifically for Jmol script commands? Perhaps something like help command xxxxxx which doesn't do a search, just gives you THAT command's help section? Bob ---------------------------------------------------------------------- Comment By: molvisions (molvisions) Date: 2007-02-23 11:27 Message: Logged In: YES user_id=920824 Originator: YES hi Bob, thanks for doing this. I don't have an issue with the content of the help, unless there are wide swaths of undocumented commands (which I doubt). so for me, at least, it is solely an issue of access. if someone can give me an idea how the current help doc are generated, I will be happy to look into building a different access point to it. one drawback is that I don't use Excel, though I do use OpenOffice. thanks, tim ---------------------------------------------------------------------- Comment By: Bob Hanson (hansonr) Date: 2007-02-23 00:44 Message: Logged In: YES user_id=1082841 Originator: NO The help documentation is now organized by command, so that's pretty much along the lines of what you are talking about, Tim. The format used to deliver it is secondary, since it's a database. What you see when you go to the help page is just one particular rendition of the explanation of the commands. We also have it in XML and DOCBOOK format, for example, and this could be rendered any way one wants. That said, I would like to suggest that we not move from the current Excel basis. This is a very flexible basis that is well organized and complete. The maintenance of that is a task that is easily manageable, and I am willing to continue doing that as long as I am developing. It works very well for me -- add new features/update the documentation and "new.htm" pages. What's nice about it is that the form (delivery) is completely dissociated from the content (the Excel data). One idea might be to take the XML or DOCBOOK output and manipulate it along the lines Tim is interested in as a "proof of concept". I have no idea what's involved in this, but presumably the DOCBOOK format is what would do the trick. I just ran a verification on the XML at http://www.w3.org/2001/03/webdata/xsv, and it passed after some editing of the Excel database. I don't know about the DOCBOOK. You can take a look for yourself at http://www.stolaf.edu/academics/chemapps/jmol/docs/index.htm?xml or http://www.stolaf.edu/academics/chemapps/jmol/docs/index.htm?docbook and see what you think. If the issue is presentation, this will work. If the issue is content, that's another story altogether. What we need is a couple of volunteers, because I know I don't have any time for this or a clue how to go about it. ---------------------------------------------------------------------- Comment By: molvisions (molvisions) Date: 2007-02-22 20:23 Message: Logged In: YES user_id=920824 Originator: YES what I would like to see: for a good example, open a command prompt and type 'perldoc -f split'. speaking as a script developer, the complexity of Jmol's scripting language warrants a closer look at how documentation is delivered to developers. it may not *be* a true computer language, but that certainly shouldn't argue against providing doc in a format friendly to script development, and to take lessons from the excellent models that exist in true languages. I don't want to weed through the entire help document when all I want to know the syntax of a command or the structure of a control element. yes, I know I can find what I want - but isn't it all about access? ---------------------------------------------------------------------- Comment By: Bob Hanson (hansonr) Date: 2007-02-22 19:13 Message: Logged In: YES user_id=1082841 Originator: NO For now you have what you have -- a complete, searchable online listing of every command's syntax, including all capabilities and restrictions. This is the most I'm prepared to provide, since I don't know what else would be better. Perhaps someone could volunteer to look into this further. Jmol is scripting language, not a computer language such as Perl or Python, so it is not necessarily apropo to compare these in this way. Perhaps such an set of documentation to the API would be appropriate, but that is not what you are referring to. The Javadoc would be of no use in this case, because you are not referring to specific Java commands but rather Jmol script commands. Tim, can you give me a better "for instance"? The return from "select" is large because that is such a common word. One of the items, though, is the select command. As for online or off, why not just download the documentation (File...save... Web Page Complete)? You may lose the pretty icons, but everything else will be there. I guess I'm not understanding what you really want to see. Bob ---------------------------------------------------------------------- Comment By: molvisions (molvisions) Date: 2007-02-22 18:00 Message: Logged In: YES user_id=920824 Originator: YES I have looked at the help command in the Jmol applet, but this is different from what I am requesting. On my machine, 'help' opens the scripting Web site in a new browser window; it doesn't seem to do much more. for example, I typed help select anticipating that it would bring me to the select command in the interactive help, but it didn't. It looks like it does highlight the term 'select' where it appears on the page, but I don't find this generally useful for development purposes. also, it requires an Internet connection. the addition of inline developer documentation in the spirit of many other languages (notably Perl, Java, and Python from my experience) would help to make Jmol much more useful - especially as the Jmol scripting language becomes more complex and powerful. Perhaps a simple use of the existing javadoc would work here? a new command like 'jmoldoc' could be a wrapper for javadoc (this is how python's 'help' command works, if I'm not mistaken). thanks, tim ---------------------------------------------------------------------- Comment By: molvisions (molvisions) Date: 2007-02-20 22:13 Message: Logged In: YES user_id=920824 Originator: YES hi Bob, I did not know about the help command in Jmol. I'll check it out. just my two cents: I disagree with your characterization of inline docs like perldoc and javadoc. I find them to be very helpful during development because they are cleaner and more focused. of course, the entries have to be well-written for this to be true! but certainly perldoc in particular is a great help for command syntax, options, basic procedure, and the like. (for a more comprehensive or tutorial view, I do go searching.) best, tim ---------------------------------------------------------------------- Comment By: Bob Hanson (hansonr) Date: 2007-02-20 13:38 Message: Logged In: YES user_id=1082841 Originator: NO perhaps. We have the help command, which you may not be aware of help select help chime etc. That works specifically for the applet and works by opening a new window to the help documentation with a search for the designated term. In *MY* opinion, this is far better than in-line documentation, because it gets you the full context of the help documentation, with examples and all, rather than just a statement or two that might or might not answer your question, and there is no overhead at all in terms of applet download time. Is there an argument that inline would be better? Bob ---------------------------------------------------------------------- You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=379136&aid=1664436&group_id=23629 ------------------------------------------------------------------------- Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV _______________________________________________ Jmol-developers mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/jmol-developers
