Re: [nant-dev] documentation error
You should post a patch to this list. read up on cvs diff, use the -u option for readibility. Your contribution is welcome. Ian I made a pass through all of them, correcting spelling mistakes and adding content here and there using my tool of choice (which happens to be Dreamweaver, but could have been anything). It took an hour, I didn't have to learn anything new and as a result it was easy. (Although at this point, I have no idea what to do with the product of my work.) -J. __ 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 --- 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
Re: [nant-dev] documentation error
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
Re: [nant-dev] documentation error
--- Scott Hernandez [EMAIL PROTECTED] wrote: Right now the Task References are created by NDoc via the userdoc target. The product of this process doesn't seem to be getting checked in. The net result is, when you check out the docs from CVS, the core part of the documentation (the tasks reference) isn't available. What would it take to make this happen? Jeffrey __ 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
Re: [nant-dev] documentation error
It should not be checked in. Once it is generated, it is stale and it is not the source of documentation anyway. Why do you want it checked into source control as html? (it should not be edited in that form) - Original Message - From: Jeffrey McManus [EMAIL PROTECTED] Sent: Thursday, January 23, 2003 2:51 PM --- Scott Hernandez [EMAIL PROTECTED] wrote: Right now the Task References are created by NDoc via the userdoc target. The product of this process doesn't seem to be getting checked in. The net result is, when you check out the docs from CVS, the core part of the documentation (the tasks reference) isn't available. What would it take to make this happen? --- 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
Re: [nant-dev] documentation error
I understand that it shouldn't be edited directly, but I think it should at least be checked in, because it represents part of the distributable package of the application. One objective of source code is to be able to view, at a glance, the state of an application (including its distributable packages; i.e. its documentation) at any point in time. Whether it was generated by a human or by an automated process shouldn't matter. If somebody needs to re-create some arbitrary build three years from now to replace it on a production system that standardized on it, they're going to be hosed because they won't be able to get documentation that matches the build they have. The practical problem that I (and lots of others, in all likelihood) are having is, without a current snapshot of the state of the task lists, there is no way to get a reference to the latest tasks, short of re-building the project, which (it seems to me) you shouldn't have to do just to get docs. -J. --- Scott Hernandez [EMAIL PROTECTED] wrote: It should not be checked in. Once it is generated, it is stale and it is not the source of documentation anyway. Why do you want it checked into source control as html? (it should not be edited in that form) - Original Message - From: Jeffrey McManus [EMAIL PROTECTED] Sent: Thursday, January 23, 2003 2:51 PM --- Scott Hernandez [EMAIL PROTECTED] wrote: Right now the Task References are created by NDoc via the userdoc target. The product of this process doesn't seem to be getting checked in. The net result is, when you check out the docs from CVS, the core part of the documentation (the tasks reference) isn't available. What would it take to make this happen? __ 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
Re: [nant-dev] documentation error
Jeffrey, The source in cvs does represent the documentation at any point, not the other way around. What your suggesting would lead to ever more dissimilarity between a build and the docs in the system. We would need to check in new docs whenever a source file is changed! That is just wrong. Also, we do builds and tag the source control system when a release is done. It you get all of cvs (by tag or date) and follow the build/doc/release process you will get exactly what you want. It will be a snapshot at that point in time. Everything will match up. I'm a strong believer in *not* storing binary distributions in the same cvs repository as the source. In fact, I would argue against storing most of the stuff that we have in bin if we weren't a build tool that built itself. I agree that the website should probably contain the latest docs of the current cvs system, as well as the last major release. But the source control system should not. I strongly believe that we should not store duplicate and redundant information under source control. We store source, not many formats of the source; just the source in the source control system. - Original Message - From: Jeffrey McManus [EMAIL PROTECTED] To: Scott Hernandez [EMAIL PROTECTED] Cc: [EMAIL PROTECTED] Sent: Thursday, January 23, 2003 4:41 PM Subject: Re: [nant-dev] documentation error I understand that it shouldn't be edited directly, but I think it should at least be checked in, because it represents part of the distributable package of the application. One objective of source code is to be able to view, at a glance, the state of an application (including its distributable packages; i.e. its documentation) at any point in time. Whether it was generated by a human or by an automated process shouldn't matter. If somebody needs to re-create some arbitrary build three years from now to replace it on a production system that standardized on it, they're going to be hosed because they won't be able to get documentation that matches the build they have. The practical problem that I (and lots of others, in all likelihood) are having is, without a current snapshot of the state of the task lists, there is no way to get a reference to the latest tasks, short of re-building the project, which (it seems to me) you shouldn't have to do just to get docs. --- 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
Re: [nant-dev] documentation error
--- Scott Hernandez [EMAIL PROTECTED] wrote: The source in cvs does represent the documentation at any point, not the other way around. What your suggesting would lead to ever more dissimilarity between a build and the docs in the system. We would need to check in new docs whenever a source file is changed! That is just wrong. If only there were some kind of automated tool to do that... :) I'm accustomed to thinking of docs as a part of the deliverable package and as such, something that should be checked in. I'm willing to accept that not everybody does it that way, though. Maybe working backwards from my original problem would shed light on this. Let's take an example...right now in the nightly builds there is support for a tag called 'nunit2'. How would someone get access to documentation on this? -J. __ 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
RE: [nant-dev] documentation error
Maybe working backwards from my original problem would shed light on this. Let's take an example...right now in the nightly builds there is support for a tag called 'nunit2'. How would someone get access to documentation on this? The correct answer is: Do a point release, already. The current stable release is over six months old and is missing some fairly major functionality. The product's not at 1.0 yet, so bugs and workarounds are acceptable (as long as they are documented). It's post-holidays; surely at least one of the committers can get a release out the door. --- 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
Re: [nant-dev] documentation error
Jeffrey McManus wrote: I'm accustomed to thinking of docs as a part of the deliverable package and as such, something that should be checked in. I'm willing to accept that not everybody does it that way, though. Having docs checked in makes sense if they are edited as html. Ours are generated. We should be updating the website regularly with the latest docs. Perhaps the nightlies should include this too. But they shouldn't be in cvs. Ian Maybe working backwards from m original problem would shed light on this. Let's take an example...right now in the nightly builds there is support for a tag called 'nunit2'. How would someone get access to documentation on this? -J. __ 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 --- 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
Re: [nant-dev] documentation error
Having docs checked in makes sense if they are edited as html. Ours are generated. We should be updating the website regularly with the latest docs. Perhaps the nightlies should include this too. Updating the website with documentation on features that aren't in the latest stable build might lead to confusion among people who use (for example) 0.7 and expect what's on the site to match version 0.7. Sticking the latest docs in the nightlies is an excellent idea though. Reiterating my original question lest it get lost in the shuffle: is there any way to view HTML documentation on 0.8 tasks today short of rebuilding the project from source? -J. __ 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
Re: [nant-dev] documentation error
No, there is no way to see the task refs unless you build the userdoc target. Note: The currently nightly are cvs snapshots, not builds. We need a nightly/periodic build to do what you are suggesting. I am all for this, and in fact I have a machine to do it, but there isn't enough time in the day. :) I just haven't gotten it done. - Original Message - From: Jeffrey McManus [EMAIL PROTECTED] To: Ian MacLean [EMAIL PROTECTED] Cc: Scott Hernandez [EMAIL PROTECTED]; [EMAIL PROTECTED] Sent: Thursday, January 23, 2003 6:29 PM Subject: Re: [nant-dev] documentation error Having docs checked in makes sense if they are edited as html. Ours are generated. We should be updating the website regularly with the latest docs. Perhaps the nightlies should include this too. Updating the website with documentation on features that aren't in the latest stable build might lead to confusion among people who use (for example) 0.7 and expect what's on the site to match version 0.7. Sticking the latest docs in the nightlies is an excellent idea though. Reiterating my original question lest it get lost in the shuffle: is there any way to view HTML documentation on 0.8 tasks today short of rebuilding the project from source? -J. __ 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
Re: [nant-dev] documentation error
--- Scott Hernandez [EMAIL PROTECTED] wrote: Oh. It sounds so simple, but this lever of automation we do not have. It would require cvs polling, or a linux build environment on sourceforge.net. Yep, I didn't mean it seriously -- hence the smiley after the suggestion. (Although...I'm not super familiar with it, but doesn't this Draco.NET thing do cvs polling?) I really don't want to hinder you from helping, maybe so other people can comment with their opinions here. I think that you and I have very different ideas about what should be in source control. Let's chuck my original put-docs-in-source-control suggestion; it's a red herring. I just think that the core of the documentation (the task reference) should match the current snapshot and be somehow available. If auto-putting it into the nightly snap isn't viable, then figuring out a way to make all the docs of the current snap somehow generally available without having to download source and do a build is the desired outcome. (I agree that doing a release would be the optimum solution, but in the absence of that, it seems like there should be a way to get interim docs on the version that's being worked on. Right?) We're absolutely in agreement that making it easy to contribute is a valuable goal. Last night I (a CVS novice) was able to fairly quickly use CVS to suck down the current source and HTML docs. I made a pass through all of them, correcting spelling mistakes and adding content here and there using my tool of choice (which happens to be Dreamweaver, but could have been anything). It took an hour, I didn't have to learn anything new and as a result it was easy. (Although at this point, I have no idea what to do with the product of my work.) -J. __ 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
[nant-dev] documentation error
There's an HTML error at the bottom of the page describing the 'nunit' task (http://nant.sourceforge.net/help/tasks/nunittask.html). This error occurs in both IE 6.0 and Mozilla (Phoenix). It looks like the page wants to document an attribute of the nunit task, but it got munged somehow? Anyway. Does the project have someone whose job it is to specifically address documentation issues? If not, I'd be happy to help out. Jeffrey __ Do you Yahoo!? Yahoo! Mail Plus - Powerful. Affordable. Sign up now. http://mailplus.yahoo.com --- This SF.net email is sponsored by: Scholarships for Techies! Can't afford IT training? All 2003 ictp students receive scholarships. Get hands-on training in Microsoft, Cisco, Sun, Linux/UNIX, and more. www.ictp.com/training/sourceforge.asp ___ Nant-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/nant-developers
Re: [nant-dev] documentation error
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. Thanks, Scott - Original Message - From: Jeffrey McManus [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Wednesday, January 22, 2003 10:57 AM Subject: [nant-dev] documentation error There's an HTML error at the bottom of the page describing the 'nunit' task (http://nant.sourceforge.net/help/tasks/nunittask.html). This error occurs in both IE 6.0 and Mozilla (Phoenix). It looks like the page wants to document an attribute of the nunit task, but it got munged somehow? Anyway. Does the project have someone whose job it is to specifically address documentation issues? If not, I'd be happy to help out. Jeffrey __ Do you Yahoo!? Yahoo! Mail Plus - Powerful. Affordable. Sign up now. http://mailplus.yahoo.com --- This SF.net email is sponsored by: Scholarships for Techies! Can't afford IT training? All 2003 ictp students receive scholarships. Get hands-on training in Microsoft, Cisco, Sun, Linux/UNIX, and more. www.ictp.com/training/sourceforge.asp ___ Nant-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/nant-developers --- This SF.net email is sponsored by: Scholarships for Techies! Can't afford IT training? All 2003 ictp students receive scholarships. Get hands-on training in Microsoft, Cisco, Sun, Linux/UNIX, and more. www.ictp.com/training/sourceforge.asp ___ Nant-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/nant-developers
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: Scholarships for Techies! Can't afford IT training? All 2003 ictp students receive scholarships. Get hands-on training in Microsoft, Cisco, Sun, Linux/UNIX, and more. www.ictp.com/training/sourceforge.asp ___ Nant-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/nant-developers
