Re: continuing documentation

[Gordon Matzigkeit]

>>>>> OKUJI Yoshinori writes:

 >> 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.

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

What is needed is to be able to see that there is a difference, choose
which of the two is the better one, and/or edit the results.

This is to make it easy to update the manual when somebody changes the
code, or to update the code comments when somebody improves the
manual.

Tagging comments is not acceptable to me, because I feel that we have
enough information already to make a comparison of text.  We know how
to collapse simple Texinfo into text, the word order is easy to
compare, and with some heuristics, we can generate a first guess at
the Texinfo when we only have the C comment.

 >> 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.

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

Yes, generating such differences is the heart of the project.  That's
what would allow nontechnical writers and nonwriter technicians to
work together to improve the documentation.

 >> 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.

 OY> Your idea is interesting, but in my experience, Emacs Lisp is
 OY> poor at syntax analysis of text, so I think it would be more
 OY> feasible to generate a log file by another language (Ruby, Perl
 OY> or something) and edit Texinfo files separately.

I'd like to avoid the complexity of multiple languages.  I won't go so
far as to make the project more complex by writing it in a language
that won't do the full job, though. ;)

 OY> I may be wrong. First of all, I must remind myself of the detail
 OY> of Emacs Lisp. ;)

I guess my dream is to leverage all of Emacs's text editing power (for
the human intervention), and also its builtin parsers for the various
languages.  Then, I'd like to contribute this work as a part of Emacs,
so that it has wide exposure to other GNU developers.

 OY> * C header files (and other source files) are masters, and
 OY> Texinfo documentation is a slave.

No, not always.  Sometimes the documenters will have improvements to
the wording of comments, and it is most convenient for them to make
changes by editing the documentation sequentially, rather than wading
through the code.

 OY> * It is not necessary to dive into the contents of descriptions.

Depending on what you mean.  It will be necessary to do some simple
Texinfo formatting to determine that a C comment is the rendered
version of the Texinfo, and inform the user if it isn't.

 OY> * If there is any difference between a prototype in C and that in
 OY> Texinfo, prompt to update the Texinfo text.

 OY> * If there is any prototype not found in Texinfo, prompt to write
 OY> a corresponding text in Texinfo (with an auto-generated
 OY> template?).

Yes and yes.  The template would be generated, as I said above, by a
heuristic that would know about GNU comment conventions (such as
capitalizing variable names).  It would not need to be intelligent at
first, but any enhancement would make documenters life easier.

 OY> * If there is any prototype not found in Texinfo, prompt to
 OY> remove it from the Texinfo file.

 OY> * Which header file should be scanned is given by human (as a
 OY> part of a delimiter, a command-line option, or a file name, like
 OY> "libports/ports.h" corresponds to "libports-ports.texi"?).

Yes and yes.

Oh, and some more requirements:

* The tool should also have a mode where it can go through the header
files and the source files to compare the comments.

* No change should be made without human assistance, and the person
  should have the opportunity to edit files after each change.  The
  tool is an assistant, not an oracle.

Thank you for your comments... I think we are a little further along
the way to having a set of requirements.

-- 
 Gordon Matzigkeit <gord@fig.org>  //\ I'm a FIG (http://fig.org/)
Committed to diversity and freedom \// Go Figure (http://fig.org/figure/)