Allow docs in OUTPUT directory to be linked (not copied) from source directory

[mgalloy]

Currently in IDLdoc, the OUTPUT keyword allows a user to put the documentation for IDL source code in a separate directory; however, a copy of each '''.pro''' file is also placed in the output directory. I'm OK with this as a default, but it would be nice to have the option of linking the HTML files in the output directory back to the '''.pro''' files in the source directory. Maybe a NO_COPY keyword?

[mgalloy]

Copying the .pro files causes a tricky problem that I have encountered. If you create your documentation in a directory that is in your !path (probably because the directory in your !path is added with a +), then IDL might pickup the "documentation .pro file" instead of the real one. (For example, I can't just put ~/projects/idldoc into my !path since then ~/projects/idldoc/api-docs would be in my !path too.) There is actually a warning about this on the help page.

There are two problems I see with making a link to the .pro file:

• FILE_LINK only works on UNIX. Is there some Windows equivalent?
• Making links would break in the relatively common case of generating documentation on a local machine and then copying to a webserver. Having a keyword to change this would fix this issue. Should copying or linking be the default?

[mgalloy]

It was brought up that the <A HREF=""> should point to the location inside ROOT instead of creating a symbolic link inside the OUTPUT. The question then is what kind of URL to use for that HREF?

• relative link (breaks across differing Windows drives)
• absolute link (breaks if docs/source are moved, especially in the case of generating documentation locally and copying to a webserver)

Maybe the correct answer is to use a relative link and generate an error if LINK_SOURCE is used with a ROOT and OUTPUT that are on differing Windows drives.

[mgalloy]

Added a SOURCE_LINK keyword to IDLDOC in r450. This keyword can be set to:

• 0 (copies source code, the default)
• 1 (creates relative links)
• 2 (creates absolute links)