Sounds good. I'm sure whatever you think is needed will help. Right now the "Task References" are created by NDoc via the userdoc target. It generates a html page for each task and an index page for them all. These docs are generated by the xml code comments, but can be supplemented/replaced by external xml files. NDoc has a lot of options for this. I'd like to see if we can combine the other docs into this format. That way we can use one tool to generate/format all our help, and the website.
In other projects I've worked with we have used all the documentation to generate the help system, faqs and website. I'd like to see a single document source that can be combined into all of these. Does this clarify anything? ----- Original Message ----- From: "Jeffrey McManus" <[EMAIL PROTECTED]> To: "Scott Hernandez" <[EMAIL PROTECTED]> Cc: <[EMAIL PROTECTED]> Sent: Wednesday, January 22, 2003 8:37 PM Subject: Re: [nant-dev] documentation error > I'm happy to contribute as much as I can to docs; I've > synched everything up with CVS and I'll start looking > at them tonight. With your permission, one of things > I'd like to start thinking about is a short > introductory blurb/doc that introduces the concept of > a build tool at a high level for experienced > developers who have never used a build tool (a profile > that will apply to many Microsoft tools developers, I > suspect). > > With respect to XMLification of the docs, I've done > this a few times before, and it has consistently > taught me one thing -- frequently, the amount of time > that developers spend managing the XML (fidding with > tags, getting the elements correct, etc.) exceeds the > benefits. I say this as a huge XML proponent who uses > XML on a near-daily basis. But generally for > documentation my watchword is "make it as easy for > people to contribute as possible." Whether it's in > HTML, XML, or on the back of a cocktail napkin, > getting good information is more important than what > format it's in. > > Looking at your source, it looks like you're using > inline XML comments already, which is great. I wonder > if it would be OK, at least for now, if we just keep > the HTML documentation in HTML and transform the > inline XML comments into HTML/PDF/CHM/whatever, using > the inline code comments emitted by the compiler? Does > this sound insane? To me, this seems like it would be > much less work -- at the end of the day if you want to > (for example) convert HTML pages to PDF you could > easily do so without bothering with an intervening XML > step. > > One question -- what's the status of the tasks page > (\nant\doc\help\tasks\index.html)? It's a dead link in > the source I just checked out; is it going to be > autogenned from the source at some point? Should we > maybe stick a placeholder page in there until the real > page is ready? > > Jeffrey > > --- Scott Hernandez <[EMAIL PROTECTED]> wrote: > > Hi Jeffrey, > > > > It looks like this has been fixed in cvs. There is > > no "help/documenter" > > person, but if you would like to help out, there is > > plenty to do :) And we > > would really appreciate it. > > > > The number one thing on my list is to convert the > > docs here > > (http://nant.sourceforge.net/help/index.html; > > excluding the task ref) into > > xml so we can more easily work with it. Then maybe > > we can generate more > > formats of help (like a chm or pdf). Currently these > > documents exist in a > > proprietary format (fogdesk, I think) and are pretty > > hard to do anything > > with but generate html from. > > > > If you need any more explanation, I can help out, or > > someone on the list > > will be able to fill in the details. > > __________________________________________________ > Do you Yahoo!? > Yahoo! Mail Plus - Powerful. Affordable. Sign up now. > http://mailplus.yahoo.com > > ------------------------------------------------------- This SF.NET email is sponsored by: SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See! http://www.vasoftware.com _______________________________________________ Nant-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/nant-developers
