From jonpryor at vt.edu  Tue Mar 11 15:42:02 2008
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Tue, 11 Mar 2008 15:42:02 -0400
Subject: [Mono-docs-list] XSLT Merge
Message-ID: <1205264522.29118.32.camel@lina.magi.jprl.com>

I've just committed a patch which merges the commonalities between
monodoc/engine/mono-ecma-css.xsl and mono-ecma.xsl into
mono-ecma-impl.xsl, thus allowing most of the code to be shared between
them.  This change also improves some of the CSS used so, visually, it
looks unchanged. :-)

If anyone could take a gander/code review I would appreciate it.

Up next I plan on making monodoc/engine/mono-ecma-impl.xsl more like
monodoc/tools/stylesheet.xsl, in particular generating CREF-style
hyperlinks instead of...whatever you want to call the current output.
This will change links such as:

	/docs/monodoc.ashx?link=M:System.Array.AsReadOnly<T>(T[])

into

	/docs/monodoc.ashx?link=M:System.Array.AsReadOnly``1(``0[])

This will permit two things:

1. ecma-provider will have a consistent URL that it needs to parse
(currently it needs to cope with both to some broken extent, and
completely ignores the former, which is why half the links to generic
methods on go-mono.com/docs never work); and

2. improve integration with monodocs2html, as it currently generates the
latter-style links to System.* types, so this will continue to work in a
better supported fashion.

Thanks,
 - Jon



From jonpryor at vt.edu  Sat Mar 15 21:52:03 2008
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Sun, 16 Mar 2008 01:52:03 +0000
Subject: [Mono-docs-list] XSLT Merge
In-Reply-To: <1205264522.29118.32.camel@lina.magi.jprl.com>
References: <1205264522.29118.32.camel@lina.magi.jprl.com>
Message-ID: <1205632323.5498.47.camel@lina.magi.jprl.com>

On Tue, 2008-03-11 at 15:42 -0400, Jonathan Pryor wrote:
> Up next I plan on making monodoc/engine/mono-ecma-impl.xsl more like
> monodoc/tools/stylesheet.xsl, in particular generating CREF-style
> hyperlinks instead of...whatever you want to call the current output.
> This will change links such as:
> 
> 	/docs/monodoc.ashx?link=M:System.Array.AsReadOnly<T>(T[])
> 
> into
> 
> 	/docs/monodoc.ashx?link=M:System.Array.AsReadOnly``1(``0[])
> 
> This will permit two things:
> 
> 1. ecma-provider will have a consistent URL that it needs to parse
> (currently it needs to cope with both to some broken extent, and
> completely ignores the former, which is why half the links to generic
> methods on go-mono.com/docs never work); and
> 
> 2. improve integration with monodocs2html, as it currently generates the
> latter-style links to System.* types, so this will continue to work in a
> better supported fashion.

This has just been committed as well.

Consequently monodoc/tools/stylesheet.xsl is *much* smaller, as it
shares a majority of its code with monodoc/engine/mdoc-html-utils.xsl
now.  Even better:

  - CSS output now generates the JavaScript "bling" discussed here:
	http://www.jprl.com/Blog/archive/development/2008/Feb-19.html
  - Navigation involving generic types actually works a majority of the 
    time now, instead of randomly.

The biggest fix is that it actually works now; the previous fix
refactored monodoc/engine/mono-ecma.xsl etc., but placed all dependent
XSLT files into resources within the monodoc.dll assembly.  It did NOT,
however, allow the XslTransform class to *use* the embedded resources;
consequently, it would work if your CWD was monodoc/engine, and would
fail if the CWD was anything else.  Oops.

Any testing would be appreciated.

Thanks,
 - Jon



From jonpryor at vt.edu  Sat Mar 22 09:47:55 2008
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Sat, 22 Mar 2008 09:47:55 -0400
Subject: [Mono-docs-list] The future of monodoc.dll
Message-ID: <1206193675.21631.14.camel@lina.magi.jprl.com>

One of the things I'd like to do before the Mono 2.0 release is migrate
monodoc.dll to use C# 2.0 features such as generics in the public API.
For example, instead of Monodoc.Node.Nodes being an ArrayList, it should
be an IEnumerable<Node> or IList<Node>, and Monodoc.Node should
implement IComparable<Node>, etc.

However, I'm not sure that this can actually be done, as monodoc.dll is
installed into the GAC, and such an API change would break any existing
clients on upgrade.

Consequently, I thought I'd throw out another idea: #ifs and changing
the assembly name.

Instead of building just monodoc.dll, we could build both monodoc.dll
and a Mono.Documentation.dll.  monodoc.dll would remain .NET 1.0
compatible, Mono.Documentation.dll would be for .NET 2.0, and we could
use #if's to keep the two separate:

        #if NET_2_0
        using NodeList = System.Collections.Generic.IList<Mono.Documentation.Node>;
        #else
        using NodeList = System.Collections.ArrayList;
        #endif
        
        public class Node : IComparable
        #if NET_2_0
          , IComparable<Node>
        #endif
        {
                public NodeList Nodes {...}
        }

This is similar/identical to what we do in mcs/class.

The alternatives are to:

1. Keep monodoc.dll as .NET 1.0 only -- no generics, etc.

2. Migrate monodoc.dll to .NET 2.0, and change the assembly version
number.  Problem is that the 1.0 monodoc.dll couldn't be built anymore
without using e.g. the monodoc-1.9.tar.gz file.

3. Keep monodoc.dll, and use a different set of source files to build
the .NET 2.0 Mono.Documentation.dll.  Perhaps it could use the 1.0
monodoc.dll as part of its implementation...?

4. Something else?

Thoughts?
 - Jon



From mkestner at novell.com  Sat Mar 22 12:39:19 2008
From: mkestner at novell.com (Mike Kestner)
Date: Sat, 22 Mar 2008 11:39:19 -0500
Subject: [Mono-docs-list] The future of monodoc.dll
In-Reply-To: <1206193675.21631.14.camel@lina.magi.jprl.com>
References: <1206193675.21631.14.camel@lina.magi.jprl.com>
Message-ID: <1206203959.22193.21.camel@t61p.site>


On Sat, 2008-03-22 at 09:47 -0400, Jonathan Pryor wrote:
> One of the things I'd like to do before the Mono 2.0 release is migrate
> monodoc.dll to use C# 2.0 features such as generics in the public API.
> For example, instead of Monodoc.Node.Nodes being an ArrayList, it should
> be an IEnumerable<Node> or IList<Node>, and Monodoc.Node should
> implement IComparable<Node>, etc.

I guess my main question would be, why?  It doesn't save boxing
overhead, since Node is a reference type, right?  Seems like
considerable pain to avoid typing 'as Node' occasionally.

Unless the generics usage is necessary for a feature addition to a
consumer of the dll, I don't see the justification for breaking
stability.

> However, I'm not sure that this can actually be done, as monodoc.dll is
> installed into the GAC, and such an API change would break any existing
> clients on upgrade.

In order to do it, you would need to install a new assembly version into
the GAC, and probably make a monodoc-2.0.pc which is
parallel-installable to the old version.

> Consequently, I thought I'd throw out another idea: #ifs and changing
> the assembly name.
> 
> Instead of building just monodoc.dll, we could build both monodoc.dll
> and a Mono.Documentation.dll.  monodoc.dll would remain .NET 1.0
> compatible, Mono.Documentation.dll would be for .NET 2.0, and we could
> use #if's to keep the two separate:

If we are really going to end up with two separate dlls, we probably
ought to spec out what we need for features in a new "engine" dll, and
implement them in as clean as possible a codebase.

For example, my new editor/viewer could probably benefit from an engine
node that exposes raw XML.  The current system is all about returning
html for obvious reasons.

I just don't see the real benefit in having a dual assembly setup if the
only difference between the versions is a little C# 2.0 sugar.

-- 
Mike Kestner <mkestner at novell.com>


From mario.sopena at gmail.com  Sat Mar 22 14:18:01 2008
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Sat, 22 Mar 2008 19:18:01 +0100
Subject: [Mono-docs-list] The future of monodoc.dll
In-Reply-To: <1206203959.22193.21.camel@t61p.site>
References: <1206193675.21631.14.camel@lina.magi.jprl.com>
	<1206203959.22193.21.camel@t61p.site>
Message-ID: <ef36f55f0803221118jdc66dc8y8528bf664b4fafe@mail.gmail.com>

Hi,

   I agree with Mike. More important than C# 2.0 sintantic sugar is
all the wrong things with the current monodoc API:

* two lookup alternatives (tree node and URL based)
* not a clear render pipeline: like Mike said, it does not expose XML,
but is is also has a rather strange way of dealing with editing and
its hardly extensible
* no easy way of installing new documentation (or updated one)
* Some minor capabilities to edit documentation of a project but no
easy way to reuse the monodoc remote documentation editing
capabilities with something not the mono project documentation
* Wrong way of handling with "installed documentation". There is no
way to deal with documentation packages. Instead, you are presented
with a list of possible documentation packages, some of them could be
installed, some of them not.

Mario

On 22/03/2008, Mike Kestner <mkestner at novell.com> wrote:
>
>  On Sat, 2008-03-22 at 09:47 -0400, Jonathan Pryor wrote:
>  > One of the things I'd like to do before the Mono 2.0 release is migrate
>  > monodoc.dll to use C# 2.0 features such as generics in the public API.
>  > For example, instead of Monodoc.Node.Nodes being an ArrayList, it should
>  > be an IEnumerable<Node> or IList<Node>, and Monodoc.Node should
>  > implement IComparable<Node>, etc.
>
>
> I guess my main question would be, why?  It doesn't save boxing
>  overhead, since Node is a reference type, right?  Seems like
>  considerable pain to avoid typing 'as Node' occasionally.
>
>  Unless the generics usage is necessary for a feature addition to a
>  consumer of the dll, I don't see the justification for breaking
>  stability.
>
>
>  > However, I'm not sure that this can actually be done, as monodoc.dll is
>  > installed into the GAC, and such an API change would break any existing
>  > clients on upgrade.
>
>
> In order to do it, you would need to install a new assembly version into
>  the GAC, and probably make a monodoc-2.0.pc which is
>  parallel-installable to the old version.
>
>
>  > Consequently, I thought I'd throw out another idea: #ifs and changing
>  > the assembly name.
>  >
>  > Instead of building just monodoc.dll, we could build both monodoc.dll
>  > and a Mono.Documentation.dll.  monodoc.dll would remain .NET 1.0
>  > compatible, Mono.Documentation.dll would be for .NET 2.0, and we could
>  > use #if's to keep the two separate:
>
>
> If we are really going to end up with two separate dlls, we probably
>  ought to spec out what we need for features in a new "engine" dll, and
>  implement them in as clean as possible a codebase.
>
>  For example, my new editor/viewer could probably benefit from an engine
>  node that exposes raw XML.  The current system is all about returning
>  html for obvious reasons.
>
>  I just don't see the real benefit in having a dual assembly setup if the
>  only difference between the versions is a little C# 2.0 sugar.
>
>
>  --
>  Mike Kestner <mkestner at novell.com>
>
>
>  _______________________________________________
>  Mono-docs-list maillist  -  Mono-docs-list at lists.ximian.com
>  http://lists.ximian.com/mailman/listinfo/mono-docs-list
>