Andy Lewis wrote: > Bertrand Delacretaz wrote: > >Andy Lewis wrote: > >>. . .my intent with the man pages was user-level technical > >>documentation... > > > > same here, but hearing other comments makes me think that we > > might need TWO reference pages > > (manpages) for some components, one for users (who use the > > components) and one for developers > > (who might want to modify or inherit them). > > intersting...hm....what would go in the developer man page that > wouldn't fit in the javadocs? > > > > > We might want to leave this open by first creating manpages named > > > > xxx-user-manpage.xml > > > > and leave > > > > xxx-dev-manpage.xml > > > > available for future use. > > > > -Bertrand
I do not agree with this. I think that we need certain information required as javadoc tags in the code before we can create *any* manpages, be they *-user or *-dev pages. The table that is at the top of example Wiki:FileGeneratorManPage would be extracted directly from the javadoc tags, and would be needed for both sets of manpages. It is important to get that information and also the developer manpages done first, because they will form the basis for the user manpages. The former should be done by cocoon-dev and the latter can then be subsequently done by anyone. Another important reason is that we need to get some system in place soon to ensure that developers do not continue to write code that has insufficient accompanying documentation. --David
