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

[David McMillan]

James Burbidge wrote:

> There are, or used to be, several LaTeX-based tools for doing
> commented-code processing, which supported (obviously) anything you
> could put into the LaTeX format (including, e.g. generated eps
> graphics to be included in the output via outside references).
> However, these tools usually rely on "standard" comment formats used
> in C/C++/Java or Shell/Perl/Awk files to decide when to stop
> pretty-printing and start treating the text as LaTeX-formatted input.
> (There are also some literate progtramming tools for this sort of
> thing, but they're overkill for what you want to do and in any case
> require restructuring your code).  If the languages you're using use
> these types of comment conventions, the tools might work.  If this
> sounds useful, I could hunt around my old files and see what I have
> information on (however, anything I have _detailed_ information on is
> likely to be very much C/C++ oriented).

	Thanks, James.  I really appreciate the effort, and the offer.
	Unfortunately, the comment formats are all over the place.  KUKAs use 
semicolons, ABBs use exclamation points, Kawasakis use semicolons or 
periods depending on which part of the file you're in, Nachis use 
REM-with-quotes _or_ semicolons, depending on whether you're going into 
or out of the language converter (don't ask).  Fanucs... I actually 
don't recall offhand.
	Honestly, what I _really_ need is a tool (or kit thereof) that will 
help me turn source code into bright, friendly, Teletubby-level coloring 
books -- and I'm not being nearly as hyperbolic as you probably think.
	In these environments, running code in your average industrial robot is 
a lot like running code in a debugger, except that in the robot, the 
debugger is the natural state to run code in -- there's no compilation.
  So, as the robot runs, its control panel (the "teach pendant" in
general parlance) displays the source code step by step following
command execution.  When a failure occurs (due most often to sensor or
mechanical failure), diagnosing the problem and recovering from it
usually entails looking at the current step and working backwards from
there.  For simple rote programs, this is usually pretty simple (but our
customers demand a level of idiot-proofing that would lead one to
suspect they are employing grade schoolers, regardless), but
unfortunately I'm the person generally selected by my employer to handle
"exotic" applications (in this context, anything that runs more than one
subroutine deep counts as "exotic").
	My root problem is, after I get these systems up and running, they are 
operated and maintained by... well, imagine having a Windows computer 
maintained by an old-school car mechanic.  Then multiply by several 
*hundred* Windows computers in the same building.  *Then* throw in an 
even dozen Linux/Unix machines that are to do jobs that the Windows 
machines just can't hack.
	Now imagine writing a manual for these operators that explains things 
clearly enough for them to understand how to recover from common
potential failures, *without* trying the "close all programs and reboot"
method, because doing that will likely destroy ~$50k worth of equipment
in short order....
	And people wonder why I seem high-strung these days.