Needed: Opinions on the CircleMUD Documentation Project

From: Jeremy Elson (
Date: 05/30/96

Hi there,

I'm starting work on the CircleMUD Documentation Project, which is really
just a fancy name for "I'm writing a lot of docs for Circle which people
have been asking for since the beginning of time."

The CDP is available at:

I used to use WordPerfect 5.1 to write all my docs and then covert to ASCII
to come up with building.doc, coding.doc, etc. (this was mainly done because
it's a pain to write in ASCII and have to reformat a paragraph when you add
3 words.)  Now, I'm converting everything over to SGML and using a tool which
automatically outputs ASCII, HTML, and LaTeX (Postscript) output from a single
set of source files (I'm using linuxdoc-sgml).

So, without any additional work, I'll be able to enclose ASCII docs with the
MUD distribution, publish docs on the Web, and even offer nicely formatted
Postscript output suitable for printing and putting in a binder.  Only the
HTML is currently available at the above URL.

Also, I'm using a tool called cxref to document the code itself.  It
provides a cross-referenced list of all global variables, all global
functions, etc., and gives you a list of every function that uses each
variable and function, etc.

So, here are my questions:

1- To coders: The cross-ref that I described above is available on the
   Web now, at the above URL.  Pplease take a look and tell me if you think
   it's useful.  It would take a lot of work, but I can add comments at the
   beginning of each function and for the global variables that will then be
   included in the cross-referenced list (i.e., there will be a description
   of what each function and variable does).  Is it worth it?

2- To builders:  There's also an HTML-ized version of building.doc there.
   Comments welcome.  Any other building docs you'd need to build an area?

3- To everyone: If you have any suggestions, or (even better) contributions
   to this area, please let me know!

CircleMUD has been severely deficient in the documentation department for
a very long time and I hope this project will finally fix that.  Contributions
are welcome!

In particular, yes, I'm going to finish coding.doc very soon. :)


This archive was generated by hypermail 2b30 : 12/18/00 PST