Experimental Physics and
Industrial Control System

"J. Lewis Muir" <[email protected]> · Thu, 10 Nov 2016 07:38:47 -0600

On 11/09, Mark Rivers wrote:
> In areaDetector there are many cross-links to documentation within the different areaDetector repositories.  I have avoided putting URLs on those at all, and simply copy all of the HTML files to the same directory on our Web server, so the files will be found automatically.  For example:
> 
> ./areaDetector-2-5/documentation/html/simDetectorDoc.html:    This is an <a href="http://www.aps.anl.gov/epics/";>EPICS</a> <a href="areaDetector.html">
> 
> So the EPICS documentation link uses an http URL, but areaDetector.html is assumed to be a file in the same directory.  How would this be handled in a maintainable way if the documentation home move to github where simDetector.html and areaDetector.html reside in different repositories?

My preference would be to make the documentation for any module able to
stand on its own.  I would parameterize all external links so that they
can be defined in one place and be set appropriately for the particular
documentation deployment.  They can have default values, but it should
be easy to override the defaults.  Now, if a URL changes, it's easy to
change it in one place and regenerate the documentation.

A variant on this would be to allow a link to be undefined.  In this
case, no link would be generated, or, if that was a pain, an undefined
link could get generated as some kind of special null link that goes
nowhere or as a link to a default page indicating that the documentation
does not have a URL for the specified link.

This assumes the documentation is being generated.  If the documentation
is not being generated, and is instead being written in its final
form (e.g., HTML), then you'd have to do some kind of URL translation
to change any URLs to something other than their defaults.  That
shouldn't be too hard either: you could have a separate translation
file containing a mapping of any URLs that should be translated into
different URLs, and then you'd have a program capable of generating a
new final-form document from the original.

Regards,

Lewis

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System