Subject: What format should I use to document the internal of a C program?

From: Shlomi Fish <[email-masked]>
Date: Sun, 11 Feb 2001 20:23:23 +0200 (IST)

Freecell Solver again. Chen told me she could not quite understand what I
was trying to achieve in every place in the program. I'm planning to add
comments, but I'm not sure they would be enough.

Thus, I want to create a document that will describe the Freecell Solver
architecture. What I would like to have:

1. Sections, sub-sections, sub-sub-section, etc. to unlimited depth.
2. Ability to render into text and in less priority HTML and in less
priority man pages and in less priority LaTeX.
3. Portability: that I would be able to edit it on Windows as well as
UNIX.

Now, DocBook XML/SGML and texinfo seems like a bit of an overkill for
this, and I'm not sure I'll be able to install them everywhere I can work
on. perlpod seems nice but I don't know if it supports #1, and it may be
too much perl-oriented, while I want to document C code.

Then there's C-WEB and similar tools of Literate Programming. But I'm not
too anxious to convert the entire project into a literate programming one,
because I don't feel it is needed. Besides, can they render into anything
besides TeX? I don't like Postscript files very much, and there are more
people out there who can edit HTML than those who can edit LaTeX.

I have a love-hate (mostly hate) relationship with MS-Word, and I'm
familiar with its sectioning scheme. But I don't have StarOffice
or AbiWord installed on {vipe,t2,lion}.technion.ac.il which are my UNIX
servers on the Technion, and my quota cannot afford it.

I can hack something in perl, but I was hoping there was some other
solution. Do I have too many demands or is this the dawning of
Shlomif::Proto::Text - yet another itch for a scratch written in perl?
(to be Freshmeated and BerliOSed before the coming of the Messiah)

If you can recommend anything, please do.

Regards,

	Shlomi Fish

----------------------------------------------------------------------
Shlomi Fish        [email-masked] 
Home Page:         http://t2.technion.ac.il/~shlomif/
Home E-mail:       [email-masked]

The prefix "God Said" has the extraordinary logical property of 
converting any statement that follows it into a true one.

---

From: Adi Stav <[email-masked]>
Date: Sun, 11 Feb 2001 21:10:24 +0200

On Sun, Feb 11, 2001 at 08:23:23PM +0200, Shlomi Fish wrote:
> this, 
...snip...

I have never used DocBook, but LinuxDox (which is a subset and a
predecessor) is anything but an overkill -- it is a very
straightforward, trivial and minimalistic document markup. You can
learn all of it in less than five minutes by looking at an example and
it translates into practically anything.

My main problem with it is that it doesn't give you enough control
over the "rendering" (e.g., you cannot have a auto-generated table of
contents if you choose to render it into a single part HTML document),
and that it doesn't give you enough sophisticated features (e.g., it
has a (undocumented) table feature, but it only works with HTML and
not postscript). LinuxDox is a subset of DocBook so I suppose one
could always just switch.

---

From: Shlomi Fish <[email-masked]>
Date: Mon, 12 Feb 2001 09:52:40 +0200 (IST)

> it translates into practically anything.

What I meant by overkill is that the program itself will occupy too much
space on the hard-disk, will take some time to compile, etc.

Is it indeed an overkill from that sense?
 
Regards,

	Shlomi Fish

---

From: Adi Stav <[email-masked]>
Date: Mon, 12 Feb 2001 11:11:29 +0200

> Is it indeed an overkill from that sense?

Heh, I don't know. I guess it depends on what your limitations are.

The executables themselves don't take much space, less than 100kb, but
you will also need various data files. A wild guess will be around
one, maybe two megabytes tops, but I suppose you could trim that
considerably by only installing the templates you need and not all the
spiffy HTML icons. It does need perl though, which isn't small. So to
sum it up: I don't know :)

As for speed, generating HTML was fast enough on my 500Mhz 128MB,
somewhere between unnoticeable to half a second. Generating postscript
through LaTeX was a whole different story, but that's a well known
pain.

---

From: Oleg Goldshmidt <[email-masked]>
Date: 15 Feb 2001 11:00:56 +0200

Hi Shlomi,

It is not clear to me what you are trying to achieve. If you
are trying to create a usage documentation (you mentioned man)
then you might consider texinfo. With the tools to convert texinfo
into LaTeX and HTML you'll cover a lot of ground.

If that seems to be overkill, then a README file might do...

If you need documentation for your code (data structures, functions,
etc), then I would suggest considering literal programming approach.
One simple tool is cxref - I've used it, though not extensively. it's
a bit of markup in your normal C comments, enabling you to generate
useful LaTeX/HTML documentation for the structural elemnts of your 
program.

A big advantage compared to documentation that is detached from the
code itself, since having all the documentation inside your code makes
it less likely that they'll go out of sync.

A disadvantage is a volume of comments inside your code, which may
annoy. However, it seems that your original motivation stems from the
observation that there are not enough comments in the code, which
makes the code unclear.

> Besides, can they render into anything besides TeX? I don't like
> Postscript files very much, and there are more people out there who
> can edit HTML than those who can edit LaTeX.

HTML, as mentioned earlier. And from what I understood from your
posting I don't see the need for anyone other than maintainers to
_edit_ the documentation.

-- 
Oleg Goldshmidt | [email-masked] 
"... We work by wit, and not by witchcraft;
 And wit depends on dilatory time." [Shakespeare]

---

From: Shlomi Fish <[email-masked]>
Date: Thu, 15 Feb 2001 21:59:49 +0200 (IST)

> If that seems to be overkill, then a README file might do...

I already have usage documentation as part of the standard distribution.
It is distributed as a couple of text files, and is well maintained.
That's not the problem.
 
> observation that there are not enough comments in the code, which

I am hoping to avoid Literate programming because it seems to me that I
need one central document that will cover the architecture of the
program. Comments are enough in order to cover the less trivial parts of
the code.

---

From: Oleg Goldshmidt <[email-masked]>
Date: 18 Feb 2001 10:02:47 +0200

> program. Comments are enough in order to cover the less trivial parts of

Something like cxref will generate a single document describing the
architecture of the program from your comments.

No, I am not trying to push it ;-)