Hi all,
Carlos Nieves Ónega writes:
> [...]
> - Noweb: I don't know anyone who has benefit of using it. If we want
> to change to plain C files, we should convert all noweb comments into
> doxygen (or whatever) comments. I think doxygen will improve code
> documentation too. Is anyone still using noweb? who wants to drop noweb?
> Any volunteers to do the work?
Is noweb really the problem? How can doxygen (or whatever) help us
document code better than with noweb? I am afraid it is not a
tool problem: it's rather that the code will not write comment or
documentation alone. It may not be the most exciting part of the job
but nobody else will do it for us.
Have you ever look at the examples provided with noweb or noweb's
source documentation itself? It is really a pleasant to read (for a
source code of course).
One possible enhancement of the way we use noweb would be to extract
both .c files and .h files from the .nw.
OK so what is the problem with noweb?
The overhead of a separate source file has been addressed with the
guile version of notangle (even if it is far from perfect and actually
need some work to support escape sequences).
Though I do agree that we made a mistake with our (maybe mine I do not
remember) choice of Texinfo as the documentation language. But note
that changing this language to another is very different from changing
from noweb to another documentation system.
People are modifying C source files instead of noweb files? Well every
project has its rules. Our first one is that if you want to keep you
changes safe, you edit the .nw file. It is clearly indicated in every
file!
So you still want to change the documentation system?
>From the first answers to your message, it looks like there is 'very
few' noweb supporters. If you want to switch to doxygen or whatever,
it is OK with me, I think I will survive :) and I will not 'veto
that change'.
However, keep in mind a few things before doing so:
- of course we do not want to lose existing documentation.
- it is unthinkable to lose the change history when moving
from a .nw file to a .c: after the transition we still want to be
able to browse changes in a source file to find who modified
what, how and why even for changes of the noweb era. We
experienced that already when moving to noweb, we do not want it
to happen again. So be ready to play with CVS :)
- while selecting the next documentation system remember that we are
working on C source files with always more GObject stuff
(properties, signal...). I am not sure doxygen knows how to handle
that (gtk-doc does of course).
- same problem but this time with scheme code.
So my position is that there is too many areas where gaf needs effort
that it would be quite a waste of time to switch to yet another
documentation system.
Noweb is not perfect but we can still improve the way we use it. But
the most important point is that source code documentation needs
commitment from the developers more than a new documentation system.
Oh I almost forgot: naturally I volunteer to update gnetlist source
code to noweb :)
Now on your other points:
> [...]
> - Unsaved schematics warning when exiting: I always have to read the
> text to know what button I should click on. I think it can be improved
> with Discard/Save/Cancel buttons, and a text explaining the
> situation.
I like this idea.
> [...]
> - Autosaving: having gschem automatically save every unsaved schematic
> every few minutes (user-defined). gschem can use another filename, like
> #real_name.sch#, like emacs, or real_name.sch~.... These files should be
> deleted when saving the page.
It would be quite useful indeed.
Regards,
Patrick
