Huw, >>I'd like to ask, hoping not to appear rude, what Huw thinks about xdocs >>and whether he'll consider their content as important as java source. >> >> >i've been using Avalon stuff for two years, but i've only been making an >effort to contribute for the last couple of months, so sorry if it takes me >a little while to catch in. > No problem.
>not meaning to sound evasive, but i'm not sure what you mean exactly - >do you mean: > >1) do i consider documentation as important as the .java, so i should get >that done sooner, not later. or that java shouldn't be submitted (or >committed) without the accompanying documentation. > Kinda. >2) do i consider the xdoc markup to be as important as the java source in >the sense that both are now used to create the management content? > Nope. I'm talking about src/xdocs/* Most projects have this source, it gets transformed into HTML and it visible at http://jakarta.apache.org/avalon/... I'm raising the issue because our documentation, particilarly website docs, are constantly critisized. It does not matter how good our code is... (I could waffle for another 300 words). Basically, only a subset of committers work on xdocs at all. Some of them do content, some do infrastructure (stylesheets etc), some do both. But the main point is that it is only a subset. We cannot bear the burdon on our own. I expect I'm going to get flamed by others now. This is not personal, it is just that I'd like to raise the bar for committer entry slightly <fx: ducks for more flames>. - Paul >as far as that goes, here's my POV. xdoc is an optional, but convenient way >to make the mxinfo files, especially since it can 'introspect' the class >directly and fill in information automatically. as it was already used to >produce the xinfo files i didn't consider the implications of adopting it, >since it does not impose any additional dependencies. also, since its only >needed to produce the mxinfo files, not by the SystemManager that reads >them, our liability is limited to finding another way to produce the files >in that format. (which is what i thought we'd do in order to >internationalize the descriptions, if/when that's done). > >assuming this answer is somewhat on the mark, the next question is where do >non-automatically generated mxinfo files fit in the source tree... > > > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
