[LMB] [OT] [AKICOTL] Documenting source code

[David McMillan]

	I need some expert (or at least experienced) advice, and since I know 
the list contains a number of people across a broad range of fields who 
sometimes have to write technical documents, this seems the most likely 
forum (among the few I am an active member of) to produce the kind of 
results I'm looking for.

	I'm an application developer/software engineer working in industrial 
automation.  One of the odd things about industrial robots is that the 
people operating them are normally running the source code "raw" -- the 
user interface *is* the IDE.  In addition to this, the people operating 
these machines are often not, um... let's just say that the 
documentation needs to be colorful, detailed, and straightforward.

	Here's my problem:  I can produce a raw text file of the source code 
the robot runs on, and format it all nice and pretty, and add comments. 
  But what I'm lacking is a good tool for taking that raw text and 
adding descriptors to it: things like explanatory bubbles linked to 
particular lines or blocks of source code, arrows tracing out branches 
and jumps, color-coding sections of related code, etc.
	Most recently, I've used Scribus for this, but while Scribus appears to 
be an excellent (and free!) desktop-publishing platform, I found it 
cumbersome for what I was trying to accomplish.  MS Word... well, the 
less said there, the better.  OpenOffice failed me too -- it's just more 
geared for composition than annotation of existing text.  Doxygen is 
intended for programmers rather than inexperienced operators, and works 
on standard languages like C++, Java, etc -- industrial robots, sadly, 
generally use brand-specific proprietary languages that are almost but 
not quite like C, Pascal, BASIC, or Fortran (I can now claim working 
competency in 20+ separate programming languages, but full mastery of 
none of them.  Sigh).
	Possibly the biggest hurdle I can't find and answer to is a means of 
importing an updated version of the source code into the documentation 
editor without losing all my previous work.  In Scribus, inserting two 
lines of code would require manually moving every bubble, arrow, 
annotation and sidebar note from that location to the very end of the 
file.
	I can't be the first person to have this need.  I'm just hoping that 
someone has used, seen, or heard of a tool that addresses this 
particular problem.