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