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

[James Burbidge]

On 28/06/07, David McMillan <skyefire at skyefire.org> wrote:
>
>         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.
>

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).

James