[Jmol-developers] [ jmol-Feature Requests-1664436 ] jmoldoc

[SourceForge.net <no...@so...>]

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