From: Christian K. <kre...@in...> - 2002-03-09 21:28:49
|
Drew Smith wrote: > > After a quick run through the apps dir what I've found is : > > e - fine > efsd - a few errors in the sgml I've listed the output here for discussion sake. <snip> Mhmmm well interesting, I don't get these here: elwood@Gonzo:/usr/local/devel/e17/apps/efsd > make html-docs make -C ./doc html-docs make[1]: Entering directory `/usr/local/devel/e17/apps/efsd/doc' ./kernel-doc -docbook <manual.raw >efsd-manual.sgml /bin/sh ../mkinstalldirs ./efsd-manual-0.0.1/figures cd efsd-manual-0.0.1 && /usr/bin/jade -t sgml -d ../html-customizations.dsl ../efsd-manual.sgml cd figures && cp -f *.gif ../efsd-manual-0.0.1/figures cd figures && cp -f *.png ../efsd-manual-0.0.1/figures cp: cannot stat `*.png': No such file or directory make[1]: [html-docs] Error 1 (ignored) cd figures && cp -f *.jpg ../efsd-manual-0.0.1/figures cp: cannot stat `*.jpg': No such file or directory make[1]: [html-docs] Error 1 (ignored) cp -f stylesheet.css efsd-manual-0.0.1/stylesheet.css tar cfvz efsd-manual-0.0.1.tar.gz efsd-manual-0.0.1 efsd-manual-0.0.1/ efsd-manual-0.0.1/r1590.html efsd-manual-0.0.1/r2551.html etc. That's with the version in cvs. That'll have to wait a bit, don't have time to track down the problem. > I'm assuming that the numbers in the output reference the problem > somehow, but how? I'm guessing that when the <note> is hit on line 244 > (229+13) it's causing the preceeding <para> to barf since there is no > </para> preceeding it? Are <notes> not permitted within a <para>graph? You can always find info about that in the docbook manual, http://www.docbook.org/tdg/en/ . Just check if the nesting is correct. Maybe there's an issue with different docbook dtds, but I don't think so, the tags in your message are all super-standard. > stuff in apps as we are attempting to for the libs (other than a select > group) or should we attempt to make all of the documentation uniform > across all packages? Of course it goes without saying that in the case > of etcher for instance, that there will be no interface to it (?) so the > documentation would be entirely different anyway and include commandline > options, environment issues and the like, but you can see what I'm > getting at. By interface you mean api, right? Well there could still be a section in the manual with code documentation for developers, and even if not, I'd still write the manual using docbook. You don't *need* to integrate code, but you can. That's why I think this way of writing doco is a hundred times better than the usual javadoc stuff that gives you *only* api. That's good when you only want api doco, but not for anything else. Cheers, Christian. -- ________________________________________________________________________ http://www.whoop.org |