[Simh] fprint_sym and parse_sym limitation

[Kevin Handy]

Doxygen has some limitations, it is more of a reference than a tutorial for
example, but it does have a lot of useful features when done properly.
- It generates LaTeX, HTML, and RTF from the sources, and other formats are
available from these (like ps and pdf).
- If you copy one source file as the basis for annother device for ecample,
the documentation is already mostly done for you.
- The documentation keeps up with the source better than seperate files.
Software developers never seem to update the documentation unless it's
staring them in the face as they make their changes.
- References to structures in a parameter list are automatically cross
linked.

As documentation for how to write code, it isn't that great because it's
mostly just a list of available functions, but does give you several views
of what edists. including links to the source code.

I don't think it works as the sole source of documentation, but it does
provide a lot of useful information even if you don't have any comments
coded in.

(I just tried playing with it) As a first try at using it. just install
doxygen (and graphviz for extra credit), type 'doxygen -g' ay the top level
simh directory, edit the generated 'Doxygen' configuration file, and list
all of the subdirectories under the 'INPUT' option (along with a '.' for
the top level directory), and then run 'doxygen'. Point your browser to
'./html/index.html' and brouse around. With the Graphviz, you also get
relationship diagrams for structures.

On Mon, Sep 14, 2015 at 1:20 PM, Christian Gauger-Cosgrove <
captainkirk359 at gmail.com> wrote:

> On 14 September 2015 at 14:34, Mark Pizzolato - Info Comm
> <Mark at infocomm.com> wrote:
> > That said, I've got a back-burner project which will migrate most of the
> simulator specific documentation to a more generic format which can
> leverage various display/output formats.  When that finally sees the light
> of day, we'll look at the remaining documents.
> >
> I know the discussion mentioned doxygen; but I'd been feeling it might
> be "nice" to transfer the SIMH documentation to LaTeX. Especially
> since it works very nicely with a version control system. And the
> documentation is kept separate from the source code.
>
> Then again, doxygen is a de facto standard in documenting software
> with annotated source code, but would require a large scale project to
> add all that information into the sources.
>
> Regards,
> Christian
> --
> Christian M. Gauger-Cosgrove
> STCKON08DS0
> Contact information available upon request.
> _______________________________________________
> Simh mailing list
> Simh at trailing-edge.com
> http://mailman.trailing-edge.com/mailman/listinfo/simh
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.trailing-edge.com/pipermail/simh/attachments/20150914/cbe3f9e2/attachment.html>