Re: continuing documentation

[OKUJI Yoshinori]

From: Gordon Matzigkeit <gord@fig.org>
Subject: Re: continuing documentation
Date: 21 Jun 2001 16:24:02 -0600

> When a `@deftypefun ...' declaration is found, your tool is to compare
> the rendered text and prototypes.  If there are differences, it should
> ask for human intervention to merge the changes.

Is it necessary to compare descriptions as well as function
prototypes? I think this would be very hard or impossible with no
human assistance (e.g. tagging comments with version numbers).

> If the function doesn't exist in the list of scanned header files,
> your tool should emit a warning, and offer to delete the
> documentation.  Likewise, if you find a declaration in one of the
> headers that is not documented, there should be a warning, and offer
> to insert the declaration where the user wants it.

That should be much easier than generating differences between a C
comment and a Texinfo text.

> With these requirements, my thoughts were to write something in Emacs
> Lisp, because that would give a rich environment for all the manual
> editing that would still need to be done.

Your idea is interesting, but in my experience, Emacs Lisp is poor at
syntax analysis of text, so I think it would be more feasible to
generate a log file by another language (Ruby, Perl or something) and
edit Texinfo files separately. I may be wrong. First of all, I must
remind myself of the detail of Emacs Lisp. ;)

Ok, then can I presume these:

* C header files (and other source files) are masters, and Texinfo
  documentation is a slave.
* It is not necessary to dive into the contents of descriptions.
* If there is any difference between a prototype in C and that in
  Texinfo, prompt to update the Texinfo text.
* If there is any prototype not found in Texinfo, prompt to write a
  corresponding text in Texinfo (with an auto-generated template?).
* If there is any prototype not found in Texinfo, prompt to remove it
  from the Texinfo file.
* Which header file should be scanned is given by human (as a part of
  a delimiter, a command-line option, or a file name, like
  "libports/ports.h" corresponds to "libports-ports.texi"?).

Okuji