This is the mail archive of the guile@cygnus.com mailing list for the guile project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
If you showed me a reference manual, and I looked it over and said it looked like a good manual, and then you showed me that the manual was generated automatically by extracting bits of text from source code, then I wouldn't suddenly change my mind and call it a bad manual. In other words, if your doc extraction system tends to all the usual details required for writing a good manual, then I'm sure you'll get a good manual. And I believe it is mechanically possible to do this. My concern is that it will be unmaintainable, realistically, given the human nature of maintainers. If the layout of the code has any influence on the layout of the manual, then you will sometimes find places where good coding style conflicts with good manual style. Certainly one can find compromises, but remember that these compromises are only necessary at all because you're trying to extract a manual from code. If you just simply move the text out of the code into the manual, then these tensions never exist in the first place. Or, because the form of the manual is obscured by being scattered throughout the source files, you will make changes that hurt the manual without realizing it at all. Did you ever read over the Java class documentation in the early days of Java? They had it on the web. It was terrible. You couldn't figure anything out. That's one example I have of a manual extracted from docstrings. I also know that Stallman was quite opposed to the idea, and over the years I decided he was probably right. It's just a gut feeling. If you don't agree, you don't agree, and you should go with your own gut feeling. If the goal is to provide on-line documentation associated with SCWM procedures, I would be much happier with a system that extracted in the reverse direction: from a manual to a database accessible by the code. For example, go ahead and write texinfo or DocBook describing the SCWM functions, then have a program grunge through the @deffn's (or the DocBook equivalent) and build a database, then have SCWM retrieve that text upon user request. Or, if you think it is valuable to have the text mingled with the source code, add a notation to your manual format that says "extract the docstring for this function from the source, and insert it here." That way, the layout of the source has no influence on the layout of the manual. Do people feel that, if the documentation is a separate file, programmers will be discouraged from writing docs, whereas, if the documentation were mingled with the source, then programmers would naturally write docstrings as they go along?