From: Gordon Matzigkeit <[EMAIL PROTECTED]>
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
_______________________________________________
Bug-hurd mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/bug-hurd
