| Re: user defined idl_catalog.xml [message #50248 is a reply to message #50247] |
Fri, 22 September 2006 20:07   |
Michael Galloy
Messages: 1114
Registered: April 2006
|
Senior Member |
|
|
JD Smith wrote:
> Interesting... any screenshots of an example? Don't you need an "ADP"
> file as well (the IDL_Assistant wants one).
Yes, IDLdoc will create the ADP file as well (using the ASSISTANT
keyword makes IDLdoc create the ADP file and use a simpler HTML that the
IDL Assistant can understand).
> Right now, IDLWAVE simply parses that XML file, and then makes a LISP
> equivalent in ~/.idlwave/idl_xml_rinfo.el for quicker re-load.
>
> If you provide source code along with your package, I have thought of
> creating a special tag in the documentation header, along the lines
> of:
>
> ;; %%%HTML-HELP%%% /path/to/html/help/file.html
>
> or some such, which can be loaded into the assistant if found. This
> doesn't help if you distribute binary flavors of your routines,
> however. The XML file itself is fairly straightforward to duplicate.
> Aside from special cases like aliases (for those space-saving
> documentation entries like OPENU/OPENR/OPENW), and system variables,
> etc., the format is pretty simple:
>
> <ROUTINE name="WV_APPLET" link="WV_APPLET.html">
> <SYNTAX name="WV_APPLET [, Input]" type="pro" />
> <ARGUMENT name="Input" link="WV_APPLET.html#wp1004581" />
> <KEYWORD name="ARRAY" link="WV_APPLET.html#wp1004583" />
> <KEYWORD name="GROUP_LEADER" link="WV_APPLET.html#wp1004841" />
> <KEYWORD name="NO_SPLASH" link="WV_APPLET.html#wp1004848" />
> <KEYWORD name="TOOLS" link="WV_APPLET.html#wp1004856" />
> <KEYWORD name="WAVELETS" link="WV_APPLET.html#wp1005269" />
> </ROUTINE>
>
> i.e., name the routine, give the link (here assumed to be beneath
> $IDL_PATH/help/online_help), give syntax with (important) type="pro"
> or type="func", list the arguments and their anchor links (if they
> have separate links in the file), and similarly with keywords.
>
> Class methods are slightly different -- see the xml file.
This XML file looks like it would be pretty easy for IDLdoc to create.
IDLdoc has all that information at hand when it is creating its output.
(It doesn't look all that different than the ADP file.)
> However, even if you create such a file, there is no simple way to
> append the data to the one shipped with IDL. IDLWAVE assumes the two
> sources of routine info are separate (library catalogs vs. system
> routine info).
>
> If IDLDOC simply generates a webpage without lots of internal links
> (for keywords, etc.), it would be simpler to just associate that html
> file somehow with the source code through some markup convention.
> Then rather than using "in source" help for library files, it could
> call the assistant for display. We'd also need a convention for where
> the IDLDOC html files are stored relative to the .pro file, e.g. just
> specify relative directories:
>
> ;; %%%HTML-HELP%%% ../help/myroutine.html
>
> Perhaps Michael could overload the IDLDOC syntax to include something
> like this, assuming that fits in logically. If it were trivial to
> unambiguously recognize a block of IDLDOC markup (which it doesn't
> appear to be as of IDLDOC 2.0), IDLWAVE (or, rather, idlwave_catalog,
> the perl script which created library catalog files) could look for a
> specific tag, like:
>
> ; @help_location ../help/myroutine.html
>
> save this path to the HTML file along with other information on the
> routine (for simplicity, likely the next routine it finds in the
> file), and then direct all help requests for that routine to the IDL
> Assistant (or other configured web browser).
>
> That would be more straightforward than going the full XML route.
> What that doesn't give you is the ability to jump right to the
> documentation of a given keyword. E.g. try:
>
> IDL> widget_control, b, SCR_XSIZE=[M-?]
>
> I don't know if IDLDOC would ever provide that granularity.
So if IDLdoc could write the XML file for the documentation and IDLWAVE
knew the location of that file, then documentation for the user routines
would have all the same functionality as the IDL documentation? That
would be cool. I've been using IDLWAVE a lot more recently (and thanks
for the M-? tip, I didn't know that) and that would be very useful. I'm
not so sure about the @help_location tag since the documentation is
meant to be independent of the code. (You would need a @help_location in
each file? Then moving the documentation could mean a lot of edits.)
Maybe IDLWAVE could keep a list of user library XML files? That would
also mean that the source code for the user library wouldn't be needed.
Now for the bad news... ITTVIS owns the source code for IDLdoc. I've
tried to get the source code released as an open source project (which I
also tried to do when I worked for RSI), but I don't know if that will
happen or how long it will take if it does.
Mike
--
www.michaelgalloy.com
|
|
|
|
comp.lang.idl-pvwave archive
Members
Search
Help
Login
Home
