From mario.sopena at gmail.com Mon Nov 12 16:32:08 2007 From: mario.sopena at gmail.com (Mario Sopena Novales) Date: Mon, 12 Nov 2007 22:32:08 +0100 Subject: [Mono-docs-list] Two bugfixes and css strikes back Message-ID: Hi guys, long time no code... well, I've come with a patch for mono-tools/docbrowser that fixes 2 bugs (#324305 and #322097) and resurrects the css-enabled documentation which was disabled by mistake (I think so, I didn't call CSI to investigate further, :-P). See what do you think and If I should commit the patch. -------------- next part -------------- A non-text attachment was scrubbed... Name: patch.diff Type: text/x-patch Size: 5038 bytes Desc: not available Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071112/e2163719/attachment.bin From miguel at novell.com Sat Nov 17 15:27:52 2007 From: miguel at novell.com (Miguel de Icaza) Date: Sat, 17 Nov 2007 15:27:52 -0500 Subject: [Mono-docs-list] Two bugfixes and css strikes back In-Reply-To: References: Message-ID: <1195331272.8373.36.camel@erandi.boston.ximian.com> Hello! > long time no code... well, I've come with a patch for > mono-tools/docbrowser that fixes 2 bugs (#324305 and #322097) and > resurrects the css-enabled documentation which was disabled by mistake > (I think so, I didn't call CSI to investigate further, :-P). > > See what do you think and If I should commit the patch. Please feel free to commit them. From valentin.sawadski at gmx.de Sat Nov 24 04:35:55 2007 From: valentin.sawadski at gmx.de (Valentin Sawadski) Date: Sat, 24 Nov 2007 10:35:55 +0100 Subject: [Mono-docs-list] Proposing a new documentation subsystem Message-ID: <1195896955.4040.33.camel@pi1536.local> Hello everybody, let's remove the dust from this list again ;-) Today I would like to propose a new documentation subsystem to completely replace the old one. Because replacing seems like such a big step I would like to explain why I want to abolish it: - Insufficient support for "Multi-Version" files (e.g. Class-Libs from .NET 1.1 and 2.0) because the current "Since Version X.Y" does not work if a member is only available in 1.1 and not in 2.0. - Generic Types and Members are not fully supported in the documentation browser. - Automated user-contributions do not work properly (I don't know if a contribution has ever made it into the documentation). - Even if documentation has been updated the updates won't make it back to the user before a new version of mono has been released. (With other words, there is no way to update offline-documentation) - Documentation work-cycle is pretty complicated. It is very unhandy to run many tools to do one simple task. (monodoc, browser, mdassembler) - No Revision control (this is not a big turn-off however it would be quite handy when user-contributions will finally work) and no user comments (again not very important but nice to have) The new documentation subsystem should be able to fulfill all requirements above. This means the new documentation subsystem would consist of a user and server part. The Server Part would mainly be used for data-storage and contribution handling. A simple web-service which is backed by some db would be quite sufficient. For Contribution-administration and adding of new assemblies to the documentation service a simple web-ui should suffice. The Client part however will be more important. It will also have a small SQLite-DB which contains all the data for offline availability. This data will be updated with new documentation from the server regularly. Apart form adding documentation to the class libraries this tool will also support 3rd party assemblies. It should be possible to add libraries or existing documentation to the client application which can than be easily documented. For distribution of the documentation I was thinking of two possibilities: 1. it should be able to export the documentation of the 3rd party assembly to a single file (probably again a SQLite-DB). Users can than xcopy the exported file into some directory so that this db will also be displayed in their browser. 2. If 3rd party developers set up their own documentation server it would be very neat if users get a URL to that server and then "check-out" a copy of the documentation for offline availability. If this subsystem will be designed very nicely this will give 3rd party developers also the ability to set-up a documentation browser as well so that they can also benefit from user-contributed documentation. Hopefully I was able to communicate my ideas well enough and now I'm looking forward to some comments :-) Kind Regards, Valentin S. From jit at occams.info Sat Nov 24 08:14:32 2007 From: jit at occams.info (Joshua Tauberer) Date: Sat, 24 Nov 2007 08:14:32 -0500 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <1195896955.4040.33.camel@pi1536.local> References: <1195896955.4040.33.camel@pi1536.local> Message-ID: <474823B8.3050706@occams.info> I think you're making it too complicated: > - Insufficient support for "Multi-Version" files (e.g. Class-Libs > from .NET 1.1 and 2.0) because the current "Since Version X.Y" does > not work if a member is only available in 1.1 and not in 2.0. This just requires the addition of more tags to the documentation, one that says when a member was removed. > - Generic Types and Members are not fully supported in the > documentation browser. Yeah. > - Automated user-contributions do not work properly (I don't know if a > contribution has ever made it into the documentation). The current system isn't bad fundamentally. I think there's just some personal overhead involved in Miguel taking the contributions and applying them. > - Even if documentation has been updated the updates won't make it back > to the user before a new version of mono has been released. (With > other words, there is no way to update offline-documentation) Fair point. > - Documentation work-cycle is pretty complicated. It is very unhandy to > run many tools to do one simple task. (monodoc, browser, mdassembler) Maybe.... > - No Revision control (this is not a big turn-off however it would be > quite handy when user-contributions will finally work) and no user > comments (again not very important but nice to have) The documentation is under revision control in Subversion (though, you may mean you need something more explicit for deploying updates). My two cents if you really want to address some of these things would be to start on the UI side and make something that works "properly" with a plain ZIP file of the XML documentation files, and no changes on the server or mdassembler side. Once that works, if you need to cache some indexes or whatever to be able to get to pages quickly, or if you need changes to the XML documentation format, then look into that. A documentation browser should be a simple program at its core. You might also want to start by taking advantage of the monodocs2html stylesheet, which Jon has fixed up quite a bit for generics. -- - Josh Tauberer http://razor.occams.info "Yields falsehood when preceded by its quotation! Yields falsehood when preceded by its quotation!" Achilles to Tortoise (in "G?del, Escher, Bach" by Douglas Hofstadter) Valentin Sawadski wrote: > Hello everybody, > > let's remove the dust from this list again ;-) > > Today I would like to propose a new documentation subsystem to > completely replace the old one. > > Because replacing seems like such a big step I would like to explain why > I want to abolish it: > - Insufficient support for "Multi-Version" files (e.g. Class-Libs > from .NET 1.1 and 2.0) because the current "Since Version X.Y" does > not work if a member is only available in 1.1 and not in 2.0. > - Generic Types and Members are not fully supported in the > documentation browser. > - Automated user-contributions do not work properly (I don't know if a > contribution has ever made it into the documentation). > - Even if documentation has been updated the updates won't make it back > to the user before a new version of mono has been released. (With > other words, there is no way to update offline-documentation) > - Documentation work-cycle is pretty complicated. It is very unhandy to > run many tools to do one simple task. (monodoc, browser, mdassembler) > - No Revision control (this is not a big turn-off however it would be > quite handy when user-contributions will finally work) and no user > comments (again not very important but nice to have) > > The new documentation subsystem should be able to fulfill all > requirements above. This means the new documentation subsystem would > consist of a user and server part. > > The Server Part would mainly be used for data-storage and contribution > handling. A simple web-service which is backed by some db would be quite > sufficient. For Contribution-administration and adding of new assemblies > to the documentation service a simple web-ui should suffice. > > The Client part however will be more important. It will also have a > small SQLite-DB which contains all the data for offline availability. > This data will be updated with new documentation from the server > regularly. > Apart form adding documentation to the class libraries this tool will > also support 3rd party assemblies. It should be possible to add > libraries or existing documentation to the client application which can > than be easily documented. For distribution of the documentation I was > thinking of two possibilities: > 1. it should be able to export the documentation of the 3rd party > assembly to a single file (probably again a SQLite-DB). Users can > than xcopy the exported file into some directory so that this db > will also be displayed in their browser. > 2. If 3rd party developers set up their own documentation server it > would be very neat if users get a URL to that server and then > "check-out" a copy of the documentation for offline availability. > > If this subsystem will be designed very nicely this will give 3rd party > developers also the ability to set-up a documentation browser as well so > that they can also benefit from user-contributed documentation. > > Hopefully I was able to communicate my ideas well enough and now I'm > looking forward to some comments :-) > > Kind Regards, > Valentin S. > > _______________________________________________ > Mono-docs-list maillist - Mono-docs-list at lists.ximian.com > http://lists.ximian.com/mailman/listinfo/mono-docs-list From valentin.sawadski at gmx.de Sat Nov 24 10:16:31 2007 From: valentin.sawadski at gmx.de (Valentin Sawadski) Date: Sat, 24 Nov 2007 16:16:31 +0100 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <474823B8.3050706@occams.info> References: <1195896955.4040.33.camel@pi1536.local> <474823B8.3050706@occams.info> Message-ID: <1195917391.4039.19.camel@pi1536.local> Hello Joshua, On Sat, 2007-11-24 at 08:14 -0500, Joshua Tauberer wrote: > I think you're making it too complicated: > > > - Insufficient support for "Multi-Version" files (e.g. Class-Libs > > from .NET 1.1 and 2.0) because the current "Since Version X.Y" does > > not work if a member is only available in 1.1 and not in 2.0. > > This just requires the addition of more tags to the documentation, one > that says when a member was removed. I don't like that idea because this might introduce some since x, removed in y, reintroduced in z.... patterns (Yes I know it is unlikely but still possible) > > - Automated user-contributions do not work properly (I don't know if a > > contribution has ever made it into the documentation). > > The current system isn't bad fundamentally. I think there's just some > personal overhead involved in Miguel taking the contributions and > applying them. Is he still the only one in charge of the documentation approval? > > - Documentation work-cycle is pretty complicated. It is very unhandy to > > run many tools to do one simple task. (monodoc, browser, mdassembler) > > Maybe.... Compared to the MS world it is really more complicated on mono. A simple "/doc" compiler flag and running nDoc would suffice on windows. > My two cents if you really want to address some of these things would be > to start on the UI side and make something that works "properly" with a > plain ZIP file of the XML documentation files, and no changes on the > server or mdassembler side. Once that works, if you need to cache some > indexes or whatever to be able to get to pages quickly, or if you need > changes to the XML documentation format, then look into that. A > documentation browser should be a simple program at its core. Yes you are right the documentation browser should be as slim as possible. However I still do think that the current xml-only approach does not work sufficiently because of the limitations mentioned in my first mail. A small database back-end could provide a lot more opportunities for the creation and maintenance of documentation. Kind Regards, Valentin S. From zpon.dk at gmail.com Sat Nov 24 10:52:42 2007 From: zpon.dk at gmail.com (=?ISO-8859-1?Q?S=F8ren_Juul?=) Date: Sat, 24 Nov 2007 16:52:42 +0100 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <1195896955.4040.33.camel@pi1536.local> References: <1195896955.4040.33.camel@pi1536.local> Message-ID: Hello I like your proposal, especially the part about user contributions and comments (I believe they could help many people). But i think a database on the client side would be much work, and make it more difficult to import new documentation library's, although it could be figured out. Maybe I am wrong, if so, please correct me... 2007/11/24, Valentin Sawadski : > > Hello everybody, > > let's remove the dust from this list again ;-) > > Today I would like to propose a new documentation subsystem to > completely replace the old one. > > Because replacing seems like such a big step I would like to explain why > I want to abolish it: > - Insufficient support for "Multi-Version" files (e.g. Class-Libs > from .NET 1.1 and 2.0) because the current "Since Version X.Y" does > not work if a member is only available in 1.1 and not in 2.0. > - Generic Types and Members are not fully supported in the > documentation browser. > - Automated user-contributions do not work properly (I don't know if a > contribution has ever made it into the documentation). > - Even if documentation has been updated the updates won't make it back > to the user before a new version of mono has been released. (With > other words, there is no way to update offline-documentation) > - Documentation work-cycle is pretty complicated. It is very unhandy to > run many tools to do one simple task. (monodoc, browser, mdassembler) > - No Revision control (this is not a big turn-off however it would be > quite handy when user-contributions will finally work) and no user > comments (again not very important but nice to have) > > The new documentation subsystem should be able to fulfill all > requirements above. This means the new documentation subsystem would > consist of a user and server part. > > The Server Part would mainly be used for data-storage and contribution > handling. A simple web-service which is backed by some db would be quite > sufficient. For Contribution-administration and adding of new assemblies > to the documentation service a simple web-ui should suffice. > > The Client part however will be more important. It will also have a > small SQLite-DB which contains all the data for offline availability. > This data will be updated with new documentation from the server > regularly. > Apart form adding documentation to the class libraries this tool > will > also support 3rd party assemblies. It should be possible to add > libraries or existing documentation to the client application which can > than be easily documented. For distribution of the documentation I was > thinking of two possibilities: > 1. it should be able to export the documentation of the 3rd party > assembly to a single file (probably again a SQLite-DB). Users can > than xcopy the exported file into some directory so that this db > will also be displayed in their browser. > 2. If 3rd party developers set up their own documentation server it > would be very neat if users get a URL to that server and then > "check-out" a copy of the documentation for offline availability. > > If this subsystem will be designed very nicely this will give 3rd party > developers also the ability to set-up a documentation browser as well so > that they can also benefit from user-contributed documentation. > > Hopefully I was able to communicate my ideas well enough and now I'm > looking forward to some comments :-) > > Kind Regards, > Valentin S. > > _______________________________________________ > Mono-docs-list maillist - Mono-docs-list at lists.ximian.com > http://lists.ximian.com/mailman/listinfo/mono-docs-list > -- Med venlig hilsen / Kind Regards S?ren Juul -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071124/64e18d8a/attachment.html From jonpryor at vt.edu Sat Nov 24 14:25:07 2007 From: jonpryor at vt.edu (Jonathan Pryor) Date: Sat, 24 Nov 2007 14:25:07 -0500 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <1195917391.4039.19.camel@pi1536.local> References: <1195896955.4040.33.camel@pi1536.local> <474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local> Message-ID: <1195932307.4588.43.camel@lina.magi.jprl.com> On Sat, 2007-11-24 at 16:16 +0100, Valentin Sawadski wrote: > On Sat, 2007-11-24 at 08:14 -0500, Joshua Tauberer wrote: > > I think you're making it too complicated: > > > > > - Insufficient support for "Multi-Version" files (e.g. Class-Libs > > > from .NET 1.1 and 2.0) because the current "Since Version X.Y" does > > > not work if a member is only available in 1.1 and not in 2.0. > > > > This just requires the addition of more tags to the documentation, one > > that says when a member was removed. > > I don't like that idea because this might introduce some since x, > removed in y, reintroduced in z.... patterns (Yes I know it is unlikely > but still possible) I've been doing some (minor) thinking about this. What it primarily would entail is duplicating the /Type/AssemblyInfo element to be a per-member element as well, listing each and every version that the element is within. This should be trivial to do -- monodocer would just insert the current assembly version into this element if it's found, and if the member _isn't_ within the current assembly monodocer would ensure that the element is NOT present for the current assembly version. Monodoc display could now be: Requirements: Namespace: ... Culture: ... Assemblies: mscorlib 1.0.500.0 mscorlib 2.0.0.0 mscorlib 2.1.0.0 etc. This perfectly handles the "introduce some since x, removed in y, reintroduced in z" pattern, as it would only list the assembly versions that the member was present within, i.e. x and z, but not y. > > > - Automated user-contributions do not work properly (I don't know if a > > > contribution has ever made it into the documentation). > > > > The current system isn't bad fundamentally. I think there's just some > > personal overhead involved in Miguel taking the contributions and > > applying them. > > Is he still the only one in charge of the documentation approval? Yes, afaik. The reason for Miguel as a bottleneck is for copyright concerns -- we don't want someone copy+pasting MSDN documentation into monodoc w/o any form of validation before it's committed to svn. Perhaps we just need a better automated validation system...but this will be a concern no matter what format/architecture we have. > > > - Documentation work-cycle is pretty complicated. It is very unhandy to > > > run many tools to do one simple task. (monodoc, browser, mdassembler) > > > > Maybe.... > > Compared to the MS world it is really more complicated on mono. A simple > "/doc" compiler flag and running nDoc would suffice on windows. Mono isn't much more complicated, if that's what you want: gmcs /doc /t:lib YourAssembly.cs monodocer -importslashdoc:YourAssembly.xml -assembly:DocTest.dll mdassembler --ecma en -o YourAssembly-docs monodocs2html -source:en -dest:/path/to/html/docs You only need one of the latter two commands; mdassembler is to view the docs in monodoc, and monodocs2html is for static HTML output. If you want to use an ASP.NET server (as http://www.go-mono.com/docs does), you don't need either of these commands. The problem typically isn't the _format_ of Mono's documentation, the problem is _writing_ the documentation in the first place. Saying "use the /doc compiler flag" isn't a solution, as you still need to _write_ the documentation within your source files, which doesn't permit WYSIWIG editing of the documentation. Afaik, NDoc doesn't support that either, which is why monodoc is nice -- it *is* a WYSIWIG editor for Mono-formatted documentation: monodoc --edit path/to/monodoc-format/docs > > My two cents if you really want to address some of these things would be > > to start on the UI side and make something that works "properly" with a > > plain ZIP file of the XML documentation files, and no changes on the > > server or mdassembler side. Once that works, if you need to cache some > > indexes or whatever to be able to get to pages quickly, or if you need > > changes to the XML documentation format, then look into that. A > > documentation browser should be a simple program at its core. > > Yes you are right the documentation browser should be as slim as > possible. However I still do think that the current xml-only approach > does not work sufficiently because of the limitations mentioned in my > first mail. A small database back-end could provide a lot more > opportunities for the creation and maintenance of documentation. I'm still not convinced. Your original list: > - Insufficient support for "Multi-Version" files (e.g. Class-Libs > from .NET 1.1 and 2.0) Above is a potential solution for this. I just need to implement it. > - Generic Types and Members are not fully supported in the > documentation browser. That's not a documentation format limitation, that's a browser limitation. The browser just needs to be updated. > - Automated user-contributions do not work properly (I don't know if a > contribution has ever made it into the documentation). Again, this isn't a problem with the format, but of the infrastructure. > - Even if documentation has been updated the updates won't make it back > to the user before a new version of mono has been released. (With > other words, there is no way to update offline-documentation) Also not a problem with the format. Monodoc largely reads ZIP files containing the documentation, so if you want updated docs you just need to update the ZIP files. It should be trivial to implement support into Monodoc to download & use updated ZIP files; the problem is one of Unix permissions (distro-provided files will be owned by root, and thus can't be updated by normal users). Regardless, it's solvable w/o a format change. > - Documentation work-cycle is pretty complicated. It is very unhandy to > run many tools to do one simple task. (monodoc, browser, mdassembler) I think you're confusing things. monodoc *is* the browser, and is NOT needed for the editing process. (It's nice to have, as it's a WYSIWIG editor, but it's not necessary -- I regularly use gvim to edit the raw XML. It would be nice to improve it's WYSIWIG capabilities; it displays the formatting, but it doesn't permit adding new sections, such as the elements, etc.) So if you don't care about editing -- you earlier mentioned 'CSC /doc' as being superior, and that has NO WYSIWIG editor -- you don't need monodoc. Just monodocer and monodocs2html (for HTML output), xsp (for ASPX output), or mdassembler (to browse docs within monodoc). > - No Revision control (this is not a big turn-off however it would be > quite handy when user-contributions will finally work) and no user > comments (again not very important but nice to have) It's XML. It's inherently compatible with revision control, as it's text. :-) I've been improving the revision control question over time as well, such as by sorting documentation members so that smaller patch files are generated when committing the updates to svn. All this is to say that I don't see any need to change the format -- extend, yes, but not completely change -- nor do I see what advantages a local SQL database would provide. A local database would have ALL the same problems as current monodoc wrt updating contents (normal users can't update root-owned files, and all files installed by the package manager are owned by root). A database also complicates the revision control question, as far as I'm concerned -- how do you *easily* integrate e.g. SQLite with Subversion or git? (Storing the entire revision history within SQLite is NOT a "revision control" solution, as far as I'm concerned.) Furthermore, monodoc *already* supports 3rd party assemblies -- this is how Gtk# and Mono.Fuse documentation, among other assemblies, is integrated into monodoc. So aside from entailing lots of work to re-find the same problems we currently have (a WYSIWIG editor which still needs improvement, solving the update problem), what does changing the format buy us? What does SQLite permit that XML doesn't? Please enlighten me. Thanks, - Jon From valentin.sawadski at gmx.de Sun Nov 25 07:22:33 2007 From: valentin.sawadski at gmx.de (Valentin Sawadski) Date: Sun, 25 Nov 2007 13:22:33 +0100 Subject: [Mono-docs-list] [PATCH] More detailed error message of the browser when failing to initialize the renderer Message-ID: <1195993353.4777.9.camel@pi1536.local> Hello everybody, my Monodoc-Browser was again not working because of some missing unmanaged dependencies. Monodoc was looking for libgtkhtml-3.8.so.15 while 3.14.so.19.1 was present in my system. While this is relatively easy to fix for it has been hard to diagnose since the browser does not show a detailed error message. A "The Renderer could not be initialized" is all you get by now. Therefore I attached a small path to show more error output when the renderer could not be started. This is however more a hack than a real solution. But unfortunately I do not know how to fix the real issue, the unmanaged dependency which could not be found. Kind Regards, Valentin S. -------------- next part -------------- A non-text attachment was scrubbed... Name: browser.cs.diff Type: text/x-patch Size: 3232 bytes Desc: not available Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071125/5f31c532/attachment.bin From valentin.sawadski at gmx.de Sun Nov 25 07:56:03 2007 From: valentin.sawadski at gmx.de (Valentin Sawadski) Date: Sun, 25 Nov 2007 13:56:03 +0100 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <1195932307.4588.43.camel@lina.magi.jprl.com> References: <1195896955.4040.33.camel@pi1536.local> <474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local> <1195932307.4588.43.camel@lina.magi.jprl.com> Message-ID: <1195995363.4777.38.camel@pi1536.local> Hello, On Sat, 2007-11-24 at 14:25 -0500, Jonathan Pryor wrote: > On Sat, 2007-11-24 at 16:16 +0100, Valentin Sawadski wrote: > > On Sat, 2007-11-24 at 08:14 -0500, Joshua Tauberer wrote: > > > I think you're making it too complicated: > > > > > > > - Insufficient support for "Multi-Version" files (e.g. Class-Libs > > > > from .NET 1.1 and 2.0) because the current "Since Version X.Y" does > > > > not work if a member is only available in 1.1 and not in 2.0. > > > > > > This just requires the addition of more tags to the documentation, one > > > that says when a member was removed. > > > > I don't like that idea because this might introduce some since x, > > removed in y, reintroduced in z.... patterns (Yes I know it is unlikely > > but still possible) > > I've been doing some (minor) thinking about this. What it primarily > would entail is duplicating the /Type/AssemblyInfo element to be a > per-member element as well, listing each and every version that the > element is within. This should be trivial to do -- monodocer would just > insert the current assembly version into this element if it's found, and > if the member _isn't_ within the current assembly monodocer would ensure > that the element is NOT present for the current assembly > version. > > Monodoc display could now be: > > Requirements: > Namespace: ... > Culture: ... > Assemblies: > mscorlib 1.0.500.0 > mscorlib 2.0.0.0 > mscorlib 2.1.0.0 > > etc. This perfectly handles the "introduce some since x, removed in y, > reintroduced in z" pattern, as it would only list the assembly versions > that the member was present within, i.e. x and z, but not y. That's great if that can be done so easily :-) > > > > > - Automated user-contributions do not work properly (I don't know if a > > > > contribution has ever made it into the documentation). > > > > > > The current system isn't bad fundamentally. I think there's just some > > > personal overhead involved in Miguel taking the contributions and > > > applying them. > > > > Is he still the only one in charge of the documentation approval? > > Yes, afaik. The reason for Miguel as a bottleneck is for copyright > concerns -- we don't want someone copy+pasting MSDN documentation into > monodoc w/o any form of validation before it's committed to svn. > Perhaps we just need a better automated validation system...but this > will be a concern no matter what format/architecture we have. I know and maybe I should have expressed myself clearer because the point was that I was thinking this could be fixed as well in the new system. > > - Documentation work-cycle is pretty complicated. It is very unhandy to > > run many tools to do one simple task. (monodoc, browser, mdassembler) > > I think you're confusing things. monodoc *is* the browser, and is NOT > needed for the editing process. Sorry that's been a typo I originally wanted to write monodocer. > (It's nice to have, as it's a WYSIWIG > editor, but it's not necessary -- I regularly use gvim to edit the raw > XML. It would be nice to improve it's WYSIWIG capabilities; it displays > the formatting, but it doesn't permit adding new sections, such as the > elements, etc.) > > So if you don't care about editing -- you earlier mentioned 'CSC /doc' > as being superior, and that has NO WYSIWIG editor -- you don't need > monodoc. Just monodocer and monodocs2html (for HTML output), xsp (for > ASPX output), or mdassembler (to browse docs within monodoc). I personally prefer it over the mono approach of documentation. However since /doc is used nowhere in the mono sources this is not an option for documenting mono. > > > - No Revision control (this is not a big turn-off however it would be > > quite handy when user-contributions will finally work) and no user > > comments (again not very important but nice to have) > > It's XML. It's inherently compatible with revision control, as it's > text. :-) > > I've been improving the revision control question over time as well, > such as by sorting documentation members so that smaller patch files are > generated when committing the updates to svn. > > All this is to say that I don't see any need to change the format -- > extend, yes, but not completely change -- nor do I see what advantages a > local SQL database would provide. A local database would have ALL the > same problems as current monodoc wrt updating contents (normal users > can't update root-owned files, and all files installed by the package > manager are owned by root). A database also complicates the revision > control question, as far as I'm concerned -- how do you *easily* > integrate e.g. SQLite with Subversion or git? (Storing the entire > revision history within SQLite is NOT a "revision control" solution, as > far as I'm concerned.) > > Furthermore, monodoc *already* supports 3rd party assemblies -- this is > how Gtk# and Mono.Fuse documentation, among other assemblies, is > integrated into monodoc. I know that monodoc already supports 3rd party assemblies but I was thinking of measures that would enable 3rd party developers also to benefit from the documentation contribution. Which means some that the documentation might contain some kind of url where contributions can be sent to. Apart from the current mono-only contribution. Another point of which I have been thinking would be to add 3rd party documentation without having to rebuild the browser and all the sources. Someway that users only have to open http://3rdparty.com/docs in the documentation browser and the browser downloads all the documentation and integrates them into the database backend. > > So aside from entailing lots of work to re-find the same problems we > currently have (a WYSIWIG editor which still needs improvement, solving > the update problem), what does changing the format buy us? What does > SQLite permit that XML doesn't? > > Please enlighten me. SQLite was just an example data format. In general I was thinking of some database back-end and forgot that changing the database was not possible since this would require root access in most cases. Because that was the point that would bring us most advantages, all changes would be contained in one generic database (where generic means that it would contain the documentation of several assemblies and more) which could easily be filled with data from different sources and yes I was thinking of keeping the revision control within the database so that users could view older revisions of the documentation while browsing (just like in a wiki). All in all I now do think that... - the fact that the database could not be changed as well will kill the biggest benefit I saw in it. - most issues I addressed really don't require rewriting the format from scratch - and I should have slept this over one night before posing it to the list.... >_> Still thanks for the fruit-full conversation. :-) Kind Regards, Valentin S. From jonpryor at vt.edu Sun Nov 25 09:28:47 2007 From: jonpryor at vt.edu (Jonathan Pryor) Date: Sun, 25 Nov 2007 09:28:47 -0500 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <1195995363.4777.38.camel@pi1536.local> References: <1195896955.4040.33.camel@pi1536.local> <474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local> <1195932307.4588.43.camel@lina.magi.jprl.com> <1195995363.4777.38.camel@pi1536.local> Message-ID: <1196000927.30453.15.camel@lina.magi.jprl.com> On Sun, 2007-11-25 at 13:56 +0100, Valentin Sawadski wrote: > On Sat, 2007-11-24 at 14:25 -0500, Jonathan Pryor wrote: > > On Sat, 2007-11-24 at 16:16 +0100, Valentin Sawadski wrote: > > > I don't like that idea because this might introduce some since x, > > > removed in y, reintroduced in z.... patterns (Yes I know it is unlikely > > > but still possible) > > > > I've been doing some (minor) thinking about this. What it primarily > > would entail is duplicating the /Type/AssemblyInfo element to be a > > per-member element as well, listing each and every version that the > > element is within. > > etc. This perfectly handles the "introduce some since x, removed in y, > > reintroduced in z" pattern, as it would only list the assembly versions > > that the member was present within, i.e. x and z, but not y. > > That's great if that can be done so easily :-) The monodocer part should be a fairly minor change, probably < 100 LOC. (Probably < 20.) The browser part will be somewhat more involved, mostly as it deals with XSLT, but I don't think it will be terribly difficult either. Sadly, I'm not sure when I'll get a chance to work on this. Hopefully before year-end. > > > Is he still the only one in charge of the documentation approval? > > > > Yes, afaik. The reason for Miguel as a bottleneck is for copyright > > concerns -- we don't want someone copy+pasting MSDN documentation into > > monodoc w/o any form of validation before it's committed to svn. > > Perhaps we just need a better automated validation system...but this > > will be a concern no matter what format/architecture we have. > > I know and maybe I should have expressed myself clearer because the > point was that I was thinking this could be fixed as well in the new > system. It would be nice to fix this -- perhaps with some Bayesian comparison function and a set of "editors" to approve the changes? -- but regardless, I doubt that such an improved process would require a format change. :-) > I personally prefer it over the mono approach of documentation. However > since /doc is used nowhere in the mono sources this is not an option for > documenting mono. /doc isn't used for a variety of reasons -- many of them listed in the monodocer man page -- including ease of translation (/doc doesn't scale to having multiple languages), and that *good* documentation is *very* verbose (examples, etc.). I find that it's not uncommon for the documentation on a member to be longer than the member itself. Do you *really* want all that documentation within the sources? Furthermore, if you have a web-based documentation editing system, I'd *really* not want that ANYWHERE near my sources, as a bug in the doc system could cause the software to stop compiling... > > Furthermore, monodoc *already* supports 3rd party assemblies -- this is > > how Gtk# and Mono.Fuse documentation, among other assemblies, is > > integrated into monodoc. > > I know that monodoc already supports 3rd party assemblies but I was > thinking of measures that would enable 3rd party developers also to > benefit from the documentation contribution. > > Which means some that the documentation might contain some kind of url > where contributions can be sent to. Apart from the current mono-only > contribution. This sounds easy enough -- extend the .source XML format to include a URL to send edits to. Then the problem "merely" becomes one of documenting the transport format/protocol so that others can write servers to integrate with monodoc. I believe the current protocol is SOAP based, so that may need to change.... > Another point of which I have been thinking would be to add 3rd party > documentation without having to rebuild the browser and all the sources. That's already possible. Just add your (.source, .tree, .zip) set of files to your $lib/monodoc/sources directory, and restart monodoc. You're done. Again, see how Gtk# and Mono.Fuse do things. > Someway that users only have to open http://3rdparty.com/docs in the > documentation browser and the browser downloads all the documentation > and integrates them into the database backend. This is a slightly different problem. It should also be solvable by having the concept of a "local" sources directory in addition to the system sources directory, e.g. ~/.local/share/monodoc/sources/, nd have the local directory read before the system directory. Again, solvable (though I don't know how difficult this would be). > Still thanks for the fruit-full conversation. :-) No problem. I'd love to dedicate more time to to monodocer/etc., but sadly I lack the time. Hopefully I can dedicate some time later this month, but I also have a 2nd baby due soon, so any potential free time is likely going to disappear... - Jon From jonpryor at vt.edu Sun Nov 25 22:05:44 2007 From: jonpryor at vt.edu (Jonathan Pryor) Date: Sun, 25 Nov 2007 22:05:44 -0500 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <1196000927.30453.15.camel@lina.magi.jprl.com> References: <1195896955.4040.33.camel@pi1536.local> <474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local> <1195932307.4588.43.camel@lina.magi.jprl.com> <1195995363.4777.38.camel@pi1536.local> <1196000927.30453.15.camel@lina.magi.jprl.com> Message-ID: <1196046344.30453.24.camel@lina.magi.jprl.com> On Sun, 2007-11-25 at 09:28 -0500, Jonathan Pryor wrote: > The monodocer part should be a fairly minor change, probably < 100 LOC. > (Probably < 20.) The browser part will be somewhat more involved, > mostly as it deals with XSLT, but I don't think it will be terribly > difficult either. > > Sadly, I'm not sure when I'll get a chance to work on this. Hopefully > before year-end. Attached is a preliminary patch to add this support. The monodocer change is 66 lines, and generates output like the attached Environment.xml. monodocs2html has also been updated; Environment.html is the current output. I should stress that this is a work-in-progress; in particular, it should (but doesn't) "garbage-collect" the elements, such that if updated assembly 2.0, and a member has an 2.0 element AND the element has been REMOVED, the docs are not currently updated to remove this element. Similar things should be done to ONLY remove a member if e.g. there are no remaining elements (which would likely obsolete the -ignore_extra_docs parameter if done well). - Jon -------------- next part -------------- A non-text attachment was scrubbed... Name: assembly-versions.diff Type: text/x-patch Size: 3092 bytes Desc: not available Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071125/b710f81e/attachment-0002.bin -------------- next part -------------- A non-text attachment was scrubbed... Name: Environment.xml Type: application/xml Size: 1222 bytes Desc: not available Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071125/b710f81e/attachment-0001.rdf -------------- next part -------------- A non-text attachment was scrubbed... Name: Environment.html Type: application/x-mozilla-bookmarks Size: 4488 bytes Desc: not available Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071125/b710f81e/attachment-0003.bin From mario.sopena at gmail.com Fri Nov 30 06:26:36 2007 From: mario.sopena at gmail.com (Mario Sopena Novales) Date: Fri, 30 Nov 2007 12:26:36 +0100 Subject: [Mono-docs-list] Documenting class libraries In-Reply-To: <556fbd1e0710060943r1a6f8be7ke2b0b3ac5ce64917@mail.gmail.com> References: <556fbd1e0710060943r1a6f8be7ke2b0b3ac5ce64917@mail.gmail.com> Message-ID: Hi Temi, sadly the documentation browser does not run in windows anymore. We are hoping it will work in a future reselease also in windows. Mario On 06/10/2007, Temi Varghese wrote: > Hi > > I am interested in documenting class libraries. Could someone suggest me how > to do in Windows XP? The site says i need GTK# Documentation Browser, but i > am not able to download it ( Mono 1.2.5.1_0 Setup) from the location > specified. However, i downloaded SDK and Runtime. Is this all that is > needed? If so, how do i carry forward from here. > > Thanks > Temi > > _______________________________________________ > Mono-docs-list maillist - Mono-docs-list at lists.ximian.com > http://lists.ximian.com/mailman/listinfo/mono-docs-list > > From mario.sopena at gmail.com Fri Nov 30 06:47:24 2007 From: mario.sopena at gmail.com (Mario Sopena Novales) Date: Fri, 30 Nov 2007 12:47:24 +0100 Subject: [Mono-docs-list] Proposing a new documentation subsystem In-Reply-To: <1196000927.30453.15.camel@lina.magi.jprl.com> References: <1195896955.4040.33.camel@pi1536.local> <474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local> <1195932307.4588.43.camel@lina.magi.jprl.com> <1195995363.4777.38.camel@pi1536.local> <1196000927.30453.15.camel@lina.magi.jprl.com> Message-ID: Hi, On 25/11/2007, Jonathan Pryor wrote: > On Sun, 2007-11-25 at 13:56 +0100, Valentin Sawadski wrote: > > On Sat, 2007-11-24 at 14:25 -0500, Jonathan Pryor wrote: > > > On Sat, 2007-11-24 at 16:16 +0100, Valentin Sawadski wrote: > > > > Furthermore, monodoc *already* supports 3rd party assemblies -- this is > > > how Gtk# and Mono.Fuse documentation, among other assemblies, is > > > integrated into monodoc. > > > > I know that monodoc already supports 3rd party assemblies but I was > > thinking of measures that would enable 3rd party developers also to > > benefit from the documentation contribution. > > > > Which means some that the documentation might contain some kind of url > > where contributions can be sent to. Apart from the current mono-only > > contribution. > > This sounds easy enough -- extend the .source XML format to include a > URL to send edits to. Then the problem "merely" becomes one of > documenting the transport format/protocol so that others can write > servers to integrate with monodoc. I believe the current protocol is > SOAP based, so that may need to change.... > > > Another point of which I have been thinking would be to add 3rd party > > documentation without having to rebuild the browser and all the sources. > > That's already possible. Just add your (.source, .tree, .zip) set of > files to your $lib/monodoc/sources directory, and restart monodoc. > You're done. Again, see how Gtk# and Mono.Fuse do things. > > > Someway that users only have to open http://3rdparty.com/docs in the > > documentation browser and the browser downloads all the documentation > > and integrates them into the database backend. > > This is a slightly different problem. It should also be solvable by > having the concept of a "local" sources directory in addition to the > system sources directory, e.g. ~/.local/share/monodoc/sources/, nd have > the local directory read before the system directory. Again, solvable > (though I don't know how difficult this would be). I spoke with Lluis Sanchez about using Mono.Addins to extend the documentation system and it seems a good approach because we will get all the subsytem for documentation updates and managment (both for providers and for doc sources) for free. This will enable downloading new docs or providers without updating the whole monodoc system. We can also get rid of the several xml files needed to finally reach the documentation files and free monodoc subsytem of some managment code. Once I have something workable I will post here for further discussion. Mario