Re: [Mono-docs-list] mdoc: Introduction and RFC
Hey, Jon. Why not just merge all of the tools into a mdoc.exe (with the new options parsing library to boot), rather than wrapping them all with a script? But otherwise I think it's a good idea. - `mdoc update' has *far* fewer options than monodocer, mostly because I can't see the need for some monodocer options such as -ignore_extra_docs (it should die now), -pretty (when don't you want nicely formatted XML?), -name, -since, etc. I think I added -pretty because reformatting XML causes problems with version control. And I don't even recall what -name does. Josh ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] monodoc Licensing
Jonathan Pryor wrote: Joshua et al, You wrote and contributed to the monodoc module many related utilities, such as monodocer, monodocs2html, etc., in addition to monodoc/engine and related documentation providers. The monodoc module currently claims to be under the GPL, as does `monodocer --version` and monodocs2html. How would you feel about relicensing these contributions under MIT/X11? No major reason, aside from an eventual simplification of Mono's licensing policy from GPL/LGPL/MIT-X11 to LGPL/MIT-X11, and I don't see much reason to prevent non-GPL-compliant reuse of these libraries and apps... Hey, Jon. I'm fine with anything, and simplification is my middle name (or, at least, the point of my domain name). You can consider any of my contributions to monodoc in the public domain. Best, -- - 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) ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Proposing a new documentation subsystem
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
Re: [Mono-docs-list] Mono documentation to be read offline ???
Jan Christensen wrote: Does there exist any mono documentation that could be read offline (PDF-files or HTML-files) If this exists, where can I get it There wasn't, then there was, and then there wasn't again. Now there is. See: http://razor.occams.info/code/monodoc/ -- - 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) ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Updating mdvalidator
(Note my new email address, btw.) Jonathan Pryor wrote: Currently mdvalidator doesn't like the documentation for generic types/members, as the XSD that mdvalidator uses hasn't been updated for the new XML tags like typeparam/. This is to be expected. However, some non-ECMA tags were added to the output of monodocer, in particular the /Type/TypeParameters, /Type/TypeParameters/TypeParameter, and /Type/Base/BaseTypeArguments elements added in October 9. I think we'll need to add /Type/Base/BaseTypeArguments to the XSD to permit validation, but do we need the TypeParameters/ element? This seems to just duplicate the information already within /Type/Docs/typeparam. Is this correct? Would it be possible to remove TypeParameters/ and instead use typeparam/ typeparam duplicates TypeParameters in just the same way param duplicates Parameter. It happens to be particularly useful when (type-)parameter names change: It's trivial for monodocer to update the (Type)Parameter nodes (by deleting and inserting new ones, for instance), but updating (type)param nodes is not possible because you don't always know which of the old parameters corresponds to which of the new parameters. The approach taken has been to not touch param nodes, but to update Parameter nodes. For example, you had: Parameter Name=X/ param name=xThis is the important parameter./param And then you change the method from having an X parameter to having Y and Z parameters. On the next monodocer run, what do you do with the existing param node? You shouldn't delete it because you don't want to delete user-written docs. Probably you leave it alone until the doc writer can resolve what happened: Parameter Name=Y/ Parameter Name=Z/ param name=xThis is the important parameter./param param name=y.../param param name=z.../param Obviously that's not the only approach one could take (and maybe not the best), but that's what's happening (iirc). Also, it has been my feeling that the order of nodes in the Docs section should not be relied on for anything (although that may not be what's happening everywhere), and so you would need a separate list of type parameters to make sure you have the right order somewhere. -- - Joshua Tauberer http://razor.occams.info Strike up the klezmer and start acting like a man. You're about to have a truth-mitzvah. -- The Colbert Report ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] Monodocer since/ support
Jonathan Pryor wrote: I'm still not entirely sure what your entire proposal is. Is it to have two elements, //Member/Version and //Member/Docs/since, the former being automatically inserted while the latter is controlled by the user? To answer this out of order and up front -- yes. On Fri, 2006-10-13 at 08:38 -0400, Joshua Tauberer wrote: Consider Gtk#, in which members were introduced in versions 2.4, 2.6, 2.8, 2.10... The /Type/AssemblyInfo/AssemblyVersion section of the XML documentation holds only *one* version, the current version, so I'm not sure how best to represent the myriad versions a member can come from that doesn't, to some extent, rely upon some arbitrary string (as since/@version uses). We don't use Type/../AssemblyVersion for anything, so let's assume we replace it with a new node (maybe at the same location) that has the assembly version the type was introduced in, and every Member also gets its own such node. The problem I have with this is that it's potentially wrong. Just to formalize the problem you point out, the version will be wrong just when a type/member was added in a previous/now-outdated version that was not yet monodocer'ed. So if someone is writing documentation for an assembly that has already had several releases (i.e. they're not writing docs concurrently with the code), or if they accidentally forget to modify the assembly version before running monodocer, or any number of other random mishaps which are likely to happen, the version information for the inserted member *will* be wrong. Those same problems happen with the --since method, and in both cases (metadata vs --since) you end up with wrong stuff that is non-trivial to correct. (Not impossible or even difficult if you still have an older version of the assembly around.) So I agree that version metadata has a sort of less-reliable quality that the rest of the metadata, but I don't see it as a compelling reason to abandon the information completely. Which may not be entirely problematic, but if it can be wrong we'll have to expect the user to potentially update it We can have an option in monodocer so the user can provide an older assembly to back-version items: both back-versioning the metadata as well as correcting --since tags that should have had previous versions. To mutilate an idea you propose later, perhaps we could add an attribute to the since/ element which contains the current assembly version, e.g. since version=Gtk# 2.4 assembly-version=2.4.0.0 / though I'm not sure this actually buys anything, for the reasons listed above. You don't mean current (as in what's put in /Type/Assembly/AssemblyVersion) but the version that corresponds with the version attribute, I think? Are you suggesting it be automatically inserted or user-written? Hence my problem, I don't see any way for the version information to ever be considered reliable... I didn't really mean reliable as in something like assuredly correct. I was going for something like the node will assuredly contain a valid A.B.C.D version string which is no earlier than the version in which the type/member appeared, and provided the user runs monodocer on every released version, then it will actually *be* that version. That's close enough for me. The information is no less reliable than the since/ tag, and in just the same cases where the since tag is reliable (i.e. correct), the metadata version is not only reliable (i.e. correct) but also machine-readable. I'm still not entirely sure what your entire proposal is. Is it to have two elements, //Member/Version and //Member/Docs/since, the former being automatically inserted while the latter is controlled by the user? If so, this still doesn't permit easy change across all files Ok. Nevermind. Updating metadata is slightly easier, but not so much that it makes a difference. (In order to back-version a type/member to a version that you forgot to run monodocer on, you only need the old assembly to update the metadata. Any type/member present in the assembly and the docs that has a future version set just gets reduced to the old version number. To update a since/ tag, you need the old and prior-to-that assemblies at the same time so you can figure out which members were added in just that version.) So here's my scenario. I have a Makefile that runs monodocer whenever I build my deployment package. So, monodocer gets run on every released version, which means that the version metadata will be kept up-to-date. Further, in my HTML docs I'm happy to list members as being since some A.B.C.D version. In this case, I can leave version tracking entirely to monodocer. If I use --since, I have to remember to update it after each release, and further I would be specifying the exact same thing that monodocer could be figuring out for itself. -- - Joshua Tauberer http://razor.occams.info Strike up the klezmer and start acting like a man. You're
Re: [Mono-docs-list] Monodocer since/ support
Jonathan Pryor wrote: (2) Command-line argument approach: add a ``--since name+version=tag'' argument, and if an assembly matching name+version is encountered, create a since/ element for any *added* types and members. It might be useful to decouple tracking which things were added in which assembly version from the since/ tag with text used for display purposes. I played with adding versioning support a while back and what I came up with was something like what Jon had, but instead of inserting since/ tags, it used the AssemblyVersion tags that already existed for types (and I guess I added them for members) to track the first version in which a type/member is seen. When a type/member is stubbed for the first time, or for legacy docs with members without an AssemblyVersion tag, it inserts the AssemblyVersion. But on future updates, it no longer modifies that information. That leaves the AssemblyVersion with the first version in which the type/member appeared. This also solves the annoying issue of every type XML file changing when the assembly version changes, because that tag doesn't get updated anymore. It doesn't work for back-versioning existing docs, like tagging things in the corlib with 1.0.*.*, since it will only insert the current assembly version on newly added types and all (legacy) members. But updating the corlib is another issue entirely because we can't load the 1.0 corlib in monodocer anymore anyway. (We can have a special system to back-version.) Then the since/ tag is left to display whatever you want. But, since monodocer is already tracking the actual assembly version things were introduced in, it's possible to automatically insert documentation here with any format -- i.e. version 2.1.2.0 becomes The 2.1 release of MyLib#.. We can have a command line option that maps assembly versions to strings for since tags, overriding a default of just using the assembly version unchanged: --since 2.1.*.*=The 2.1 release. (actually I would recommend not using asterisks on the command line, of course, but that shows what I meant) -- - Joshua Tauberer http://razor.occams.info Strike up the klezmer and start acting like a man. You're about to have a truth-mitzvah. -- The Colbert Report ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] More monodocer
A fix is to change line 699: -WriteElementText(root, Base/BaseTypeName, basetypename); +WriteElementText(basenode, BaseTypeName, basetypename); However, I'm not sure *why* this would be necessary, There was a bug in WriteElement. It didn't traverse down the nodes properly if a node in the path (in this case Base) already existed. Another problem is that the position of /Type/TypeParameters has changed from DocTest/en.expected -- it used to be after the /Type/Docs node, and now it's before the /Type/Base node. The *real* problem is that the position of /Type/TypeParameters changes between the initial documentation generation and on update. Right, I just fixed it so it stays at the top. Everything is committed and *should* work now. I hope... -- - Joshua Tauberer http://razor.occams.info Strike up the klezmer and start acting like a man. You're about to have a truth-mitzvah. -- The Colbert Report ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] More monodocer
Jonathan Pryor wrote:
You might want to wrap the (iInherited from... and ) within
xsl:text/ so that extra whitespace isn't introduced in the output
document.
Good point.
Also, you might want to modify DocTest.cs so that GenericBase`1 has some
members, so that we can see the effect of this option in the regression
tests.
Right, I thought of that after sending the patch. That also helped
explain the other problem you found:
Your changes broke something: {T} should continue to be {`1} within the
href=... text.
I needed to add type name escaping in two places.
Why'd you get rid of the # from the href here and in other spots? I
don't see any changes in GetLinkId() that would remove the need for
this.
What happens now is that in the template GetInheritedMembers, it
recursively assembles some content like this:
Members Name=Object FullName=System.Object
Member ...
/Member
/Members
Members Name=MyClass FullName=MyNs.MyClass
Member ...
/Member
/Members
Then when listing a member, rather than using ../.. to get to the type
(which is no longer in the tree of this content), it uses
parent::Members to go up a level to get the declaring type of the
member. Further, when assembling the link, it needs to put a file path
before the #, which is why the # moved from the a nodes up earlier.
--
- Joshua Tauberer
http://razor.occams.info
Strike up the klezmer and start acting like a man. You're
about to have a truth-mitzvah. -- The Colbert Report
___
Mono-docs-list maillist - Mono-docs-list@lists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] Generics Support for monodoc/tools
Jonathan Pryor wrote: At the URL below is a patch to monodoc/tools to add support for Generics to monodocer.exe and monodocs2html.exe. (Next stop: adding support for Generics to the documentation browser.) Hey, Comments for the monodocer part of the patch: After running it on some of my docs, I get these unexpected changes: -ReturnTypeSemWeb.N3Writer+Formats/ReturnType +ReturnTypeSemWeb.N3Writer.Formats/ReturnType (I'm not necessarily opposed to such a change, but I thought that was part of what was undone about + vs ..) - Parameter Name=prefix Type=System.Stringamp; RefType=out / + Parameter Name=prefix Type=System.Stringamp; RefType=out + Attributes + Attribute +AttributeNameSystem.Runtime.InteropServices.Out/AttributeName + /Attribute + /Attributes + /Parameter Is out exposed differently through reflection in 2.0? I think we should suppress this attribute, since it duplicates RefType. Also (but this is related to the +/. thing), during an update the index.xml file was updated by adding entries like: Type Name=Sparql.QueryType File=Sparql+QueryType / but without removing the old entry with the + in the name. Lastly, the File attribute wasn't added to any existing entries in index.xml when doing a doc update. Looking forward to all the updates. -- - Joshua Tauberer http://razor.occams.info Strike up the klezmer and start acting like a man. You're about to have a truth-mitzvah. -- The Colbert Report ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] Generics Support for monodoc/tools
Hey, Jon.
Very nice.
I won't have a chance to look at the patch for a few days but I had two
comments:
The one breaking change to monodocer.exe is that '+' is no longer used
for nested types, but '.' is used instead. That is:
public class Outer { public class Inner {}}
generates the file Outer.Inner.xml, while as before it would generate
Outer+Inner.xml. This change is necessary for monodocs2html.exe, as
there is no way from a see cref=T:Namespace.Outer.Inner / reference
to tell which of those strings is the namespace, the outer class, and
the inner class (at least, no easy way that I can see), so removing the
'+' makes monodocs2html.exe easier to implement.
I don't see how that helps, since the full file path is
Namespace/Outer+Inner.xml --- which means it already needs to know which
period ends the namespace so it knows which directory has the file, and
if it knows that, then it knows the next period must be a nested class
period.
(It also is ugly-as-sin, containing joyfully recursive XSLT calls to
convert FooA,B.NestedC into Foo`2.Nested`1 constructs. Lots of
fun. Really. Stop looking at me like that!)
Fun, eh?
--
- Joshua Tauberer
http://razor.occams.info
Strike up the klezmer and start acting like a man. You're
about to have a truth-mitzvah. -- The Colbert Report
___
Mono-docs-list maillist - Mono-docs-list@lists.ximian.com
http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] monodocer System.ComponentModel patch
Greg Steffensen wrote: I've patched monodocer to optionally look for member attributes that are instances of System.ComponentModel.DescriptionAttribute, and use the descriptions found there for the contents of the summary element Hey, Thanks for resending it as a patch. So, what you have will use the DescriptionAttribute for members, but not for types. The attribute can be applied to types, but I don't know whether it's used that way in practice../? It would be good to put what you wrote in the MakeDocNode method (the main one), which is where the summary nodes are created anyway for both types and members. The problem is that MakeDocNode doesn't have a reference to the member/type being documented, so what you'd want to do is add a parameter of type ICustomAttributeProvider to that method (types and members all implement from that), and then fix up the callers to pass the thing down. Somehow it got a little more difficult. The problem with doing that is that (if/)when we eventually switch to Cecil instead of Reflection, the patch isn't going to reapply nicely to the Cecil version I un-committed, so the changes may have to be redone... -- - Joshua Tauberer http://taubz.for.net Unfortunately, we're having this discussion. It's too bad, because guess who listens to the discussion: the enemy. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Mono.Cecil dependency in monodocer
Miguel de Icaza wrote: Hello, Atsushi Eno wrote: I noticed that the latest monodocer depends on cecil (and the build is broken there). If we use it, I think -pkg:mono-cecil should be used in the makefile(.am). Yes. I was thinking some pending Cecil bugs would be fixed quickly, and I was waiting for that to finish up those changes. Turns out reading custom attributes from an assembly is trickier than I realized. Joshua mentioned today that he might want to backport to Reflection and use some 2.0 reflection APIs to get the attributes out. So, I've reverted all of my Cecil changes. This is a good opportunity to use Cecil, so if Cecil makes it into a release, I think we should go with it. That leaves two questions. The first is whether using gmcs will have any build ramifications? The 2.0 reflection API is the alternative in order to get custom attributes (and generics) documented properly. For anyone: If monodocer is compiled with gmcs, is it still able to load assemblies compiled against the 1.0 corlib? I don't have a grasp of how assembly versioning works in .NET... (Yeah, I could try it.) -- - Joshua Tauberer http://taubz.for.net Unfortunately, we're having this discussion. It's too bad, because guess who listens to the discussion: the enemy. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Mono.Cecil dependency in monodocer
Atsushi Eno wrote: I noticed that the latest monodocer depends on cecil (and the build is broken there). If we use it, I think -pkg:mono-cecil should be used in the makefile(.am). Yes. I was thinking some pending Cecil bugs would be fixed quickly, and I was waiting for that to finish up those changes. Turns out reading custom attributes from an assembly is trickier than I realized. -- - Joshua Tauberer http://taubz.for.net Unfortunately, we're having this discussion. It's too bad, because guess who listens to the discussion: the enemy. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] Re: [Mono-dev] [PATCH] Monodoc. Fix rendering of masteroverview for monodocer output
Mario Sopena wrote: Any comments before submitting? Looks good. Thanks for correcting for my laziness. :) Should be easy enough to load in the namespace summary files (namespacename.xml in the docs directory) and include it. Also, I don't think you need to email mono-devel-list with monodoc changes. Probably everyone interested is on the docs list. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] Re: [Mono-dev] Monodoc
Matthijs ter Woord wrote: Is there any special format needed? (IE, ecma xml docs etc) If so, could anyone point me to it? So the goal is to extend our XML format to handle generic classes, and that includes 1) how to include the generic part of a type/member signature in the metadata parts of the XML, and 2) how this affects see tags. (Maybe there are more things not coming to mind.) As for (1), I think we can do this however we want. Monodocer and the monodoc stylesheet would just need to be updated. For (2), we want to remain compatible with the inline documentation format Microsoft uses, for instance to be compatible with NDoc. So, what would be useful would be for someone to dig around and see if Microsoft has updated their /doc tag reference for generics. Updating monodocer means having it be compiled with gmcs so it can reflect to get generics. But, monodocer should really be changed to use Cecil (rather than reflection) first before doing this. Does anyone know how Cecil is doing? (The main reasons to not use reflection is that reflection doesn't give access to how attribute are constructed, so currently monodocer is making up something reasonable to display.) - Josh - Original Message - From: Miguel de Icaza [EMAIL PROTECTED] To: Matthijs ter Woord [EMAIL PROTECTED]; mono-docs-list@lists.ximian.com Cc: [EMAIL PROTECTED] Sent: Friday, September 30, 2005 4:20 AM Subject: Re: [Mono-dev] Monodoc Hello, When will monodoc be ready for .NET 2.0 classes? (ie, when will it also allow to document generics) We will have to wait for someone to contribute the necessary code to cope with this. I have not had much time to look into this issue. What needs to be done is: * Look at the new ECMA XML documentation from ECMA and evaluate how we could bring those changes into our documentation. * Someone would have to port the new docs nonetheless. * Someone would have to architect the changes to the monodoc engine to do so. The right place to discuss this is the mono-docs-list. That being said, if you can not wait to write some documentation, we have a *lot* of stuff in the 1.x profile that needs documentation. Considering that 2.x stuff wont be 100% supported for a while, maybe it would be best to contribute to the 1.x effort. ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] Re: [Mono-dev] Monodoc
Alexandre Miguel Pedro Gomes wrote: Monodoc would need a profile chooser or something like that to switch between 1.x and 2.0 profile, right? Any plans on those things? I imagine that we'll show the 2.0 docs (at some point) but new members/types will be tagged as being introduced in 2.0. That's a really long way off, though. Btw anyone knows why the C# specification appears without newlines? Where? Mostly it displays fine for me (on the web and in monodoc). I recall that there are tables somewhere in there that aren't shown right because the column separators are gone from the source XML files. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] patch for monodocer to update paramref
Atsushi Eno wrote: I could not find where (well, whether) monodocer updates parameter names when there are two or more parameters. Does the updating happen in such cases? No. If parameters were added or removed and if there are also name changes, it starts to get difficult matching up old and new names. There might be some corner cases where it's possible to update the names, but I didn't want to get into that mess. If it looks good, I'll commit this patch later. Yeah, looks good. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Monodoc not showing parameter names
Juanval wrote: Well, my problem is the fact that parameter names are not shown in Monodoc all the time. (snip) So, does anybody know why those names aren't shown? I don't remember why it was done that way, but my guess is that if parameter names were always shown, those lines would very often wrap, and that makes it a lot harder to read. You could submit a patch to make it an option. :) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] Add Gecko support
Hey, Mario. Normally I'd chime in with comments, but I haven't gotten gecko-sharp working yet on my box. Just from reading the patch it looks good, though. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] XSL patch for versioning
There's probably a one-liner that'll do the job (ancestor-or-self:*/Doc/since[position()=1] -- haven't tested it, it might pick out the wrong one), but the way you have it is clear. Do you edit the since tags manually? It would be nice to pick up the information either from attributes on types/members, or else by monodocer adding it when it adds members (subject to some command line args specifying the current version number). On an unrelated note, for anyone reading this far, does anyone mind if I get monodocer using Cecil instead of reflection? This should (eventually at least) let monodocer pick up security attributes as well as what exceptions are thrown (by disassembling methods). -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** Mike Kestner wrote: The attached patch causes members without since elements to use the parent type's since element. This is desirable behavior as otherwise every member of a new type has to carry a redundant since element. Based on my complete ignorance of XSL, it's likely there is a cleaner way to do this, but this patch seems to accomplish the desired behavior. I await the feedback of the XSL masters. Index: mono-ecma.xsl === --- mono-ecma.xsl (revision 45981) +++ mono-ecma.xsl (working copy) @@ -547,7 +547,14 @@ !-- summary -- - xsl:apply-templates select=Docs/since / + xsl:variable name=since select=Docs/since / + + xsl:if test=$since + xsl:apply-templates select=Docs/since / + /xsl:if + xsl:if test=not($since) + xsl:apply-templates select=/Type/Docs/since / + /xsl:if p xsl:apply-templates select=Docs/summary mode=notoppara/ ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] XSL patch for versioning
Mike Kestner wrote: dvp shouldn't depend on the Type/MemberSignature elements to find the nodes though, if that's the code you're referring to. Why not? It's not really guaranteed to have a certain form. It should be just for display to the user (although monodoc uses it anyway to determine modifiers on members). Things like spaces and semicolons could be changed in the future. You should use GetMember(Type type, XmlElement member) to get the MemberInfo for each member node in the xml, and then to add since nodes to that as needed. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] Re: PATCH: resubmit
Hey, The patch is ok. Feel free to commit (and thanks), but here are some pedantic comments: [Glade.Widget] TreeView PluginsTreeView; Don't need that anymore. - RootTree.UncompiledHelpSources.Add(args[i+1]); + RootTree.UncompiledHelpSources.Add(args[i+1]); Try to avoid those whitespace changes. + property name=label translatable=yeslt;span size=quot;largerquot;gt;lt;bgt;monodoc:lt;/bgt; The Mono Documentation Library viewerlt;/spangt;/property Should be a capital 'v' in viewer, if the rest is going to be capitalized. Say, I don't suppose you want to work on indexing/searching next? -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Re: [Mono-devel-list] patch for bug#57748
Heh, okay, okay, here we go... Rafael Ferreira wrote: Would you like to remove the plugins tab completely or just have a label instead of the list? My preference would be to remove it alltogether. I changed the interface so the docbrowser version shows up in the about tab as well, check it out and tell me what you think: Nice. Oops, I forgot I did that. That line is giving me some compilation problems: You just need to 'make install' the latest monodoc.dll from /monodoc/browser. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Monodocer for multiple assemblies
Mike Kestner wrote: Attached is a first pass attempt at adding multiple assembly support to monodocer. I need support for this in order to transition Gtk# to using monodocer instead of the mkfork of the old updater that we've been nursing along in gtk-sharp/doc/updater. Excellent. - the index document layout has to change to support multiple assemblies. The patch supports stubbing for an assembliesassemblyattrs... layout, but I'm unsure if this is the way to go. I think this index file is only used for the docs2html translation, so I need input on the desired layout. It's also used by monodoc --edit so monodoc doesn't have to scan the directory layout. I think what you've done is fine. There's no need to separate out the type listing by assembly. - The index assembly attr updating is broken. I decided not to waste time on this until I had a better feeling for how they are used and what they should look like. Yeah, I guess I never did that since it's not used anywhere. - DoUpdateNamespace just looks in the first assembly supplied. I'm uncertain what the typical use case is for this so it's unclear whether we should support multiple assembly namespace updating. I think we can get rid of that feature entirely. (Does anyone on the list use it?) I'm a little concerned about the volume of information that monodocer puts on the console. It would be nice if Updating Foo was only written to the Console if Foo has changes. Yeah, sure. I didn't do that because it was hard to figure out when a file was changing, from the way the xml is updated. Also, when members are to be deleted but --delete is not specified, would it be okay to add a Deprecated attr like the old updater used to do. Oh, I didn't know the old updater did that. I don't really think it's useful to add a Deprecated attribute -- the output of monodocer is a good indication of what needs fixing. But that's just me. Patch looks good to me, BTW. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Docbrowser Editor Bugs
Jonathan Pryor wrote: 1. I can't edit namespace summaries (this also exists when not using --edit as well). This was never working. I'm not sure how to hack that in, either. 2. When using `monodoc --edit DIR`, monodoc dies whenever I try to edit a non-namespace node. Fixed in SVN. Both /monodoc/browser and /mono-tools/docbrowser needed changes. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] MonkeyGuide and Monodoc futures.
Miguel de Icaza wrote: Am wondering if you could assist us with the proper XSLT glue to transform our current XHTML documentation into something that MediaWiki would consume. Yeah sure, I can take care of that in a few days. I might have had time sooner, except rather than doing work due tomorrow I've just been hacking Subversion integration for MonoDevelop for fun. Mono is a real problem for me because it makes it too easy to create nifty things, and that distracts me from doing actually important things... -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] MonkeyGuide and Monodoc futures.
Miguel de Icaza wrote: The problem is that nobody contributes to the Monkeyguide. The sources have been on SVN forever, but it barely gets noticed. Well, till recently the Monkeyguide was following a moving target, which I'm sure made it more difficult to work on then than it would be now. So what do you have in mind? We already have the data in a consumable format (XHTML); The question is how do we keep it updated, and useful. I'm not so convinced XHTML is the best format to be writing it in. I'm looking at some of the pages now, and things like TOCs for subsections in a page, copyright lines at the bottom of pages, awkward uses of meta tags to track authorship, etc... These can be abstracted more to make maintaining the pages easier. Maybe it's just that I don't like Wikis all that much. :) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] [PATCH] generator/updater.cs - questions
Rodolfo Campero wrote: If I use monodocer, will I be able to edit the XML files with monodoc and then merge the changes as explained in the tutorial? Monodocer does the exact same thing that updater does, only it does it correctly. So yes. Everything else in that tutorial looks good, except for this improvement: If you're not editing docs that come installed with Monodoc, or if you remove those nodes from the monodoc.xml file first, you can edit XML files directly, without having to assemble the docs first and merge the changes file after, using: monodoc --local-edit /full/path/to/doc/root -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - Mono-docs-list@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Tab Navigation (Mozilla integration)
Todd Berman wrote: GeckoSharp lacks two critical things that Gtk.HTML has. First, it has no support for hooking into protocols to allow images to be loaded directly from resource files, which the Mono handbook needs (last I saw). It does have these hooks. Oh, in that case, how do I do that? (I even read on Mozilla's gtkmozembed page that it wasn't supported, which is why I was so sure.) I believe it kind of has these, but why are they important, in theory the gtkmozembed widget should just handle copy/paste if we remove our keybindings for it. Or if we directly pass it a ctrl-c or ctrl-a key event is *should* handle it properly. Well, ok. If you can help me get the protocol hooks going, I can finish having Monodoc pick up Mozilla if it's available and we can work around the other issues. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Updating Gtk# docs
Mike Kestner wrote: Until monodocer is installed by a package lower on the dependency chain than Gtk#, I would prefer it not be used to update the Gtk# docs. Well, right now it's not installed anywhere at all. Getting it is pretty trivial, though. svn co ...; make, and that's it. I am using a hacked version of the monodoc updater that is built in gtk-sharp/doc/updater currently. Right. I wrote monodocer specifically to be a drop-in replacement for the old updater. I'm not sure what you've changed, but the old one suffered from a wide range of problems, including generating bad (stringified) signatures, not updating metadata when it changes, not doing attributes well, etc. etc. This update tool seems like a good candidate to be moved. It would be nice to have a place for documentation tools, which would make sense in the monodoc area, but I don't have strong feelings about it. It generates a 2 megabyte diff of changes The word ouch comes to mind. Yeah, but it's not making up changes for no good reason. Unless the Monodoc XML format changes, the Gtk# docs are in need of much updating. So the docs currently list a bunch of inherited interfaces that shouldn't be explicitly shown in the docs? Yes. Well, it depends on what the meaning of shouldn't is. It's not incorrect to list them if the type implements it (via its base type), but it's really just redundant clutter. updating signatures, and changing 'returns' nodes to 'value' nodes for properties. Updating signatures how? Were the old sigs incorrectly generated by the old updater? In what manner? (I mean the TypeSignature Language=C# and MemberSignature... nodes.) This might have been introduced into the main Mono docs by an earlier monodocer, so I'm not sure if this applies to Gtk#: structs were listed as sealed, interfaces were listed as abstract, there were bad abstract+virtual combinations, and more. (And this all shows up in Monodoc.) In any event, whatever signature strings are being generated now, they don't match exactly with what is present in the files. For the return/value nodes: monodocer simply changes the element's name. If these are predictable transformations, can the old docs be moved to the new signatures? The 'returns' to 'value' transformation is one that seems easy enough to preserve existing docs, does the tool do so? Yeah, nothing is destroyed by any of this. Unless names of members or the parameters to methods/indexers have changed, everything is fine. If those things have changed, Monodocer may add new documentation sections for what it thinks are new members, but it won't delete anything that has user-written documentation (unless the --delete option is given). I want to have correct docs in Gtk#, but I would really like to avoid weeks of effort moving deprecated docs around manually. It's not quite that bad. :) If I can adapt Monodocer to make it easier to get the Gtk# docs updated faster, I can do that. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Tab Navigation (Mozilla integration)
John Luke wrote: I'm not a doctor but you should be able to use either RenderData or OpenStream apis to send whatever you want to the control (barring bugs in that part of the API). The question is if we send the control: img src=monodoc:monohb/path/image.png/ Can we intercept Mozilla's attempt to use the monodoc: protocol so we can give the image data ourselves? -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Tab Navigation (Mozilla integration)
Todd Berman wrote:
I believe there is a signal called OpenUri or OpenUrl or something that
can be used for that.
One would think so, but then again... Here's the relevant stuff:
class WebControl {
public event Gecko.OpenUriHandler OpenUri;
}
public delegate void OpenUriHandler (object o, Gecko.OpenUriArgs args)
public class OpenUriArgs {
public object [] Args { get; set; }
public string AURI { get; }
public object RetVal { get; set; }
}
If you can see how to go from there to sending the control data...
(Other related events are just as opaque.)
--
- Joshua Tauberer
http://taubz.for.net
** Nothing Unreal Exists **
___
Mono-docs-list maillist - [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Tab Navigation
Hi, Mario. I'm finally getting around to looking at the tab navigation patch. It was a good idea. First some comments about using it. When I open a new tab it shows a blank page. It should either show the Mono Documentation root page, or it should show the same page that is currently being shown. Maybe it's just me, but the height of the tabs themselves is really large -- about two lines high, but only one line of text will be displayed in them. Also, the titles of the tabs is problematic. When I look at the members listing for a type, the tab title is Members which makes it impossible to distinguish it from other tabs showing the members of other types. (Okay, I even suggested how to get the titles, I know.) You may need to grab the parent node's text in the tree too. You'll have to play around with it to see what works best. The New Tab tool should be on the toolbar too. You can't be editing in more than one tab at a time. When you try to edit in a second tab, you get a blank area. You can go two routes: make editing work in multiple tabs, or just really limit it to one tab. Limiting it to one tab is better for now, and if you do this you should be able to keep more of the code related to editing unchanged. (Maybe better yet, when the user clicks an [edit] link, put the editing widgets into another tab, so you can switch between editing something and the page you were editing. Otherwise, you could go the easy route and just hide the tabs entirely when the user is in editing mode.) I haven't quite figured out how you have the back and forward buttons tied nicely with the active tab, but good work there. Now for comments about the code itself. Some of this stuff gets picky. You made a lot of things 'internal', but they should just be 'public'. Browser.exe isn't meant to be referenced by another assembly, so there's no real distinction, so public is easier to follow (and everything else seems to be either public or private). Try to keep widgets private. There were a few lines in the diff that were only different by a trailing space. Try to remove these before sending the diff so there aren't lines marked as different that didn't really change. In browser.glade, it looks like a lot of things were unnecessarily changed. Do we need requires lib=gnome/ and the new property.../ nodes at the top and elsewhere? (I don't know what they do.) Also lots of id attributes changed. It's easier to follow diffs without changes like this. Can you revert the file and make only the changes you need by hand? And, as I said above, it would be good to keep more of the editing code unchanged, especially if the user can still only edit one thing at a time. So... good luck! -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** Mario Sopena Novales wrote: Hallo guys! I've posted a week or so saying I was working on displaying multiples tabs on a page (thanks Joshua). In the way of getting it I have found something in the code of monodoc I dislike. The actual implementation of the History. There is an object History that is supposed to managed the history (any magic here), but for me makes no sense that this object shall manage too the code of the buttons back and forward. Shouldn't the events of the buttons been managed by the browser itself? For me makes sense that the History was an object that manages only history data (a real abstraction of a history) and not GUI data too. Besides that, what is suppose that the class PageVisit should do? It is only for letting the object History to call the browser to actualize himself? Isn't this a mess or I'm missing something? If the implementation of the History were managing only history data, and the browser, GUI data, I think the browser could actualize himself. What do you think? I'm missing the point? Ok, at this point, somebody is thinking what the h... smokes this guy? Well, I, actually, don't smoke, but all of this comes from my implementation of tabs. I want to make a Tab object (and a list of them) that manages all of the data related to a tab (his history and a reference to the areas for rendering the content by the moment). With the actual implementation of history I'm not pretty sure of how to do that. That's all. If anyone has arrived here, please post an answer (or send me money, it's up to you). Bye! Mario Sopena ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] A question on Tabs
Mario Sopena Novales wrote: this is my first post. I've started struggling with the source of Monodoc trying to get a functional tab navigation. If I got a decent solution I will post here. But, for the moment I just have a question. What kind of tab navigation do you mean? You mean displaying multiple tabs of pages? You should grab the titles from the tree node that corresponds to the page being viewed. When a page is loaded, it should be returning the corresponding node in some out parameter (I forget where exactly). Hope that helps. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Rendering example/ blocks
Jonathan Pryor wrote: Attached is a patch to monodoc to implement this default escaping behavior. It also has a fix to the XML colorizer so that the output isn't completely garbled. OK to commet? Looks good to me. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Rendering example/ blocks
2. Modify Colorizer.Colorize so that it always escapes XML entities, even for unrecognized languages. This seems reasonable and straightforward to me, but could possibly prevent some functionality (such as directly emitting HTML into example, such as custom font/s, span/s, etc.). This is my preference. example blocks should be able to be rendered with or without the colorizer so that we can still get offline HTML output without the help of extension functions. But, there is too much escaping going on. The example blocks in the files should be considered as having raw code, not HTML. The renderer should take care of making sure that lt;'s come through as less than signs in the final output. So, you shouldn't double-esacpe. I've done this in a local copy, but I'm unable to test it. (For reasons I can't fathom, mono prefers loading the monodoc.dll that's in the GAC than the newer one in the current directory. I've got to figure out how to disable this behavior...) I usually: export MONO_PATH=. and then mono browser.exe. As a side note, the xml colorizer seems borked within monodoc. It doesn't color the text, but inserts the colors inline with the text; for example, this: The one extension function I didn't write... :) Maybe it's a bug in XSLT or streams or something. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Man page support and Linking
Jonathan Pryor wrote: 1. Does monodoc support man pages yet? If not, when will it? It would only work in Unix, then. Are the man pages licensed in such a way as to allow their embedding in Monodoc? That'd be easier, and it would look nicer. The problem with having a man page provider is that, I think, every page needs to correspond to a page in the table of contents, and so that would require either having a list of man pages that Monodoc should display in the TOC, or it would need to display all man pages in the TOC. 2. Is it/will it be possible to link between the different sets of providers? Why doesn't it work now? IIRC, the ECMA docs link between the docs with a href=T:.../... If I ever get my virtual file system browser finished, this would all be working already... (it's never going to be finished) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] MonoDoc item schema
Francisco T. Martinez wrote: I did not create MS HTML Help 1.1 *.chm files because the resulting HTML output did not have traditional htmlheadtitle/title/headbody/body/html Take a look at http://taubz.for.net/code/monodocs/corlib/en/html That's how monodocs2html outputs things currently. It has the usual HTML structure. Microsoft chose XML documents for their table of contents and index files. So I not only need to generate HTML output from the MonoDoc XML pages but must generate these supporting files as well. Monodocer creates an index.xml file in the root directory of documentation which monodocs2html uses to create the TOC (class listing) pages. (Run monodocer with the --update command to generate the file for existing docs, since there aren't any index.xml files checked-in in CVS.) You could transform these index files to TOCs and indexes using stylesheets. (See the stylesheets in monodoc/tools.) Can you point me where to find the ECMA DTD? I don't know if there was one (I think someone may have created an unofficial one at some point), but our docs have had a bunch of format changes since the original format, so I wouldn't follow an ECMA DTD. Once more let me congratulate you on the work you have done on monodoc/tools. Thanks. :) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] MonoDoc item schema
Paco, No schema exists. It wouldn't be too hard to create based on my description of the files at: http://www.nullenvoid.com/mono/wiki/index.php/ECMAStyleDocumentation But, how much more control do you need over the HTML generation? Monodocs2html already lets you use a custom page template, and it would be fairly easy to allow other methods of customization, like changing the way links are handled. It would be great if the existing tools could be extended to do what you need. Creating some nice XSLTs to convert monodoc docs to other formats would be good as well, though no one has had the patience for it yet. :) I keep saying it must not be difficult, but since no one's been able to finish it yet, maybe I underestimated the problem. - Josh - Original Message - From: Francisco T. Martinez [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Monday, August 16, 2004 9:44 AM Subject: [Mono-docs-list] MonoDoc item schema Hello: Does any one know if there is an XSD file that describes the complete schema that may be used for MonoDoc documents (overviews, specific item pages, etc.) I am building MS Help Files for Win32 and plan to do a lot of XSLT to generate HTML versions of the existing XML formats. I have taken a look at the great work that was done in monodoc/tools but may need much more finer degree of control over the HTML generation process. Of course if no one knows about the existence of such schema, I may create my own and may publish or make accessible my documentation in the documentation format generated by XML Spy (see the following link of a sample based on the project file format used by MonoDevelop: http://www.mfconsulting.com/product/prj2make-sharp/prjxDoc/index.html ) Paco ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] MonoDoc item schema
Paco, No schema exists. It wouldn't be too hard to create based on my description of the files at: http://www.nullenvoid.com/mono/wiki/index.php/ECMAStyleDocumentation But, how much more control do you need over the HTML generation? Monodocs2html already lets you use a custom page template, and it would be fairly easy to allow other methods of customization, like changing the way links are handled. It would be great if the existing tools could be extended to do what you need. Creating some nice XSLTs to convert monodoc docs to other formats would be good as well, though no one has had the patience for it yet. :) I keep saying it must not be difficult, but since no one's been able to finish it yet, maybe I underestimated the problem. Let me know if I can help in any of the above ways. - Josh - Original Message - From: Francisco T. Martinez [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Monday, August 16, 2004 9:44 AM Subject: [Mono-docs-list] MonoDoc item schema Hello: Does any one know if there is an XSD file that describes the complete schema that may be used for MonoDoc documents (overviews, specific item pages, etc.) I am building MS Help Files for Win32 and plan to do a lot of XSLT to generate HTML versions of the existing XML formats. I have taken a look at the great work that was done in monodoc/tools but may need much more finer degree of control over the HTML generation process. Of course if no one knows about the existence of such schema, I may create my own and may publish or make accessible my documentation in the documentation format generated by XML Spy (see the following link of a sample based on the project file format used by MonoDevelop: http://www.mfconsulting.com/product/prj2make-sharp/prjxDoc/index.html ) Paco ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] monodoc split
Miguel de Icaza wrote: It leads me to another question though: does monodoc have a maintainer of sorts? There are a few features and bugs that would be nice to address, and I hope no one will be offended if I say that the code could use a little bit of prettifying. I am the maintainer for the code; Feel free to send patches to prettify. I have some half-finished patches to Monodoc that I want to get checked in at some point... Please don't prettify the EcmaHelpSourceProvider code since that'll cause conflicts with my changes. :) I can also help out with reviewing Monodoc patches. I'm not making many Mono contributions these days, but I'm still following the maillist. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] MonoDoc translation
Giovanni Ferron wrote: Hi i'm here again with a simple question, I would like to translate the monodoc documentation in italian, but i didn't find a way to do this. I only find a web page (http://www.go-mono.com/monodoc-xml.html) where says that i can use the lang attribute in this way doc lang=ISO-code, it's right? or there's another way? That page must be extremely old. It doesn't reflect the structure of the XML documents that are used now. The Monodoc documentation is huge, to say the least. Getting the documentation in English is a huge project (and very unfinished). Translating it is a huge project too. Maybe on the order of a hundred hours of work. See: http://cvs.hispalinux.es/cgi-bin/cvsweb/monodoc/class/?cvsroot=mono The documentation is in CVS at /monodoc/class. Each assembly documented has a directory there. Within those directories is directory for each language. Currently there's only en. Within that, there is the real documentation. Each namespace has a directory. In those, each type has a file. So, you will want to build a similar structure in a directory for Italian (what's the ISO code for Italian?). There's probably a flag in the assembler program (in monodoc/browser) that selects English for compiling the docs. I don't remember. I'd suggest you copy the type files one by one from the en directory to the Italian directory as you translate them so you can keep track of what's been documented. It could turn into a big mess very quickly. Good luck... -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] HTML docs
The script genbasedocs.sh is what you'll need (in the same directory). It generates the index.xml files. But, I was working on it last night and made some nice enhancements. When I commit the updates tonight, I'll post a brief howto to the list. - Josh - Original Message - From: Mike Kestner [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Tuesday, May 18, 2004 2:16 PM Subject: [Mono-docs-list] HTML docs Hello docsters, I'm looking for info on the state of the art in HTML documentation production from monodoc source docs. I've scanned the monodoc cvs module and found monodoc/tools/genhtml.sh, but it seems to require a mysterious index.xml file that is undocumented and doesn't seem to be part of the current doc structure for either Gtk# or the class docs. So, are there tools to produce HTML docs from either monodoc source xml or assembled monodoc .tree files? -- Mike Kestner [EMAIL PROTECTED] ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] HTML docs
Okay, my changes are committed, but I don't have time to write a howto right now. I updated the corlib docs that I posted last time: http://taubz.for.net/code/monodocs/mono-docs-corlib.tgz and http://taubz.for.net/code/monodocs/corlib/en/html to browse it online. genbasedocs.sh now works pretty well, but it takes forever and is only running on the corlib docs. monodocs2html.exe is the real program, which is now working very well. That's how you can generate html docs for arbitrary assemblies. It does need this mysterious index.xml file :), which for now can be created by using the stub command of monodocer.exe. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** Mike Kestner wrote: Hello docsters, I'm looking for info on the state of the art in HTML documentation production from monodoc source docs. I've scanned the monodoc cvs module and found monodoc/tools/genhtml.sh, but it seems to require a mysterious index.xml file that is undocumented and doesn't seem to be part of the current doc structure for either Gtk# or the class docs. So, are there tools to produce HTML docs from either monodoc source xml or assembled monodoc .tree files? ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Tiny patch to monodoc/tools/README (s/stub.exe/monodocer.exe/g)
Heh, thanks, committed! -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] monodoc ecma-provider reflection and the gac
Hey, John. I have this fixed on my hard drive already and will commit it very soon. Along with that, the commit will 1) turn off the Mono Implementation Notes if the assembly isn't found 2) generate the inheritance trees from the XML files, so having the assembly present isn't required and 3) optionally display inherited (non-overridden) members in the member listing, based on an option in the View menu. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Translator from monodoc XML format to Microsoft XML format
Rodolfo,
A starting point:
For the static HTML docs generating stuff I'm working on, I added a new
index.xml file into the mix. These files (one per assembly) contain
assembly- and namespace- specific documentation that isn't present in
the regular XML files for each of the types.
You might want to use these files to determine which types to combine
into the MS-style XML file, using something like:
xsl:for-each
select=document('index.xml')/Overview/Types/Namespace/Type/@Name
You can generate an index.xml file using monodoc/tools/stub.exe with the
--stubassembly option (which I just now committed). This will let you
combine all of the files entirely with XSLT.
Otherwise you could also scan the directory, but that requires
programming outside of XSLT.
--
- Joshua Tauberer
http://taubz.for.net
** Nothing Unreal Exists **
Rodolfo Campero wrote:
I don't know how long will take to do that; I will try first to do a
stand alone application, and then I will check NDoc documentation in
order to evaluate if I can do the documenter.
If I decide to jump into that second task, I will ask Kevin if I need
some help or explanation.
From: Gert Driesen [EMAIL PROTECTED]
To: Rodolfo Campero
[EMAIL PROTECTED],[EMAIL PROTECTED]
CC: [EMAIL PROTECTED]
Subject: Re: [Mono-docs-list] Translator from monodoc XML format to
Microsoft XML format
Date: Thu, 29 Apr 2004 15:57:16 +0200
Hi,
Kevin Downs (NDoc team) has already started working on an NDoc documenter
that will convert MS XML format to Monodoc. It would be great if the
conversion from Monodoc (ECMA) to MS XML format could be implemented
as an
NDoc documenter too.
Gert
- Original Message -
From: Rodolfo Campero [EMAIL PROTECTED]
To: [EMAIL PROTECTED]
Sent: Thursday, April 29, 2004 3:45 PM
Subject: [Mono-docs-list] Translator from monodoc XML format to Microsoft
XML format
FYI
From: Rodolfo Campero [EMAIL PROTECTED]
To: [EMAIL PROTECTED]
CC: [EMAIL PROTECTED],
[EMAIL PROTECTED],[EMAIL PROTECTED],
[EMAIL PROTECTED]
Subject: Re: [Mono-list] Question about attributes
Date: Thu, 29 Apr 2004 13:37:28 +
Hi Joshua,
I already know XSLT, so I will give it a shot this afternoon (it's
10:30
am
here in Argentina, I will start working on it at 19:00).
Also I will subscribe to mono-docs-list right now, so I will posts
questions there if I have to.
I would like to know who should I refer to when I get something
usable,
in
order to make it part of mono or monodoc.
Best regards,
Rodolfo
From: Joshua Tauberer [EMAIL PROTECTED]
To: Rodolfo Campero [EMAIL PROTECTED]
CC: [EMAIL PROTECTED], [EMAIL PROTECTED],
[EMAIL PROTECTED]
Subject: Re: [Mono-list] Question about attributes
Date: Thu, 29 Apr 2004 09:21:26 -0400
Rodolfo Campero wrote:
I don't know if there is some effort to create a translator from
monodoc XML format to Microsoft XML documentation format. That would
be nice, because one could use NDoc to generate files for Windows
users.
Does anyone knows about such a tool?
Since this has come up so many times, I'll work on it when I get the
chance. (As I keep repeating on the docs list, the two formats
are so
similar that it would be trivial for anyone to learn XSLT, if
necessary,
and write the conversion themselves if they wanted it. It would also
make
a nice project if someone is looking for a way to contribute to
Mono.)
--
- Joshua Tauberer
http://taubz.for.net
** Nothing Unreal Exists **
_
Protect your PC - get McAfee.com VirusScan Online
http://clinic.mcafee.com/clinic/ibuy/campaign.asp?cid=3963
___
Mono-list maillist - [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-list
_
The new MSN 8: advanced junk mail protection and 2 months FREE*
http://join.msn.com/?page=features/junkmail
___
Mono-docs-list maillist - [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-docs-list
___
Mono-docs-list maillist - [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-docs-list
_
Help STOP SPAM with the new MSN 8 and get 2 months FREE*
http://join.msn.com/?page=features/junkmail
___
Mono-docs-list maillist - [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-docs-list
___
Mono-docs-list maillist - [EMAIL PROTECTED]
http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Translator from monodoc XML format to Microsoft XML format
Rodolfo Campero wrote: Given the fact that Kevin is working on a command-line utility to convert MonoDoc-MS-XML, I consider that it will be a waste of effort if I start coding such a tool from scratch. So in my opinion the best thing to do now is just wait untill Kevin finishes its work. Do you agree? It's hard to disagree with that. :) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Mono 1.0 quickly approaching.
Miguel de Icaza wrote: We are only nine weeks from Mono 1.0, and now is a perfect time to start documenting some classes using Monodoc if you have some spare time. Only 21,118 things left to document in corlib! (This is the number of occurences of To be added in the corlib XML files, which are now pretty much in sync with the actual assembly.) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] Re: [Mono-list] Offline docs, PerlSharp
Daniel Morgan wrote: I can not wait for the static HTML documentation for Mono. Wait no longer. :) See: http://taubz.for.net/code The docs aren't perfect, but... *Also* I've put up a little webpage for my PerlSharp binding, including documentation for it using the same method as I used to generate the docs above. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
[Mono-docs-list] New docs tools, offline html output
Hey, all. In trying to get my PerlSharp binding to look nice and professional, I started working on an off-line HTML generator for Monodoc XML files. It basically runs docs through a modified version of the main XSL stylesheet that Monodoc uses. The output is a lot like Javadoc output. I'd like to commit this, plus my stub.cs program (no longer creating duplicates of operators), into a new /monodoc/tools directory. Objections anyone? After I get this in CVS, I'll post HTML documentation for the Mono assemblies somewhere, since someone had asked for that a while back. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] monodoc newbie
Soeren wrote: When looking up classes such as gda.client I get this: Mono Implementation Note: An error occured while loading type information: File 'gda-sharp' not found. Whats that about. Monodoc loads up assemblies to check that the documentation in monodoc actually corresponds to what's in the assembly. It's saying it can't find that assembly. Is it possible to contrib text to classes that show this? Yes. And who exactly are allowed to contrib text? Is any filling in the blanks in gda.*? As far as I know, you're welcome to contribute anything. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Updating class library docs
Hector E. Gomez Morales wrote: Sorry If I was grumpy but I thank you for you work and time spent, but that is peer review is all about, I think :). I didn't mind. :) One question again, I like very much some parts of your program but I like some things too from update.exe can I borrow some code from your app and use it to merge and make a new better update.exe? Yeah, go for it. I'm curious to know what you're using from update, though. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Running the updater on mscorlib.
Ben Maurer wrote: Yep, we have talked about this before. jluke said that we would loose alot of the ECMA docs by doing this. Why is that? My recollection of the updater program was that it was pretty flakey. It shouldn't be hard to write a new program to bring the xml files up to date, though - checking for new members or removed members can be based on the code I wrote for those Mono Implementation Note boldfaces. (back to lurking) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Monodoc editing and live preview.
Miguel de Icaza wrote: * see cref=SomeType/ is invoked, the error message I get is: Looks like you need to add the extension object before calling Htmlize. XsltArgumentList args = new XsltArgumentList(); args.AddExtensionObject(monodoc://extensions, new ExtensionObject() and pass that to Htmlize. You'll have to make that class public, I guess. * I would love to give some loving to the various block types to spice up our rendering. How will the html widget know to load the icons from resources in the assembly? -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Rendering if methods error
Martin Willemoes Hansen wrote: In MonoDoc-0.6, the methods with parameters do not have a space between method name and parameter list, but the space is in the parameter list like: void foobar( Foo foo); Fixed in CVS. Thanks for pointing it out, I had forgotten about that. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Patch for overloads in monodoc
Don't forget overloaded properties with indexers. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Quick Monodoc patch
Ben Maurer wrote: I have a quick patch for Monodoc that makes it so that we don't put in excess xmlns stuff (we were generating code like p xmlns:monodoc=monodoc://extensions) Looks good to me, Ben. Sorry about that - I hadn't looked at the raw output since I added the monodoc xsl extension functions. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] Web based Monodoc
To alleviate increasing the complexity in browser.cs, I propose adding a separate class to generate www output. Two other possibilities: Pipe the output of monodoc to xsltproc. This has the advantages of keeping everything out of browser.cs and not having any extra dependencies (xsltproc should be a dependency of mono anyway through libxslt): system(monodoc --html '$query' | xsltproc --stringparam processorurl 'theurlprefix' nameofstylesheet.xsl -); Create a new assembly that does the transformation by referencing browser.exe and using the classes in there however you need to get the job done. Only minor modifications might need to be made to browser.cs. I see these as a bit more clean than putting the code into browser.cs. But, I'm a fanatic about these things, so I'll shush already. -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
Re: [Mono-docs-list] MonoDoc type lookups / helpsource improvement
Miguel de Icaza wrote: * Is this the fix for delegates? * Is this the fix for the ref/out you talked about before? Okay, now we have those. Updating all of the ECMA docs took a while to make sure no information was being lost as I ran all of the xml files through a stylesheet. I realize now that committing changes for the whole monodoc/class directory was probably not a good idea... Parameter nodes now have a RefType attribute if the parameter is by referece which is either ref or out. Delegates have Parameters and ReturnValue nodes at their top-level, which have the same format as those in member nodes. I realize now that Events should have their delegate type stored in the ECMA docs as well... but I leave this for another time. I'll need to add these new attributes/nodes to whatever programs there are to generate ECMA outlines and updates. I'll also need to give to GTK# people what I used to update the docs. I fixed a few more mono-ecma stylesheet bugs. And, I added a Mono Implementation Notes section at the top of type and member pages (and summaries in the type and member listings): mono-ecma.xsl now has a call to an extension function to get this information at runtime I had to fix my extension object implementation in System.XML.dll to get this to work, otherwise it would randomly generate NullReferenceExceptions. If the assembly of the type is available to MonoDoc, it loads the assembly. If the type doesn't exist, or if it has MonoTODO attributes, or if its members have MonoTODO attributes, it presents that information on the documentation page. Maybe this should be done ahead of time, or not at all. It might be a good way to identify what parts of Mono still need work. Hopefully this is wrapping up my monodoc contributions. :) -- - Joshua Tauberer http://taubz.for.net ** Nothing Unreal Exists ** ___ Mono-docs-list maillist - [EMAIL PROTECTED] http://lists.ximian.com/mailman/listinfo/mono-docs-list
