From aramirez at xenodium.com  Sun Dec  2 13:26:38 2007
From: aramirez at xenodium.com (Alvaro A. Ramirez)
Date: Sun, 02 Dec 2007 18:26:38 +0000
Subject: [Mono-docs-list] monodoc search bar
Message-ID: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>

Hi all,

Picked up monodoc recently and noticed one cannot search within the
current page. This is quite useful when looking up APIs. In any case,
I've added a little bar (similar to epiphany's) to search within the
current tab.

Attached is a patch for mono-tools. gnome-sharp also needs to be patched
to bind the search methods in gtkhtml. Comments? Suggestion? Am I way
off here? ;)

Cheers,

Alvaro

ps. The search bar is currently disabled when using gecko renderer. I
plan on adding search to GeckoHtmlRender as well.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gnome-sharp.diff
Type: text/x-patch
Size: 2419 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071202/e9e3434d/attachment-0002.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: mono-tools.diff
Type: text/x-patch
Size: 18506 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071202/e9e3434d/attachment-0003.bin 

From mkestner at novell.com  Sun Dec  2 18:24:29 2007
From: mkestner at novell.com (Mike Kestner)
Date: Sun, 02 Dec 2007 17:24:29 -0600
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
Message-ID: <1196637869.27459.22.camel@t61p.site>


On Sun, 2007-12-02 at 18:26 +0000, Alvaro A. Ramirez wrote:

> Attached is a patch for mono-tools. gnome-sharp also needs to be patched
> to bind the search methods in gtkhtml. Comments? Suggestion? Am I way
> off here? ;)

Because of some API stability issues, we will be moving gtkhtml-sharp
from gnome-sharp to the new gnome-desktop-sharp module in the next
release cycle.  This patch might be better applied against that module.

The other issue is one of dependency.  Is it okay for docbrowser to
depend on bleeding edge gtkhtml-sharp?  If not, you will probably need
to make this feature optional via configure magic to allow building
against older gtk-sharp/gnome-sharp releases.  At the very least, you
need to bump the configure version check in mono-tools to identify the
new dependency.

-- 
Mike Kestner <mkestner at novell.com>


From miguel at novell.com  Mon Dec  3 15:20:59 2007
From: miguel at novell.com (Miguel de Icaza)
Date: Mon, 03 Dec 2007 15:20:59 -0500
Subject: [Mono-docs-list] Proposing a new documentation subsystem
In-Reply-To: <1195921831.4167.79.camel@erandi.boston.ximian.com>
References: <1195921831.4167.79.camel@erandi.boston.ximian.com>
Message-ID: <1196713259.3977.25.camel@erandi.boston.ximian.com>


>  - 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.

I can not think of an example, but even if I did, you could still add
the comment as a regular remark.

>  - Generic Types and Members are not fully supported in the
>    documentation browser.

This is a bug, should be easy to fix.

>  - Automated user-contributions do not work properly (I don't know if a
>    contribution has ever made it into the documentation).

Thousands have.    There are a number of problems though:

	* Am currently the only admin.

	* There are few contributions, fewer good ones.

	* Many of the contributions are bad (incomplete examples,
	  non-compiling examples, lack of consistency in the examples),
	  description is sometimes plain wrong.

	* Some of the contributions for Gtk# tend to be cut-and-paste
	  without any editing or adjustments for Gtk# directly from the
	  Gtk+ docs.

	* Worst of all: for the MS APIs, many contributions are direct
	  cut and paste texts from the MSDN documentation.

	  This last one means that I tend to defer their approval until
	  I have visually inspected each documentation member, and this 
	  takes a lot of time.

	  If the contribution is minor, I usually let it go.

>  - 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)

Correct;   But there is so little documentation being written, that this
is not a major issue.

If we had people writing lots of documentation, we could upload new zip
files and have monodoc ping those to download them.

Today, adding such support would be mostly useless, considering the
glacial speed at which people actually write docs.

>  - Documentation work-cycle is pretty complicated. It is very unhandy to
>    run many tools to do one simple task. (monodoc, browser, mdassembler)

Not sure what you mean.

>  - 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)

We have revision control, its called SVN.


> 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.

We already have this, the admin UI could be improved, and I can grant
other people admin rights;   The problems with the contributions
remains.

As usual, programmers tend to think that they can code their way out of
actually writing documentation.   And as it turns out, writing
documentation, requires someone to sit down and go through the
implementation and actually describe it.   No amount of tooling helps
here.

I would be happy to improve the documentation tools though, and am
looking for some concrete, but most importantly evolutionary proposals
as opposed to revolutionary ones.

Miguel

From miguel at novell.com  Mon Dec  3 15:26:21 2007
From: miguel at novell.com (Miguel de Icaza)
Date: Mon, 03 Dec 2007 15:26:21 -0500
Subject: [Mono-docs-list] Proposing a new documentation subsystem
In-Reply-To: <ef36f55f0711300347g3436d446rcd194f698848e996@mail.gmail.com>
References: <1195896955.4040.33.camel@pi1536.local>
	<474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local>
	<1195932307.4588.43.camel@lina.magi.jprl.com>
	<1195995363.4777.38.camel@pi1536.local>
	<1196000927.30453.15.camel@lina.magi.jprl.com>
	<ef36f55f0711300347g3436d446rcd194f698848e996@mail.gmail.com>
Message-ID: <1196713581.3977.29.camel@erandi.boston.ximian.com>

Hello,

> I spoke with Lluis Sanchez about using Mono.Addins to extend the
> documentation system and it seems a good approach because we will get
> all the subsytem for documentation updates and managment (both for
> providers and for doc sources) for free.
> 
> This will enable downloading new docs or providers without updating
> the whole monodoc system. We can also get rid of the several xml files
> needed to finally reach the documentation files and free monodoc
> subsytem of some managment code.
> 
> Once I have something workable I will post here for further discussion.

Which kind of add-ins do you have in mind?

I love add-ins where they make sense, but I do not love add-ins for the
sake of having an add-in.   If we have a genuine reason to support a new
file format we should decide whether there is a good reason to not have
it as part of the core mono documentation system.

Supporting downloading updates is a pipeline issue more than an "add-in"
issue.   Sure, you can write an add-in, but the fundamental issues are:

	* Someone needs to write the new docs (these happen at glacial
	  speeds)

	* If the above were fixed (hundreds of new docs per day), 
	  updating docs should just be part to the core Monodoc 
	  functionality.

MIguel

From jonpryor at vt.edu  Mon Dec  3 15:31:51 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Mon, 03 Dec 2007 15:31:51 -0500
Subject: [Mono-docs-list] Proposing a new documentation subsystem
In-Reply-To: <1196713581.3977.29.camel@erandi.boston.ximian.com>
References: <1195896955.4040.33.camel@pi1536.local>
	<474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local>
	<1195932307.4588.43.camel@lina.magi.jprl.com>
	<1195995363.4777.38.camel@pi1536.local>
	<1196000927.30453.15.camel@lina.magi.jprl.com>
	<ef36f55f0711300347g3436d446rcd194f698848e996@mail.gmail.com>
	<1196713581.3977.29.camel@erandi.boston.ximian.com>
Message-ID: <1196713911.23240.22.camel@lina.magi.jprl.com>

On Mon, 2007-12-03 at 15:26 -0500, Miguel de Icaza wrote:
> > I spoke with Lluis Sanchez about using Mono.Addins to extend the
> > documentation system and it seems a good approach because we will get
> > all the subsytem for documentation updates and managment (both for
> > providers and for doc sources) for free.
> > 
> > This will enable downloading new docs or providers without updating
> > the whole monodoc system. We can also get rid of the several xml files
> > needed to finally reach the documentation files and free monodoc
> > subsytem of some managment code.
>
> Which kind of add-ins do you have in mind?

I think he was suggesting that we bundle the XML docs *as* an add-in.
(At least, this was my interpretation, and made me go "Cool!")  This
would allow using the existing Mono.Addins infrastructure to update the
documentation after installation time.

So no format changes (beyond what I've already proposed), just a
distribution model change.

This sounds rational to me.

> Supporting downloading updates is a pipeline issue more than an "add-in"
> issue.   Sure, you can write an add-in, but the fundamental issues are:
> 
> 	* Someone needs to write the new docs (these happen at glacial
> 	  speeds)

If we use add-ins as the package model and not the file format, this is
a non-issue -- we use the existing docs, and write a program to compile
the current (.source .tree .zip) file tuple into an add-in.

> 	* If the above were fixed (hundreds of new docs per day), 
> 	  updating docs should just be part to the core Monodoc 
> 	  functionality.

Exactly, but Mono.Addins already has updating as a core part of its
functionality, so using Mono.Addins as the *distribution* format would
allow code reuse here.

 - Jon



From mario.sopena at gmail.com  Tue Dec  4 12:33:02 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Tue, 4 Dec 2007 18:33:02 +0100
Subject: [Mono-docs-list] Proposing a new documentation subsystem
In-Reply-To: <1196713911.23240.22.camel@lina.magi.jprl.com>
References: <1195896955.4040.33.camel@pi1536.local>
	<474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local>
	<1195932307.4588.43.camel@lina.magi.jprl.com>
	<1195995363.4777.38.camel@pi1536.local>
	<1196000927.30453.15.camel@lina.magi.jprl.com>
	<ef36f55f0711300347g3436d446rcd194f698848e996@mail.gmail.com>
	<1196713581.3977.29.camel@erandi.boston.ximian.com>
	<1196713911.23240.22.camel@lina.magi.jprl.com>
Message-ID: <ef36f55f0712040933i29646dbu9aaed43a373ecdf7@mail.gmail.com>

Hi,

   Jon replies are exactly what I meant. Nothing to add here.

  By the way, your changes about adding AssemblyInfo to every members
sounds good to me. The only problem I see is what to do with the
already <since> tag that we have. Does the implementation collide in
some way?

Mario

On 03/12/2007, Jonathan Pryor <jonpryor at vt.edu> wrote:
> On Mon, 2007-12-03 at 15:26 -0500, Miguel de Icaza wrote:
> > > I spoke with Lluis Sanchez about using Mono.Addins to extend the
> > > documentation system and it seems a good approach because we will get
> > > all the subsytem for documentation updates and managment (both for
> > > providers and for doc sources) for free.
> > >
> > > This will enable downloading new docs or providers without updating
> > > the whole monodoc system. We can also get rid of the several xml files
> > > needed to finally reach the documentation files and free monodoc
> > > subsytem of some managment code.
> >
> > Which kind of add-ins do you have in mind?
>
> I think he was suggesting that we bundle the XML docs *as* an add-in.
> (At least, this was my interpretation, and made me go "Cool!")  This
> would allow using the existing Mono.Addins infrastructure to update the
> documentation after installation time.
>
> So no format changes (beyond what I've already proposed), just a
> distribution model change.
>
> This sounds rational to me.
>
> > Supporting downloading updates is a pipeline issue more than an "add-in"
> > issue.   Sure, you can write an add-in, but the fundamental issues are:
> >
> >       * Someone needs to write the new docs (these happen at glacial
> >         speeds)
>
> If we use add-ins as the package model and not the file format, this is
> a non-issue -- we use the existing docs, and write a program to compile
> the current (.source .tree .zip) file tuple into an add-in.
>
> >       * If the above were fixed (hundreds of new docs per day),
> >         updating docs should just be part to the core Monodoc
> >         functionality.
>
> Exactly, but Mono.Addins already has updating as a core part of its
> functionality, so using Mono.Addins as the *distribution* format would
> allow code reuse here.
>
>  - Jon
>
>
>

From jonpryor at vt.edu  Tue Dec  4 13:11:45 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Tue, 04 Dec 2007 18:11:45 +0000
Subject: [Mono-docs-list] Proposing a new documentation subsystem
In-Reply-To: <ef36f55f0712040933i29646dbu9aaed43a373ecdf7@mail.gmail.com>
References: <1195896955.4040.33.camel@pi1536.local>
	<474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local>
	<1195932307.4588.43.camel@lina.magi.jprl.com>
	<1195995363.4777.38.camel@pi1536.local>
	<1196000927.30453.15.camel@lina.magi.jprl.com>
	<ef36f55f0711300347g3436d446rcd194f698848e996@mail.gmail.com>
	<1196713581.3977.29.camel@erandi.boston.ximian.com>
	<1196713911.23240.22.camel@lina.magi.jprl.com>
	<ef36f55f0712040933i29646dbu9aaed43a373ecdf7@mail.gmail.com>
Message-ID: <1196791905.23240.61.camel@lina.magi.jprl.com>

On Tue, 2007-12-04 at 18:33 +0100, Mario Sopena Novales wrote:
>   By the way, your changes about adding AssemblyInfo to every members
> sounds good to me. The only problem I see is what to do with the
> already <since> tag that we have. Does the implementation collide in
> some way?

They don't collide, but <since/> is conceptually superseded by
<AssemblyInfo/>.  I'm not sure what to do about that.  On the one hand,
<since/> permits a human-readable string (instead of a version number),
but <AssemblyInfo/> is more automated and less likely to be wrong (I
hope).

Both could be shown, though I'm not sure how confusing this would be...

 - Jon



From aramirez at xenodium.com  Tue Dec  4 19:28:16 2007
From: aramirez at xenodium.com (Alvaro Ramirez)
Date: Wed, 05 Dec 2007 00:28:16 +0000
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <1196637869.27459.22.camel@t61p.site>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
	<1196637869.27459.22.camel@t61p.site>
Message-ID: <1196814496.30973.56.camel@PenguinGuiness.WhosNet>

Hiya Mike,

> Because of some API stability issues, we will be moving gtkhtml-sharp
> from gnome-sharp to the new gnome-desktop-sharp module in the next
> release cycle.  This patch might be better applied against that module.

Sounds good. Attached is now gnome-desktop-sharp.diff

> 
> The other issue is one of dependency.  Is it okay for docbrowser to
> depend on bleeding edge gtkhtml-sharp? 

Should be ok. I've now made it optional. There was already a check for
bleeding edge gtkhtml-sharp (3.14) used for printing. If not present,
the search bar is disabled.

>  If not, you will probably need
> to make this feature optional via configure magic to allow building
> against older gtk-sharp/gnome-sharp releases.  At the very least, you
> need to bump the configure version check in mono-tools to identify the
> new dependency.

Yup, you can build against older gtk-sharp/gnome-sharp releases, since
the search bar is now optional. Have a look at the new patches.

Thanks,

Alvaro
-------------- next part --------------
A non-text attachment was scrubbed...
Name: mono-tools.diff
Type: text/x-patch
Size: 19229 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071205/eaeb5c49/attachment-0002.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gnome-desktop-sharp.diff
Type: text/x-patch
Size: 2611 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071205/eaeb5c49/attachment-0003.bin 

From mario.sopena at gmail.com  Wed Dec  5 03:38:37 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Wed, 5 Dec 2007 09:38:37 +0100
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <1196814496.30973.56.camel@PenguinGuiness.WhosNet>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
	<1196637869.27459.22.camel@t61p.site>
	<1196814496.30973.56.camel@PenguinGuiness.WhosNet>
Message-ID: <ef36f55f0712050038x1a05d7eeobfe84979fcf8cd1@mail.gmail.com>

Hi,

   I think your patch misses if someone hits the Ctrl+F keystroke but
it does not have the gtkhtml-sharp version needed. It will be
presented with a useless findbar.

We better avoid those situations

Mario

On 05/12/2007, Alvaro Ramirez <aramirez at xenodium.com> wrote:
> Hiya Mike,
>
> > Because of some API stability issues, we will be moving gtkhtml-sharp
> > from gnome-sharp to the new gnome-desktop-sharp module in the next
> > release cycle.  This patch might be better applied against that module.
>
> Sounds good. Attached is now gnome-desktop-sharp.diff
>
> >
> > The other issue is one of dependency.  Is it okay for docbrowser to
> > depend on bleeding edge gtkhtml-sharp?
>
> Should be ok. I've now made it optional. There was already a check for
> bleeding edge gtkhtml-sharp (3.14) used for printing. If not present,
> the search bar is disabled.
>
> >  If not, you will probably need
> > to make this feature optional via configure magic to allow building
> > against older gtk-sharp/gnome-sharp releases.  At the very least, you
> > need to bump the configure version check in mono-tools to identify the
> > new dependency.
>
> Yup, you can build against older gtk-sharp/gnome-sharp releases, since
> the search bar is now optional. Have a look at the new patches.
>
> Thanks,
>
> Alvaro
>
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list
>
>
>

From aramirez at xenodium.com  Wed Dec  5 07:20:48 2007
From: aramirez at xenodium.com (Alvaro Ramirez)
Date: Wed, 05 Dec 2007 12:20:48 +0000
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <ef36f55f0712050038x1a05d7eeobfe84979fcf8cd1@mail.gmail.com>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
	<1196637869.27459.22.camel@t61p.site>
	<1196814496.30973.56.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712050038x1a05d7eeobfe84979fcf8cd1@mail.gmail.com>
Message-ID: <1196857248.6795.17.camel@PenguinGuiness.WhosNet>

Hi Mario,

> I think your patch misses if someone hits the Ctrl+F keystroke but
> it does not have the gtkhtml-sharp version needed. It will be
> presented with a useless findbar.

hmmm... shouldn't be the case. If you build against older versions of
gtkhtml, the menu items get hidden, which would prevent the key-bindings
from working (??)

#if (!GTKHTML_SHARP_3_14)
                ui ["find_separator"].Hide ();
                ui ["find_text"].Hide ();
                ui ["find_next"].Hide ();
                ui ["find_previous"].Hide ();
#endif


> We better avoid those situations

The above seems to avoid the scenario you mentioned. In any case, I've
added some more conditionals and removed the search bar from the
container altogether (when building against older gtk-html). The
downside to this is that browser.cs now has more #if's :( Have a look at
the new patches. Let me know...

Thanks,

Alvaro
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gnome-desktop-sharp.diff
Type: text/x-patch
Size: 2611 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071205/c28d442c/attachment.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: mono-tools.diff
Type: text/x-patch
Size: 19661 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071205/c28d442c/attachment-0001.bin 

From valentin.sawadski at gmx.de  Sat Dec  8 06:04:34 2007
From: valentin.sawadski at gmx.de (Valentin Sawadski)
Date: Sat, 08 Dec 2007 12:04:34 +0100
Subject: [Mono-docs-list] Differences between generic names in the
	documentation.
Message-ID: <1197111874.3998.27.camel@pi1536.local>

Hello,

I recently tried to work on the generics support in monodocer and
noticed that it has names one and the same type differently.

Eg: If i have a "public class Test<T>" monodocer will produce the
following output.

index.xml:
	...
	<Types>
	  <Namespace Name="Test">
	    <Type Name="Test`1" />
	  </Namespace>
	</Types>
	....

Test`1.xml (Note that the the filename and name of the type are already
different):
	<Type Name="Test&lt;T&gt;" FullName="Test.Test.Test&lt;T&gt;">
	...

But then again it seems that the browser uses the Test&lt;T&gt;
everywhere. Sometimes it gets parsed and will be displayed as Test<T>
but other times not and some ugly HTML-Entities are being shown as the
class name.

To streamline all these naming issues my proposal is to use the Test`1
Notation everywhere to be more coherent with the output of Type.Name and
not to introduce too much C#-Notations into the docs since Mono can be
used from a couple of languages.

Generic Methods are also stored in the fancy "Method&lt;T&gt" way while
the Name returned by the corresponding MethodInfo would just be
"Method". Here I would also alter the Name to be compliant with the
output of MethodInfo, otherwise different generic overloads won't be
recognized as an overload (See Console.Write for example)

The changes in monodocer should be pretty easy to do (probably less 20
lines of code). However I haven't yet tested how the rest of the
documentation stack will react. Any comments on that?

Kind Regards,
Valentin.


From jonpryor at vt.edu  Sat Dec  8 11:03:03 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Sat, 08 Dec 2007 11:03:03 -0500
Subject: [Mono-docs-list] Differences between generic names in
	the	documentation.
In-Reply-To: <1197111874.3998.27.camel@pi1536.local>
References: <1197111874.3998.27.camel@pi1536.local>
Message-ID: <1197129783.5871.81.camel@lina.magi.jprl.com>

On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> I recently tried to work on the generics support in monodocer and
> noticed that it has names one and the same type differently.
> 
> Eg: If i have a "public class Test<T>" monodocer will produce the
> following output.
> 
> index.xml:
> 	...
> 	<Types>
> 	  <Namespace Name="Test">
> 	    <Type Name="Test`1" />

To be fair, current output would be:

	<Type Name="Test`1" DisplayName="Test&lt;T&gt;" />

i.e. an added Type/@DisplayName attribute.

> 	  </Namespace>
> 	</Types>
> 	....
> 
> Test`1.xml (Note that the the filename and name of the type are already
> different):

Necessary, actually, because '<' and '>' are not valid filename
characters on Win32. :-)

> 	<Type Name="Test&lt;T&gt;" FullName="Test.Test.Test&lt;T&gt;">
> 	...
> 
> But then again it seems that the browser uses the Test&lt;T&gt;
> everywhere. Sometimes it gets parsed and will be displayed as Test<T>
> but other times not and some ugly HTML-Entities are being shown as the
> class name.

These are bugs in the doc browser and should be fixed.

> To streamline all these naming issues my proposal is to use the Test`1
> Notation everywhere to be more coherent with the output of Type.Name and
> not to introduce too much C#-Notations into the docs since Mono can be
> used from a couple of languages.

I don't like this idea, mostly because e.g. Dictionary`2 is wildly
undescriptive.  Even Microsoft doesn't do this; instead, they do
"Dictionary Generic Class" for the .NET 2.0 docs, and (more sensibly)
"Dictionary(TKey,TValue) Generic Class" for the .NET 3.5 docs.

We could go the .NET 3.5 approach for the DisplayName attribute if you
care that much. :-)

But I really don't want to do Dictionary`2 because it's wrong.  Most
people don't know what "`2" is going to mean, it's ugly, and losing the
"TKey, TValue" part is a loss of some nice information.

> Generic Methods are also stored in the fancy "Method&lt;T&gt" way while
> the Name returned by the corresponding MethodInfo would just be
> "Method". Here I would also alter the Name to be compliant with the
> output of MethodInfo, otherwise different generic overloads won't be
> recognized as an overload (See Console.Write for example)

Generic methods use "Method&lt;T&gt;" because that's what the ECMA
documentation does.  I did this for consistency, as the monodoc XML
format is based on the ECMA XML format.

> The changes in monodocer should be pretty easy to do (probably less 20
> lines of code). However I haven't yet tested how the rest of the
> documentation stack will react. Any comments on that?

You have a point that "<" and ">" are rather C# specific, so
following .NET 3.5 and using '(' and ')' might be an acceptable
compromise (again, if you care that much; personally, I don't have a
problem with using '<' and '>').  For reasons stated above, I do NOT wnt
to use Foo`N notation in the shell.

Furthermore, since you can "overload" types based on the number of
generic type parameters, not using <>/()/[]/etc. to enclose type
parameters either results in name ambiguities (if you only show what's
before the '`', as .NET 2.0 docs do), or requires the use of `N
notation.  Consider:

	delegate R Func<R> ();
	delegate R Func<R,P> (P p);
	delegate R Func<R,P1,P2> (P1 p1, P2 p2);

Which results in Func`1, Func`2, and Func`3, vs. Func<R>, Func<R,P>, and
Func<R,P1,P2> (or replace <> with () or something else).  I find the
latter far preferable.

 - Jon



From mario.sopena at gmail.com  Sun Dec  9 06:11:41 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Sun, 9 Dec 2007 12:11:41 +0100
Subject: [Mono-docs-list] Differences between generic names in the
	documentation.
In-Reply-To: <1197129783.5871.81.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
Message-ID: <ef36f55f0712090311n7e3c8b6bre023f667af5069d3@mail.gmail.com>

Hi,

On 08/12/2007, Jonathan Pryor <jonpryor at vt.edu> wrote:
> On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> > I recently tried to work on the generics support in monodocer and
> > noticed that it has names one and the same type differently.

> >
> > But then again it seems that the browser uses the Test&lt;T&gt;
> > everywhere. Sometimes it gets parsed and will be displayed as Test<T>
> > but other times not and some ugly HTML-Entities are being shown as the
> > class name.
>
> These are bugs in the doc browser and should be fixed.
>

Can you provide samples, bugzilla report or point to a class/method/..
that is not rendered properly so I can try to fix it please.

Thanks!

From mario.sopena at gmail.com  Sun Dec  9 07:11:51 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Sun, 9 Dec 2007 13:11:51 +0100
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <1196857248.6795.17.camel@PenguinGuiness.WhosNet>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
	<1196637869.27459.22.camel@t61p.site>
	<1196814496.30973.56.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712050038x1a05d7eeobfe84979fcf8cd1@mail.gmail.com>
	<1196857248.6795.17.camel@PenguinGuiness.WhosNet>
Message-ID: <ef36f55f0712090411k34a065aata7f6b1cee59b2109@mail.gmail.com>

Hi,

  sorry my comment made you code a new patch. I tried both and, as you
said, with your first patch the findbar does not appears when you
don't have the newet gtkhtml-sharp lib. So, I will go with the first.

However, your patch needs to be in gnome-sharp before we apply it to
monodoc and we have to make sure the version we test is the one that
has your patch applied. So, once it gets in gnome-sharp, the check
should be GTKHTML_SHARP_3_X instead of GTKHTML_SHARP_3_14.

On 05/12/2007, Alvaro Ramirez <aramirez at xenodium.com> wrote:
> Hi Mario,
>
> > I think your patch misses if someone hits the Ctrl+F keystroke but
> > it does not have the gtkhtml-sharp version needed. It will be
> > presented with a useless findbar.
>
> hmmm... shouldn't be the case. If you build against older versions of
> gtkhtml, the menu items get hidden, which would prevent the key-bindings
> from working (??)
>
> #if (!GTKHTML_SHARP_3_14)
>                 ui ["find_separator"].Hide ();
>                 ui ["find_text"].Hide ();
>                 ui ["find_next"].Hide ();
>                 ui ["find_previous"].Hide ();
> #endif
>
>
> > We better avoid those situations
>
> The above seems to avoid the scenario you mentioned. In any case, I've
> added some more conditionals and removed the search bar from the
> container altogether (when building against older gtk-html). The
> downside to this is that browser.cs now has more #if's :( Have a look at
> the new patches. Let me know...
>
> Thanks,
>
> Alvaro
>
>

From aramirez at xenodium.com  Sun Dec  9 08:14:30 2007
From: aramirez at xenodium.com (Alvaro Ramirez)
Date: Sun, 09 Dec 2007 13:14:30 +0000
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <ef36f55f0712090411k34a065aata7f6b1cee59b2109@mail.gmail.com>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
	<1196637869.27459.22.camel@t61p.site>
	<1196814496.30973.56.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712050038x1a05d7eeobfe84979fcf8cd1@mail.gmail.com>
	<1196857248.6795.17.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712090411k34a065aata7f6b1cee59b2109@mail.gmail.com>
Message-ID: <1197206070.5512.26.camel@PenguinGuiness.WhosNet>

Hi Mario,

On Sun, 2007-12-09 at 13:11 +0100, Mario Sopena Novales wrote:
>   sorry my comment made you code a new patch. I tried both and, as you
> said, with your first patch the findbar does not appears when you
> don't have the newet gtkhtml-sharp lib. So, I will go with the first.

No worries!

> However, your patch needs to be in gnome-sharp before we apply it to
> monodoc and we have to make sure the version we test is the one that
> has your patch applied. 

Sounds good. I take it you mean gnome-desktop-sharp (instead of
gnome-sharp)?

> So, once it gets in gnome-sharp, the check
> should be GTKHTML_SHARP_3_X instead of GTKHTML_SHARP_3_14.

Anyone I should ping to get the patch in gnome-desktop-sharp?

Thanks,

Alvaro

On 05/12/2007, Alvaro Ramirez <aramirez at xenodium.com> wrote:
> > Hi Mario,
> >
> > > I think your patch misses if someone hits the Ctrl+F keystroke but
> > > it does not have the gtkhtml-sharp version needed. It will be
> > > presented with a useless findbar.
> >
> > hmmm... shouldn't be the case. If you build against older versions of
> > gtkhtml, the menu items get hidden, which would prevent the key-bindings
> > from working (??)
> >
> > #if (!GTKHTML_SHARP_3_14)
> >                 ui ["find_separator"].Hide ();
> >                 ui ["find_text"].Hide ();
> >                 ui ["find_next"].Hide ();
> >                 ui ["find_previous"].Hide ();
> > #endif
> >
> >
> > > We better avoid those situations
> >
> > The above seems to avoid the scenario you mentioned. In any case, I've
> > added some more conditionals and removed the search bar from the
> > container altogether (when building against older gtk-html). The
> > downside to this is that browser.cs now has more #if's :( Have a look at
> > the new patches. Let me know...
> >
> > Thanks,
> >
> > Alvaro
> >
> >


From jonpryor at vt.edu  Sun Dec  9 08:42:28 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Sun, 09 Dec 2007 08:42:28 -0500
Subject: [Mono-docs-list] Differences between generic names in
	the	documentation.
In-Reply-To: <ef36f55f0712090311n7e3c8b6bre023f667af5069d3@mail.gmail.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
	<ef36f55f0712090311n7e3c8b6bre023f667af5069d3@mail.gmail.com>
Message-ID: <1197207748.4065.8.camel@lina.magi.jprl.com>

On Sun, 2007-12-09 at 12:11 +0100, Mario Sopena Novales wrote:
> On 08/12/2007, Jonathan Pryor <jonpryor at vt.edu> wrote:
> > On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> > > But then again it seems that the browser uses the Test&lt;T&gt;
> > > everywhere. Sometimes it gets parsed and will be displayed as Test<T>
> > > but other times not and some ugly HTML-Entities are being shown as the
> > > class name.
> >
> > These are bugs in the doc browser and should be fixed.
>
> Can you provide samples, bugzilla report or point to a class/method/..
> that is not rendered properly so I can try to fix it please.

I don't know of any bugzilla reports, but here's an example:

1. Open Monodoc.
2. Select Class Library -> System -> Array Class -> Members.
3. Then just look under "Methods" -- lots of issues show up:
   - "Exists&lt;T&gt;(T[], Predicate&lt;T&gt;) : bool" instead of
     "Exists<T>(T[], Predicate<T>) : bool"
   - etc.
4. Click on a "Predicate&lt;T&gt;" link.  This should take you to the
   documentation for System.Predicate`1; instead, it takes to limbo
   with "System.Predicate<T>" in the doc area.

The problem is that the docbrowser is escaping XML entities when it
really shouldn't be, because I know there's logic in the engine to parse
e.g. System.Predicate<T> and translate it into System.Predicate`1 to
load the appropriate documentation (I know as I wrote it; it's simple,
in that it just removes everything after the '<', then appends "# commas
+ 1" between the '<' and '>').

Because the docbrowser is overly escaping, this code is getting
System.Predicate&lt;T&gt;, which (obviously) contains no '<', so the
translation logic fails.

There are likely other bugs; I didn't test this extensively when I
originally wrote (bad me!), and I certainly don't remember this "over
escaping" problem...

 - Jon



From jonpryor at vt.edu  Sun Dec  9 18:27:05 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Sun, 09 Dec 2007 18:27:05 -0500
Subject: [Mono-docs-list] Differences between generic names
	in	the	documentation.
In-Reply-To: <1197129783.5871.81.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
Message-ID: <1197242825.4065.23.camel@lina.magi.jprl.com>

On Sat, 2007-12-08 at 11:03 -0500, Jonathan Pryor wrote:
> On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> > To streamline all these naming issues my proposal is to use the Test`1
> > Notation everywhere to be more coherent with the output of Type.Name and
> > not to introduce too much C#-Notations into the docs since Mono can be
> > used from a couple of languages.
> 
> I don't like this idea, mostly because e.g. Dictionary`2 is wildly
> undescriptive.  Even Microsoft doesn't do this; instead, they do
> "Dictionary Generic Class" for the .NET 2.0 docs, and (more sensibly)
> "Dictionary(TKey,TValue) Generic Class" for the .NET 3.5 docs.
> 
> We could go the .NET 3.5 approach for the DisplayName attribute if you
> care that much. :-)
> 
> But I really don't want to do Dictionary`2 because it's wrong.  Most
> people don't know what "`2" is going to mean, it's ugly, and losing the
> "TKey, TValue" part is a loss of some nice information.

To elaborate further, Microsoft documentation for .NET 3.5 uses
parenthesis to enclose type parameters (as already mentioned).

The next issue, if you want a "truly" language-agnostic description, is
the Members view of a given class, e.g. Class Library -> System -> Array
-> Members.  Monodoc currently shows all type parameters AND the full
parameter list, e.g. AsReadOnly<T>(T[]), while .NET 3.5 shows only the
method name and type parameters, e.g. AsReadOnly(T).

The "advantage" to the .NET approach is a more language-agnostic display
-- no language uses (T) for type parameters, though it *is* close to
VB.NET which would use (Of T).

The disadvantage is that .NET doesn't show argument lists.  Perhaps this
isn't necessary, but I find that this leads to extra clicks within
msdn2.microsoft.com as they "collapse" all overloads into a single link.

This "collapsing" doesn't help though; see:

http://msdn2.microsoft.com/en-us/library/system.array.binarysearch(VS.90).aspx

When you view the overloads, you see _all_ overloads for a given method,
*plus* type parameters, resulting in such "helpful" language-agnostic
prototypes as:

	BinarySearch(T)([], T)
	BinarySearch(T)([], T, IComparer(T))
	BinarySearch(T)([], Int32, T, IComparer(T))

In short, I prefer the current monodoc Members view.

Given that, what's a decent language-agnostics way to show class members
AND method prototypes?  If we follow the .NET 3.5 () lead, we'd get
AsReadOnly(T)(T[]), which really helps no one.

So we either pick a language, e.g. C# (as we currently do), generating
AsReadOnly<T>(T[]), or we pick some other set of "enclosing" characters
to contain type parameters, e.g. (requires UTF-8):

	AsReadOnly?T?(T[]) : ReadOnlyCollection?T?

(using U+300C and U+300D to "quote" the type parameters), or maybe
re-use [] (I believe Nemerle does this):

	AsReadOnly[T](T[]) : ReadOnlyCollection[T]

In short, we have a trade-off between a more useful (as far as I'm
concerned) "show all overloads in the Members page" AND use a sensible
set of characters to distinguish between type paramters and actual
parameters, vs. a more language-agnostic "only show the Member name, and
display overloads in a separate page," and in the separate page use ()
to enclose *both* type parameters AND method parameters.

 - Jon



From mkestner at novell.com  Sun Dec  9 23:07:15 2007
From: mkestner at novell.com (Mike Kestner)
Date: Sun, 09 Dec 2007 22:07:15 -0600
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <1197206070.5512.26.camel@PenguinGuiness.WhosNet>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
	<1196637869.27459.22.camel@t61p.site>
	<1196814496.30973.56.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712050038x1a05d7eeobfe84979fcf8cd1@mail.gmail.com>
	<1196857248.6795.17.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712090411k34a065aata7f6b1cee59b2109@mail.gmail.com>
	<1197206070.5512.26.camel@PenguinGuiness.WhosNet>
Message-ID: <1197259635.27459.154.camel@t61p.site>


On Sun, 2007-12-09 at 13:14 +0000, Alvaro Ramirez wrote:

> > So, once it gets in gnome-sharp, the check
> > should be GTKHTML_SHARP_3_X instead of GTKHTML_SHARP_3_14.

The check needs to be for gtkhtml-sharp-3.14.pc, since the API won't
likely get committed back to gtkhtml-sharp-2.0 where gtkhtml-3.0 through
3.12 are bound.  There's already a 3.14 check in place though, from when
I did the print rework.

> Anyone I should ping to get the patch in gnome-desktop-sharp?

Your updated patch had some issues, like incorrect versions in the
paths, and it also appeared that you hand-edited the .raw file which is
not allowed.  Hand-edits would be lost the next time the parser is run.

I committed a patch to gnome-desktop-sharp tonight which uses metadata
to do the renaming and stripping of the Engine prefixes from the method
names.  It's on svn revision r91026.  I'm pretty sure it's the way your
patch suggested, but you might want to verify that.

Thanks for the patch.

-- 
Mike Kestner <mkestner at novell.com>


From mario.sopena at gmail.com  Mon Dec 10 04:36:48 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Mon, 10 Dec 2007 10:36:48 +0100
Subject: [Mono-docs-list] Differences between generic names in the
	documentation.
In-Reply-To: <1197242825.4065.23.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
	<1197242825.4065.23.camel@lina.magi.jprl.com>
Message-ID: <ef36f55f0712100136q15212242lfc7d34e7c783ddd3@mail.gmail.com>

Hi,

On 10/12/2007, Jonathan Pryor <jonpryor at vt.edu> wrote:
> On Sat, 2007-12-08 at 11:03 -0500, Jonathan Pryor wrote:
>
> In short, we have a trade-off between a more useful (as far as I'm
> concerned) "show all overloads in the Members page" AND use a sensible
> set of characters to distinguish between type paramters and actual
> parameters, vs. a more language-agnostic "only show the Member name, and
> display overloads in a separate page," and in the separate page use ()
> to enclose *both* type parameters AND method parameters.
>
>  - Jon

my opinion is to stay as it is now for several reasons:

* The agnostic solution is just ugly (like esperanto, it wont work
because is not good enough for everybody)

* C# is the primary development language for Mono and almost everybody
programs in C# or, at least, understands C#. Besides that, all the
examples in the documentation are only in C# so we have already a
C#-ish documentation.

* In the future, as other languages take more specific weight, we can
add a "Language" menu that will translate generic, examples and
everything that needs to be done to be more language XX friendly.

Mario

From valentin.sawadski at gmx.de  Mon Dec 10 11:57:30 2007
From: valentin.sawadski at gmx.de (Valentin Sawadski)
Date: Mon, 10 Dec 2007 17:57:30 +0100
Subject: [Mono-docs-list] Differences between generic names in
	the	documentation.
In-Reply-To: <ef36f55f0712100136q15212242lfc7d34e7c783ddd3@mail.gmail.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
	<1197242825.4065.23.camel@lina.magi.jprl.com>
	<ef36f55f0712100136q15212242lfc7d34e7c783ddd3@mail.gmail.com>
Message-ID: <1197305850.10885.8.camel@pi1536.local>

Hello,

On Mon, 2007-12-10 at 10:36 +0100, Mario Sopena Novales wrote:
> * C# is the primary development language for Mono and almost everybody
> programs in C# or, at least, understands C#. Besides that, all the
> examples in the documentation are only in C# so we have already a
> C#-ish documentation.

By the way I think it should be pretty easy to extend monodocer to
generate <TypeSignature /> and <MemberSignature /> tags for different
languages. (Like MS does within their docs) This could probably be done
by using Mono.Addins so that 3rd party language developers could also
integrate their language to the docs. (Especially Boo, VB.NET and
Nemerle)

Kind Regards,
Valentin Sawadski


From valentin.sawadski at gmx.de  Mon Dec 10 12:12:40 2007
From: valentin.sawadski at gmx.de (Valentin Sawadski)
Date: Mon, 10 Dec 2007 18:12:40 +0100
Subject: [Mono-docs-list] Differences between generic names in
	the	documentation.
In-Reply-To: <1197129783.5871.81.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
Message-ID: <1197306760.13224.1.camel@pi1536.local>

Hello,

On Sat, 2007-12-08 at 11:03 -0500, Jonathan Pryor wrote: 
> You have a point that "<" and ">" are rather C# specific, so
> following .NET 3.5 and using '(' and ')' might be an acceptable
> compromise (again, if you care that much; personally, I don't have a
> problem with using '<' and '>').  For reasons stated above, I do NOT wnt
> to use Foo`N notation in the shell.
> 
> Furthermore, since you can "overload" types based on the number of
> generic type parameters, not using <>/()/[]/etc. to enclose type
> parameters either results in name ambiguities (if you only show what's
> before the '`', as .NET 2.0 docs do), or requires the use of `N
> notation.  Consider:
> 
> 	delegate R Func<R> ();
> 	delegate R Func<R,P> (P p);
> 	delegate R Func<R,P1,P2> (P1 p1, P2 p2);
> 
> Which results in Func`1, Func`2, and Func`3, vs. Func<R>, Func<R,P>, and
> Func<R,P1,P2> (or replace <> with () or something else).  I find the
> latter far preferable.

This is right for the way a user sees this.

However I was also thinking of the name inside the xml-File and I
believe that it would be better to use the `N variant within the
xml-File because this would prevent the "&lgt;"-Parsing or bugs ins the
class browser and it's probably also better for the commandline-version
of the doc browser to type System.Collections.Generic.Dictionary`2 then
System.Collections.Generic.Dictionary<TKey, TValue>.

But it's true that Dictionary<TKey, TValue> is nicer to see for a
(C#)-user of the documentation.

Kind Regards,
Valentin Sawadski


From jonpryor at vt.edu  Mon Dec 10 13:56:31 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Mon, 10 Dec 2007 13:56:31 -0500
Subject: [Mono-docs-list] Differences between generic names in
	the	documentation.
In-Reply-To: <1197306760.13224.1.camel@pi1536.local>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
	<1197306760.13224.1.camel@pi1536.local>
Message-ID: <1197312991.4065.53.camel@lina.magi.jprl.com>

On Mon, 2007-12-10 at 18:12 +0100, Valentin Sawadski wrote:
> On Sat, 2007-12-08 at 11:03 -0500, Jonathan Pryor wrote: 
> > Consider:
> > 
> > 	delegate R Func<R> ();
> > 	delegate R Func<R,P> (P p);
> > 	delegate R Func<R,P1,P2> (P1 p1, P2 p2);
> > 
> > Which results in Func`1, Func`2, and Func`3, vs. Func<R>, Func<R,P>, and
> > Func<R,P1,P2> (or replace <> with () or something else).  I find the
> > latter far preferable.
> 
> However I was also thinking of the name inside the xml-File and I
> believe that it would be better to use the `N variant within the
> xml-File because this would prevent the "&lgt;"-Parsing or bugs ins the
> class browser and it's probably also better for the commandline-version
> of the doc browser to type System.Collections.Generic.Dictionary`2 then
> System.Collections.Generic.Dictionary<TKey, TValue>.

Yes, and no.

In some contexts, the `N variant is already used, in particular in
index.xml //Type/@Name uses the `N variant.

Then there's the individual Type.xml files, which is more problematic,
for two reasons:

 1. I'm trying to maintain compatibility with the CLILibraryTypes.xml
    document included with ECMA-335.  This permits easier importing of
    the standardized documentation whenever it changes, and this 
    documentation format does not use `N.

    This impacts e.g. //ReturnType and //Parameter/@Type, among 
    other internal elements.

 2. Many non-`N uses will be due to user-generated comments, 
    e.g. under //Docs, in particular for the //see/@cref attribute.
    The construction of this value is documented in ECMA-334 (C#
    Standard) Annex E (Documentation Comments):

        The cref attribute can be attached to any tag to provide a
        reference to a code element....   For code elements that contain
        code that uses generics, the normal generics syntax, for
        instance List<T>, cannot be used because it produces invalid
        XML.  Instead, curly brraces can be used, such as <see
        cref="List{T}"/>, or the normal XML escape syntax &lt; and &gt;
        for instance as in List&lt;T&gt;.

(2) is particularly important, not just because it's ALSO used in the
imported ECMA docs, but also because `monodocer -importslashdoc` imports
`CSC /doc`-formatted files (e.g. for 3rd party documentation).

So what you want to do -- simplify the XML contents so to minimize the
docbrowser parsing "burden" -- simply isn't acceptable.  Requiring it
would either require "munging" all of these references on import, or
kill the current import functionality.

Munging in import also won't fix any instances where people manually
edit the XML files (as I frequently do), and the ability to "fully
reference" generic types is quite helpful in documentation; consider:

        public class Dictionary<TKey,TValue> {
            /// <returns>A <see cref="IEnumerable{TKey}"/>.</returns>
                public IEnumerable<TKey> Keys {get {return null;} }
        }

In this case, it's "nice" to see IEnumerable{TKey} as the link instead
of IEnumerable`1 to help reinforce the specialization of this generic
type.

 - Jon



From jonpryor at vt.edu  Mon Dec 10 14:04:22 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Mon, 10 Dec 2007 14:04:22 -0500
Subject: [Mono-docs-list] Differences between generic names
	in	the	documentation.
In-Reply-To: <1197305850.10885.8.camel@pi1536.local>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
	<1197242825.4065.23.camel@lina.magi.jprl.com>
	<ef36f55f0712100136q15212242lfc7d34e7c783ddd3@mail.gmail.com>
	<1197305850.10885.8.camel@pi1536.local>
Message-ID: <1197313462.4065.62.camel@lina.magi.jprl.com>

On Mon, 2007-12-10 at 17:57 +0100, Valentin Sawadski wrote:
> By the way I think it should be pretty easy to extend monodocer to
> generate <TypeSignature /> and <MemberSignature /> tags for different
> languages. (Like MS does within their docs) This could probably be done
> by using Mono.Addins so that 3rd party language developers could also
> integrate their language to the docs. (Especially Boo, VB.NET and
> Nemerle)

This should currently be pretty trivial -- just create a subclass of
MemberFormatter for your particular language and call your new formatter
in "the appropriate places."  This could be done much easier, but the
fact that we currently already have an abstraction in place to generate
these signature strings helps immensely.

Using Mono.Addins is also an interesting idea, though I'm not sure how
useful it would be.  The reason being that <TypeSignature/> and
<MemberSignature/> are generated at `monodocer` runtime, and the system
that `monodocer` is run on may not have the plugins you desire.

What would make more sense -- though I have no idea how easy this would
be -- is to alter the docbrowser to use Mono.Addins and have an XML ->
signature addin for each language.  We'd likely need to extend the XML
syntax further -- we have a <TypeParameter/> element but it's only used
at class level, and it should likely be inserted at member level as well
for generic methods -- but this would allow users to install addins on
their local machine and have the XML signatures translated "on-the-fly"
to their desired language.

The downside is that the XML contains C#-formatted type names (see other
message for reasons why this won't change), so this effectively requires
a C# -> language translator as well in some circumstances, but for the
basics of member name, method parameters, type parameters, etc., this is
all readily extractable from the XML.

 - Jon



From jonpryor at vt.edu  Mon Dec 10 15:12:01 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Mon, 10 Dec 2007 15:12:01 -0500
Subject: [Mono-docs-list] Proposing a new documentation subsystem
In-Reply-To: <1196046344.30453.24.camel@lina.magi.jprl.com>
References: <1195896955.4040.33.camel@pi1536.local>
	<474823B8.3050706@occams.info> <1195917391.4039.19.camel@pi1536.local>
	<1195932307.4588.43.camel@lina.magi.jprl.com>
	<1195995363.4777.38.camel@pi1536.local>
	<1196000927.30453.15.camel@lina.magi.jprl.com>
	<1196046344.30453.24.camel@lina.magi.jprl.com>
Message-ID: <1197317521.4065.65.camel@lina.magi.jprl.com>

On Sun, 2007-11-25 at 22:05 -0500, Jonathan Pryor wrote:
> Attached is a preliminary patch to add this support.  The monodocer
> change is 66 lines, and generates output like the attached
> Environment.xml.  monodocs2html has also been updated; Environment.html
> is the current output.
> 
> I should stress that this is a work-in-progress; in particular, it
> should (but doesn't) "garbage-collect" the <AssemblyVersion/> elements,
> such that if updated assembly 2.0, and a member has an
> <AssemblyVersion>2.0</AssemblyVersion> element AND the element has been
> REMOVED, the docs are not currently updated to remove this element.
> Similar things should be done to ONLY remove a member if e.g. there are
> no remaining <AssemblyVersion/> elements (which would likely obsolete
> the -ignore_extra_docs parameter if done well).

This has been committed to monodoc-HEAD, complete with support for
"garbage collecting" <AssemblyVersion/> elements on repeated invocations
of monodocer against different assembly versions (thus removing the need
for both -since and -ignore_extra_docs).

 - Jon



From aramirez at xenodium.com  Mon Dec 10 15:18:03 2007
From: aramirez at xenodium.com (Alvaro Ramirez)
Date: Mon, 10 Dec 2007 20:18:03 +0000
Subject: [Mono-docs-list] monodoc search bar
In-Reply-To: <1197259635.27459.154.camel@t61p.site>
References: <1196619998.11992.39.camel@PenguinGuiness.WhosNet>
	<1196637869.27459.22.camel@t61p.site>
	<1196814496.30973.56.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712050038x1a05d7eeobfe84979fcf8cd1@mail.gmail.com>
	<1196857248.6795.17.camel@PenguinGuiness.WhosNet>
	<ef36f55f0712090411k34a065aata7f6b1cee59b2109@mail.gmail.com>
	<1197206070.5512.26.camel@PenguinGuiness.WhosNet>
	<1197259635.27459.154.camel@t61p.site>
Message-ID: <1197317883.8655.4.camel@PenguinGuiness.WhosNet>

Hi Mike,

On Sun, 2007-12-09 at 22:07 -0600, Mike Kestner wrote:
> On Sun, 2007-12-09 at 13:14 +0000, Alvaro Ramirez wrote:
> 
> > > So, once it gets in gnome-sharp, the check
> > > should be GTKHTML_SHARP_3_X instead of GTKHTML_SHARP_3_14.
> 
> The check needs to be for gtkhtml-sharp-3.14.pc, since the API won't
> likely get committed back to gtkhtml-sharp-2.0 where gtkhtml-3.0 through
> 3.12 are bound.  There's already a 3.14 check in place though, from when
> I did the print rework.

Yup. Saw that. Piggybacked on that :)

> 
> > Anyone I should ping to get the patch in gnome-desktop-sharp?
> 
> Your updated patch had some issues, like incorrect versions in the
> paths, and it also appeared that you hand-edited the .raw file which is
> not allowed.  Hand-edits would be lost the next time the parser is run.

ah yeah. Wasn't too sure about that. First time doing it. Also saw the
raw file was checked in to the repository, which threw me off.

> 
> I committed a patch to gnome-desktop-sharp tonight which uses metadata
> to do the renaming and stripping of the Engine prefixes from the method
> names.  It's on svn revision r91026.  I'm pretty sure it's the way your
> patch suggested, but you might want to verify that.

cool. will use metadata in the future. Thanks!

Alvaro



From valentin.sawadski at gmx.de  Tue Dec 11 10:55:53 2007
From: valentin.sawadski at gmx.de (Valentin Sawadski)
Date: Tue, 11 Dec 2007 16:55:53 +0100
Subject: [Mono-docs-list] Differences between generic names
	in	the	documentation.
In-Reply-To: <1197313462.4065.62.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197129783.5871.81.camel@lina.magi.jprl.com>
	<1197242825.4065.23.camel@lina.magi.jprl.com>
	<ef36f55f0712100136q15212242lfc7d34e7c783ddd3@mail.gmail.com>
	<1197305850.10885.8.camel@pi1536.local>
	<1197313462.4065.62.camel@lina.magi.jprl.com>
Message-ID: <1197388553.3989.4.camel@pi1536.local>


On Mon, 2007-12-10 at 14:04 -0500, Jonathan Pryor wrote: 
> On Mon, 2007-12-10 at 17:57 +0100, Valentin Sawadski wrote:
> > By the way I think it should be pretty easy to extend monodocer to
> > generate <TypeSignature /> and <MemberSignature /> tags for different
> > languages. (Like MS does within their docs) This could probably be done
> > by using Mono.Addins so that 3rd party language developers could also
> > integrate their language to the docs. (Especially Boo, VB.NET and
> > Nemerle)
> 
> This should currently be pretty trivial -- just create a subclass of
> MemberFormatter for your particular language and call your new formatter
> in "the appropriate places."  This could be done much easier, but the
> fact that we currently already have an abstraction in place to generate
> these signature strings helps immensely.
> 
> Using Mono.Addins is also an interesting idea, though I'm not sure how
> useful it would be.  The reason being that <TypeSignature/> and
> <MemberSignature/> are generated at `monodocer` runtime, and the system
> that `monodocer` is run on may not have the plugins you desire.

That's what I've been thinking. Just to override MemberFormatter and
then using Mono.Addins to check at runtime which derived classes are
available to use them to generate the signatures.

Missing dependencies should not be a problem we would just have to ship
Mono.Addins and a couple of stock Formatters with monodoc. If users want
to use a different formatter they could add a additional addin into some
~/.config folder and Mono.Addins could load and use them as well.

This would be a pretty easy solution to enable multiple signatures
however this has the limitation that signatures are only created during
the creation of the documentation.

> What would make more sense -- though I have no idea how easy this would
> be -- is to alter the docbrowser to use Mono.Addins and have an XML ->
> signature addin for each language.  We'd likely need to extend the XML
> syntax further -- we have a <TypeParameter/> element but it's only used
> at class level, and it should likely be inserted at member level as well
> for generic methods -- but this would allow users to install addins on
> their local machine and have the XML signatures translated "on-the-fly"
> to their desired language.
> 
> The downside is that the XML contains C#-formatted type names (see other
> message for reasons why this won't change), so this effectively requires
> a C# -> language translator as well in some circumstances, but for the
> basics of member name, method parameters, type parameters, etc., this is
> all readily extractable from the XML.

I don't know much about how the browser parses his data but this is also
an alternative worth investigating. I'll probably look into both if I
have the time.

Kind Regards,
Valentin


From jonpryor at vt.edu  Wed Dec 12 05:57:27 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Wed, 12 Dec 2007 05:57:27 -0500
Subject: [Mono-docs-list] Differences between generic names in
	the	documentation.
In-Reply-To: <1197111874.3998.27.camel@pi1536.local>
References: <1197111874.3998.27.camel@pi1536.local>
Message-ID: <1197457047.10240.57.camel@lina.magi.jprl.com>

On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> But then again it seems that the browser uses the Test&lt;T&gt;
> everywhere. Sometimes it gets parsed and will be displayed as Test<T>
> but other times not and some ugly HTML-Entities are being shown as the
> class name.

After looking into this further, I *think* this is a GTKHTML rendering
bug.

What I -- and most people -- expect to happen when "&lt;" is used in
HTML is for '<' to be rendered instead.  (After all, it *is* the escape
character for '<'.)

However, GTKHTML only occasionally does this replacement -- when the
&lt; is NOT part of a link.  If it's used within an <a/> tag (either the
href attribute or the text itself) &lt; is NOT replaced with '<'.

You can see this via `monodoc 'M:System.Array.AsReadOnly<T>'` -- the
page title is correct ("System.Array.AsReadOnly<T> Method"), as is the
method prototype and inline text such as the "IList<T>" in the Remarks
section, but any instances of &lt; that are part of a link are NOT
properly translated.  I think it's GTKHTML because `monodoc --html`
doesn't have e.g. "&amp;lt;" for &lt; within links, but just &lt;, and
monodoc still displays "&lt;" instead of '<'.

This is bad, because it makes the most important pieces of text -- the
links -- look wrong.

I think when I first worked on Generics support in monodoc I was using
Gecko; unfortunately, it crashes instantly now, so that's not really an
option.

Furthermore, clicking on a link containing &lt; results in a Url
containing &lt;, which (as mentioned elsewhere) the monodoc engine
doesn't like -- it expects <> to be used.

I've just committed a fix to docbrowser so that GtkHtmlRenderer will
"correct" the URLs before it sends them to the core, so at least you can
now click on links to Generic types/methods and actually go somewhere,
but the rendering is still wrong, and I don't know how to fix that short
of fixing GTKHTML (argh!) or switching to Gecko (crash!).

 - Jon



From jonpryor at vt.edu  Wed Dec 12 08:01:08 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Wed, 12 Dec 2007 08:01:08 -0500
Subject: [Mono-docs-list] Differences between generic names
	in	the	documentation.
In-Reply-To: <1197457047.10240.57.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197457047.10240.57.camel@lina.magi.jprl.com>
Message-ID: <1197464468.10240.67.camel@lina.magi.jprl.com>

On Wed, 2007-12-12 at 05:57 -0500, Jonathan Pryor wrote:
> On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> > But then again it seems that the browser uses the Test&lt;T&gt;
> > everywhere. Sometimes it gets parsed and will be displayed as Test<T>
> > but other times not and some ugly HTML-Entities are being shown as the
> > class name.
> 
> After looking into this further, I *think* this is a GTKHTML rendering
> bug.

Perfect test case:

1. Start Monodoc.
2. Click File -> Lookup URL, or type Ctrl+L.
3. Enter the URL: <a href="foo.bar&lt;T&gt;">foo.bar&lt;T&gt;</a>

It displays as "foo.bar&lt;T&gt;" (i.e. no escaping is occurring), and
if you hold your mouse over the link the target is "foo.bar&lt;T&gt;".

You can in fact change the URL to be:

	<a href="foo.bar<T>">foo.bar&lt;T&gt;</a>

Despite being invalid XML (is it even valid HTML?), GTKHTML displays it,
and shows the desired target when you mouse over it (foo.bar<T>), but it
still shows "foo.bar&lt;T&gt;" as the link text.  I can't find any way
to get "foo.bar<T>" as the link text. :-/

(Not that a href of "foo.bar<T>" helps anyway, as that's invalid XML,
and thus cannot be used within the documentation.)

So it's definitely a GTKHTML bug; no idea how to fix it.  This has also
been reported:

	http://bugzilla.gnome.org/show_bug.cgi?id=340007
	http://bugzilla.gnome.org/show_bug.cgi?id=494315
	http://bugzilla.gnome.org/show_bug.cgi?id=498847

The latter two were opened in November of this year.  The first one also
seems applicable, and was opened in 2006.

Sounds like the actual solution is to get Gecko working again.  Anyone
know why it dies?

 - Jon



From valentin.sawadski at googlemail.com  Fri Dec 14 12:33:24 2007
From: valentin.sawadski at googlemail.com (Valentin Sawadski)
Date: Fri, 14 Dec 2007 18:33:24 +0100
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed
	generic types.
Message-ID: <1197653604.24204.0.camel@pi1536.local>

Hello,

this short patch makes all properly formatted and malformed links in the
docbrowser work. Please review it and apply if no one objects.

Kind Regards,
Valentin Sawadski
-------------- next part --------------
A non-text attachment was scrubbed...
Name: monodoc.diff
Type: text/x-patch
Size: 987 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071214/74af8592/attachment.bin 

From valentin.sawadski at googlemail.com  Fri Dec 14 14:22:40 2007
From: valentin.sawadski at googlemail.com (Valentin Sawadski)
Date: Fri, 14 Dec 2007 20:22:40 +0100
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed
	generic types.
Message-ID: <1197660160.24204.1.camel@pi1536.local>

Hello,

this short patch makes all properly formatted and malformed links in the
docbrowser work. Please review it and apply if no one objects.

[Sorry if I have sent this mail multiple times but I'm having
difficulties with my emails and subscriptions to the mono list right
now....]

Kind Regards,
Valentin Sawadski
-------------- next part --------------
A non-text attachment was scrubbed...
Name: monodoc.diff
Type: text/x-patch
Size: 987 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071214/46a616d4/attachment.bin 

From mario.sopena at gmail.com  Sat Dec 15 07:30:33 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Sat, 15 Dec 2007 13:30:33 +0100
Subject: [Mono-docs-list] Differences between generic names in the
	documentation.
In-Reply-To: <1197464468.10240.67.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197457047.10240.57.camel@lina.magi.jprl.com>
	<1197464468.10240.67.camel@lina.magi.jprl.com>
Message-ID: <ef36f55f0712150430h33a214b2ped72b979e1353bf1@mail.gmail.com>

Hi,


On 12/12/2007, Jonathan Pryor <jonpryor at vt.edu> wrote:
> On Wed, 2007-12-12 at 05:57 -0500, Jonathan Pryor wrote:
> > On Sat, 2007-12-08 at 12:04 +0100, Valentin Sawadski wrote:
> > > But then again it seems that the browser uses the Test&lt;T&gt;
> > > everywhere. Sometimes it gets parsed and will be displayed as Test<T>
> > > but other times not and some ugly HTML-Entities are being shown as the
> > > class name.
> >
> > After looking into this further, I *think* this is a GTKHTML rendering
> > bug.
>
> Perfect test case:
>
> 1. Start Monodoc.
> 2. Click File -> Lookup URL, or type Ctrl+L.
> 3. Enter the URL: <a href="foo.bar&lt;T&gt;">foo.bar&lt;T&gt;</a>
>
> It displays as "foo.bar&lt;T&gt;" (i.e. no escaping is occurring), and
> if you hold your mouse over the link the target is "foo.bar&lt;T&gt;".
>
> You can in fact change the URL to be:
>
>         <a href="foo.bar<T>">foo.bar&lt;T&gt;</a>
>
> Despite being invalid XML (is it even valid HTML?), GTKHTML displays it,
> and shows the desired target when you mouse over it (foo.bar<T>), but it
> still shows "foo.bar&lt;T&gt;" as the link text.  I can't find any way
> to get "foo.bar<T>" as the link text. :-/
>
> (Not that a href of "foo.bar<T>" helps anyway, as that's invalid XML,
> and thus cannot be used within the documentation.)
>
> So it's definitely a GTKHTML bug; no idea how to fix it.  This has also
> been reported:
>
>         http://bugzilla.gnome.org/show_bug.cgi?id=340007
>         http://bugzilla.gnome.org/show_bug.cgi?id=494315
>         http://bugzilla.gnome.org/show_bug.cgi?id=498847
>
> The latter two were opened in November of this year.  The first one also
> seems applicable, and was opened in 2006.
>

  I couldn't reproduce the problem with rendering generics you are
talking about. I think this is related to the version of gtkhtml. I've
noticed I only have the old gtkhtml-2.0 and, maybe, this is a issue
with 3.14 (I've seen the bugs you reported are related to the 3X
series). Could you try to compile with old libgtkhtml-2.0 and see If
the problem is still there?

Maybe we should stick with the old 2.0 gtkhtml; by the way I don't
know what exactly gives us the 3X series, nor why it was enabled by
default?

> Sounds like the actual solution is to get Gecko working again.  Anyone
> know why it dies?

Well, it seems related to a change in monodoc script "configuring"
something to get the gecko library. In the bug report
(https://bugzilla.novell.com/show_bug.cgi?id=341815) Wade points to a
change made on r81537 but I can not try it myself because I don't have
OpenSUSE. Does removing these two lines (which I don't think are so
much useful) fixes the problem for you?

Mario


>
>  - Jon
>
>
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list
>

From jonpryor at vt.edu  Sat Dec 15 08:45:03 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Sat, 15 Dec 2007 08:45:03 -0500
Subject: [Mono-docs-list] Differences between generic names in
	the	documentation.
In-Reply-To: <ef36f55f0712150430h33a214b2ped72b979e1353bf1@mail.gmail.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197457047.10240.57.camel@lina.magi.jprl.com>
	<1197464468.10240.67.camel@lina.magi.jprl.com>
	<ef36f55f0712150430h33a214b2ped72b979e1353bf1@mail.gmail.com>
Message-ID: <1197726303.4430.27.camel@lina.magi.jprl.com>

Mike: Didn't GtkHtml# always bind gtkhtml-3.0?  Or did it bind 2.x at
some point in time?

On Sat, 2007-12-15 at 13:30 +0100, Mario Sopena Novales wrote:
> On 12/12/2007, Jonathan Pryor <jonpryor at vt.edu> wrote:
> > Perfect test case:
> >
> > 1. Start Monodoc.
> > 2. Click File -> Lookup URL, or type Ctrl+L.
> > 3. Enter the URL: <a href="foo.bar&lt;T&gt;">foo.bar&lt;T&gt;</a>
> >
> > It displays as "foo.bar&lt;T&gt;" (i.e. no escaping is occurring), and
> > if you hold your mouse over the link the target is "foo.bar&lt;T&gt;".
>
>   I couldn't reproduce the problem with rendering generics you are
> talking about. I think this is related to the version of gtkhtml. I've
> noticed I only have the old gtkhtml-2.0 and, maybe, this is a issue
> with 3.14 (I've seen the bugs you reported are related to the 3X
> series). Could you try to compile with old libgtkhtml-2.0 and see If
> the problem is still there?

As far as I'm aware, Gtkhtml# has *always* bound the 3.x API, not the
2.x API.  In fact, 3.x and 2.x are NOT compatible (compare the output of
`nm -D libgtkhtml-2.so` to `nm -D libgtkhtml-3.14.so` and grep for "T",
which lists methods found within those libraries).

So I'm not sure how you could possibly be using Gtkhtml 2.0 with
Monodoc.

> > Sounds like the actual solution is to get Gecko working again.  Anyone
> > know why it dies?
> 
> Well, it seems related to a change in monodoc script "configuring"
> something to get the gecko library. In the bug report
> (https://bugzilla.novell.com/show_bug.cgi?id=341815) Wade points to a
> change made on r81537 but I can not try it myself because I don't have
> OpenSUSE. Does removing these two lines (which I don't think are so
> much useful) fixes the problem for you?

This has nothing to do with it, as seen by comment #2 which is a C
sample that reproduces the crash.

The actual patch you refer to allowed monodoc to *use* Gecko; it's the
actual use of Gecko which causes the crash.

 - Jon



From mkestner at novell.com  Sat Dec 15 10:21:34 2007
From: mkestner at novell.com (Mike Kestner)
Date: Sat, 15 Dec 2007 09:21:34 -0600
Subject: [Mono-docs-list] Differences between generic names
	in	the	documentation.
In-Reply-To: <1197726303.4430.27.camel@lina.magi.jprl.com>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197457047.10240.57.camel@lina.magi.jprl.com>
	<1197464468.10240.67.camel@lina.magi.jprl.com>
	<ef36f55f0712150430h33a214b2ped72b979e1353bf1@mail.gmail.com>
	<1197726303.4430.27.camel@lina.magi.jprl.com>
Message-ID: <1197732094.27459.260.camel@t61p.site>


On Sat, 2007-12-15 at 08:45 -0500, Jonathan Pryor wrote:
> Mike: Didn't GtkHtml# always bind gtkhtml-3.0?  Or did it bind 2.x at
> some point in time?

The gtkhtml-sharp-2.0.pc points to bindings of gtkhtml from versions
3.0.10 through 3.12.  When the API broke in 3.14, we had to change some
things, and now the gtkhtml-sharp-3.14.pc found in gnome-desktop-sharp
points to bindings for gtkhtml-3.14.pc.

That's probably the source of confusion.
-- 
Mike Kestner <mkestner at novell.com>


From mario.sopena at gmail.com  Sat Dec 15 10:30:57 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Sat, 15 Dec 2007 16:30:57 +0100
Subject: [Mono-docs-list] Differences between generic names in the
	documentation.
In-Reply-To: <1197732094.27459.260.camel@t61p.site>
References: <1197111874.3998.27.camel@pi1536.local>
	<1197457047.10240.57.camel@lina.magi.jprl.com>
	<1197464468.10240.67.camel@lina.magi.jprl.com>
	<ef36f55f0712150430h33a214b2ped72b979e1353bf1@mail.gmail.com>
	<1197726303.4430.27.camel@lina.magi.jprl.com>
	<1197732094.27459.260.camel@t61p.site>
Message-ID: <ef36f55f0712150730g4d6d74dfl28eaa9997fb45915@mail.gmail.com>

Hi,

On 15/12/2007, Mike Kestner <mkestner at novell.com> wrote:
>
> On Sat, 2007-12-15 at 08:45 -0500, Jonathan Pryor wrote:
> > Mike: Didn't GtkHtml# always bind gtkhtml-3.0?  Or did it bind 2.x at
> > some point in time?
>
> The gtkhtml-sharp-2.0.pc points to bindings of gtkhtml from versions
> 3.0.10 through 3.12.  When the API broke in 3.14, we had to change some
> things, and now the gtkhtml-sharp-3.14.pc found in gnome-desktop-sharp
> points to bindings for gtkhtml-3.14.pc.

Well, I never looked at the C library but just at how monodoc browser
pointed to gtkhtml-sharp-2.0 and gtkhtml-sharp-3.14 and that made me
think gtkhtml-sharp-2.0 pointed to a 2.X series.

Then, it seems a problem of libgtkhtml for 3.14 onwards?


>
> That's probably the source of confusion.
> --
> Mike Kestner <mkestner at novell.com>
>
>

From valentin.sawadski at googlemail.com  Fri Dec 14 12:13:13 2007
From: valentin.sawadski at googlemail.com (Valentin Sawadski)
Date: Fri, 14 Dec 2007 18:13:13 +0100
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed
	generic types.
Message-ID: <1197652393.22207.4.camel@pi1536.local>

Hello,

this short patch makes all properly formatted and malformed links in the
docbrowser work. Please review it and apply if no one objects.

Kind Regards,
Valentin Sawadski
-------------- next part --------------
A non-text attachment was scrubbed...
Name: monodoc.diff
Type: text/x-patch
Size: 987 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071214/ff66b33d/attachment.bin 

From valentin.sawadski at googlemail.com  Fri Dec 14 12:13:29 2007
From: valentin.sawadski at googlemail.com (Valentin Sawadski)
Date: Fri, 14 Dec 2007 18:13:29 +0100
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup of malformamed
	generic types.
Message-ID: <1197652409.22207.5.camel@pi1536.local>

Hello,

this short patch makes all properly formatted and malformed links in the
docbrowser work. Please review it and apply if no one objects.

Kind Regards,
Valentin Sawadski
-------------- next part --------------
A non-text attachment was scrubbed...
Name: monodoc.diff
Type: text/x-patch
Size: 987 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20071214/92e56eb6/attachment.bin 

From jonpryor at vt.edu  Tue Dec 18 09:31:19 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Tue, 18 Dec 2007 09:31:19 -0500
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup
	of	malformamed	generic types.
In-Reply-To: <1197652393.22207.4.camel@pi1536.local>
References: <1197652393.22207.4.camel@pi1536.local>
Message-ID: <1197988279.4430.54.camel@lina.magi.jprl.com>

On Fri, 2007-12-14 at 18:13 +0100, Valentin Sawadski wrote:
> this short patch makes all properly formatted and malformed links in the
> docbrowser work. Please review it and apply if no one objects.

This isn't necessary; I "fixed" GtkHtmlHtmlRender (in
mono-tools/docbrowser) to do the s/&lt;/</g and s/&gt;/>/g substitutions
(since this is in my mind a GtkHtml bug, in that it isn't properly
rendering/un-escaping XML entities).

I made the GtkHtmlHtmlRender change on Dec-12.

 - Jon



From valentin.sawadski at googlemail.com  Wed Dec 19 12:59:53 2007
From: valentin.sawadski at googlemail.com (Valentin Sawadski)
Date: Wed, 19 Dec 2007 18:59:53 +0100
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup
	of	malformamed	generic types.
In-Reply-To: <1197988279.4430.54.camel@lina.magi.jprl.com>
References: <1197652393.22207.4.camel@pi1536.local>
	<1197988279.4430.54.camel@lina.magi.jprl.com>
Message-ID: <1198087193.3987.6.camel@pi1536.local>

Hello Jonathan,

On Tue, 2007-12-18 at 09:31 -0500, Jonathan Pryor wrote:
> On Fri, 2007-12-14 at 18:13 +0100, Valentin Sawadski wrote:
> > this short patch makes all properly formatted and malformed links in the
> > docbrowser work. Please review it and apply if no one objects.
> 
> This isn't necessary; I "fixed" GtkHtmlHtmlRender (in
> mono-tools/docbrowser) to do the s/&lt;/</g and s/&gt;/>/g substitutions
> (since this is in my mind a GtkHtml bug, in that it isn't properly
> rendering/un-escaping XML entities).

I see your changes but they only worked for the MembersOverview page, as
far as I can tell.

See System.Array for example. If you click BinarySearch<T>(T[], T) in
the overview, everything works fine. When you then hover over the the
IComparable<T> link, the status-panel displays the right "URL" however
if you click it, you'll end up in the middle of nowhere again.

> 
> I made the GtkHtmlHtmlRender change on Dec-12.
> 
>  - Jon
> 
> 

Kind Regards,
Valentin


From jonpryor at vt.edu  Wed Dec 19 13:33:29 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Wed, 19 Dec 2007 13:33:29 -0500
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup
	of	malformamed	generic types.
In-Reply-To: <1198087193.3987.6.camel@pi1536.local>
References: <1197652393.22207.4.camel@pi1536.local>
	<1197988279.4430.54.camel@lina.magi.jprl.com>
	<1198087193.3987.6.camel@pi1536.local>
Message-ID: <1198089209.4430.66.camel@lina.magi.jprl.com>

On Wed, 2007-12-19 at 18:59 +0100, Valentin Sawadski wrote:
> On Tue, 2007-12-18 at 09:31 -0500, Jonathan Pryor wrote:
> > On Fri, 2007-12-14 at 18:13 +0100, Valentin Sawadski wrote:
> > > this short patch makes all properly formatted and malformed links in the
> > > docbrowser work. Please review it and apply if no one objects.
> > 
> > This isn't necessary; I "fixed" GtkHtmlHtmlRender (in
> > mono-tools/docbrowser) to do the s/&lt;/</g and s/&gt;/>/g substitutions
> > (since this is in my mind a GtkHtml bug, in that it isn't properly
> > rendering/un-escaping XML entities).
> 
> I see your changes but they only worked for the MembersOverview page, as
> far as I can tell.
> 
> See System.Array for example. If you click BinarySearch<T>(T[], T) in
> the overview, everything works fine. When you then hover over the the
> IComparable<T> link, the status-panel displays the right "URL" however
> if you click it, you'll end up in the middle of nowhere again.

I can't reproduce this.  What I'm doing:

1. Navigate to System.Array.BinarySearch<T>(T[],T).
2. Within the Right pane, Click the "IComparable&lt;T&gt;" link above
the prototype.

I'm then taken to IComparable<T> documentation.

 - Jon



From valentin.sawadski at googlemail.com  Wed Dec 19 13:43:23 2007
From: valentin.sawadski at googlemail.com (Valentin Sawadski)
Date: Wed, 19 Dec 2007 19:43:23 +0100
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup
	of	malformamed	generic types.
In-Reply-To: <1198089209.4430.66.camel@lina.magi.jprl.com>
References: <1197652393.22207.4.camel@pi1536.local>
	<1197988279.4430.54.camel@lina.magi.jprl.com>
	<1198087193.3987.6.camel@pi1536.local>
	<1198089209.4430.66.camel@lina.magi.jprl.com>
Message-ID: <1198089803.3398.3.camel@pi1536.local>

Hello Jonathan,

On Wed, 2007-12-19 at 13:33 -0500, Jonathan Pryor wrote:
> On Wed, 2007-12-19 at 18:59 +0100, Valentin Sawadski wrote:
> > On Tue, 2007-12-18 at 09:31 -0500, Jonathan Pryor wrote:
> > > On Fri, 2007-12-14 at 18:13 +0100, Valentin Sawadski wrote:
> > > > this short patch makes all properly formatted and malformed links in the
> > > > docbrowser work. Please review it and apply if no one objects.
> > > 
> > > This isn't necessary; I "fixed" GtkHtmlHtmlRender (in
> > > mono-tools/docbrowser) to do the s/&lt;/</g and s/&gt;/>/g substitutions
> > > (since this is in my mind a GtkHtml bug, in that it isn't properly
> > > rendering/un-escaping XML entities).
> > 
> > I see your changes but they only worked for the MembersOverview page, as
> > far as I can tell.
> > 
> > See System.Array for example. If you click BinarySearch<T>(T[], T) in
> > the overview, everything works fine. When you then hover over the the
> > IComparable<T> link, the status-panel displays the right "URL" however
> > if you click it, you'll end up in the middle of nowhere again.
> 
> I can't reproduce this.  What I'm doing:
> 
> 1. Navigate to System.Array.BinarySearch<T>(T[],T).
> 2. Within the Right pane, Click the "IComparable&lt;T&gt;" link above
> the prototype.
> 
> I'm then taken to IComparable<T> documentation.

This is very strange, because it does not work at my machine (rev
91596). Do you have any idea why it is not working for me, but for you?
(I'm not using Gecko to render the pages.)

Kind Regards,
Valentin


From jonpryor at vt.edu  Wed Dec 19 21:25:34 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Wed, 19 Dec 2007 21:25:34 -0500
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup
	of	malformamed	generic types.
In-Reply-To: <1198089803.3398.3.camel@pi1536.local>
References: <1197652393.22207.4.camel@pi1536.local>
	<1197988279.4430.54.camel@lina.magi.jprl.com>
	<1198087193.3987.6.camel@pi1536.local>
	<1198089209.4430.66.camel@lina.magi.jprl.com>
	<1198089803.3398.3.camel@pi1536.local>
Message-ID: <1198117534.4430.73.camel@lina.magi.jprl.com>

On Wed, 2007-12-19 at 19:43 +0100, Valentin Sawadski wrote:
> On Wed, 2007-12-19 at 13:33 -0500, Jonathan Pryor wrote:
> > I can't reproduce this.  What I'm doing:
> > 
> > 1. Navigate to System.Array.BinarySearch<T>(T[],T).
> > 2. Within the Right pane, Click the "IComparable&lt;T&gt;" link above
> > the prototype.
> > 
> > I'm then taken to IComparable<T> documentation.
> 
> This is very strange, because it does not work at my machine (rev
> 91596). Do you have any idea why it is not working for me, but for you?
> (I'm not using Gecko to render the pages.)

Did you update & install *both* monodoc/engine AND
mono-tools/docbrowser?

One of my recent fixes in monodoc/engine "fixes" "invalid" links that
were present in the imported ECMA documentation, invalid links of the
form "T: Namespace.Type" (note the space after the ':').

Clicking on these links would previously go to a nearly blank page
containing the only text of the link you just clicked.

An example of this is M:System.Array.AsReadOnly<T>, which in the summary
links to "T: System.Collections.Generic.IList&lt;T&gt;" (note the
space).

Is it possible that the links you're clicking which lead nowhere are of
this malformed type?

Thanks,
 - Jon



From jonpryor at vt.edu  Wed Dec 19 21:52:04 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Wed, 19 Dec 2007 21:52:04 -0500
Subject: [Mono-docs-list] What to do about types in the root namespace?
Message-ID: <1198119124.4430.97.camel@lina.magi.jprl.com>

While trying to update the contents of monodoc/class, I ran into a
problem: Npgsql contains the following types in the root ("") namespace:
NpgsqlRowUpdatingEventArgs, and NpgsqlRowUpdatedEventArgs.

The problem is twofold:

1. monodocer generates an error and exits if it sees such a type.
2. What should Monodoc do with such a type?

Assuming that telling the Npgsql authors to rename their types is
undesirable, we need a way to support types in the root namespace.

These aren't intractable problems, but the solution isn't entirely clear
to me either.

For (1), monodoc could do one of the following (alternatives desired):

a. Place the types into a 'Global' directory, e.g.
assembly-name/en/Global/NpgsqlRowUpdatingEventArgs.xml.

Problem: what if someone actually uses a 'Global' namespace?

b. Don't care, and write the file
assembly-name/en/NpgsqlRowUpdatingEventArgs.xml (i.e. use "" as the
namespace).

This should work, as you can't have a namespace and type with the same
name within a given assembly.

HOWEVER, it's quite possible to spit the monodocer output of multiple
assemblies into the same directory; in fact, this is currently done in
monodoc/class, spitting the output of the assemblies nunit.core,
nunit.framework, nunit.mocks, and nunit.util into the nunit directory.

Consequently, if assembly A has a namespace Foo, and assembly B has a
type Foo, and you request monodocer to generate output for both
assemblies into the same directory, the Foo.xml file would be clobbered,
containing whichever assembly was most recently documented.

We could just say "Don't Do That," and be done with it. :-)

Solution (b) is my preference.

Then there's question (2), which I find harder to solve: what should
Monodoc do with these types?

Currently, the tree of monodoc assumes that all types have namespaces --
"Class Library" has namespace sub-nodes, which contain actual type
sub-nodes:

  + Class Library
    + System
      + Array
        + Methods
          - AsReadOnly<T>

Where should types in the root namespace be placed?  As siblings of the
namespace nodes?

  + Class Library
    + System
      + Array
        + Methods
          - AsReadOnly<T>
    - RootNamespaceType Class

As children of a "Global" namespace?

  + Class Library
    + System
      + Array
        + Methods
          - AsReadOnly<T>
    + Global
      - RootNamespaceType Class

Something else?

Note that the "parent tree" has some say over how logical the choice is.
The "Class Library", "Gnome Libraries", etc. nodes are spread across
multiple namespaces, so any type in the root namespace may be far away
from the types it should be used with.

On the other hand, the "Various" node has more subdivisions:

  + Various
    + NUnit Libraries
      + NUnit.Framework
        + Assert Class

So any types in the root namespace may be closer to the types they're
likely to be used with.

Then there's the issue of monodoc internals: iirc, many portions assume
that there is a namespace within the Fully Qualified Type Name, and use
string manipulation operations to extract the namespace.  What happens
when the namespace is, rightfully, ""?  I have no idea.

Thoughts?

Thanks,
 - Jon




From m.j.hutchinson at gmail.com  Wed Dec 19 22:02:24 2007
From: m.j.hutchinson at gmail.com (Michael Hutchinson)
Date: Wed, 19 Dec 2007 22:02:24 -0500
Subject: [Mono-docs-list] What to do about types in the root namespace?
In-Reply-To: <1198119124.4430.97.camel@lina.magi.jprl.com>
References: <1198119124.4430.97.camel@lina.magi.jprl.com>
Message-ID: <aec34c770712191902k60c570a0x8c7a5ef69068e524@mail.gmail.com>

On Dec 19, 2007 9:52 PM, Jonathan Pryor <jonpryor at vt.edu> wrote:
> While trying to update the contents of monodoc/class, I ran into a
> problem: Npgsql contains the following types in the root ("") namespace:
> NpgsqlRowUpdatingEventArgs, and NpgsqlRowUpdatedEventArgs.
>
> The problem is twofold:
>
> 1. monodocer generates an error and exits if it sees such a type.
> 2. What should Monodoc do with such a type?
>
> Assuming that telling the Npgsql authors to rename their types is
> undesirable, we need a way to support types in the root namespace.
...
> We could just say "Don't Do That," and be done with it. :-)

Putting types in the root namespaces sounds to me like a Bad Thing,
violating naming guidelines etc. IMO this isn't something that MonoDoc
should care about -- if anything, it should throw an error (as it
does) or ignore them.

-- 
Michael Hutchinson
http://mjhutchinson.com

From mario.sopena at gmail.com  Thu Dec 20 02:57:56 2007
From: mario.sopena at gmail.com (Mario Sopena Novales)
Date: Thu, 20 Dec 2007 08:57:56 +0100
Subject: [Mono-docs-list] What to do about types in the root namespace?
In-Reply-To: <aec34c770712191902k60c570a0x8c7a5ef69068e524@mail.gmail.com>
References: <1198119124.4430.97.camel@lina.magi.jprl.com>
	<aec34c770712191902k60c570a0x8c7a5ef69068e524@mail.gmail.com>
Message-ID: <ef36f55f0712192357j20c82e3ej37fa04849a45cf9@mail.gmail.com>

Hi,

   what about printing a big warning saying those classes A,B and C
won't be documented because they are not contained in a Namespace and
ignoring them when writing the documentation?

Mario

On 20/12/2007, Michael Hutchinson <m.j.hutchinson at gmail.com> wrote:
> On Dec 19, 2007 9:52 PM, Jonathan Pryor <jonpryor at vt.edu> wrote:
> > While trying to update the contents of monodoc/class, I ran into a
> > problem: Npgsql contains the following types in the root ("") namespace:
> > NpgsqlRowUpdatingEventArgs, and NpgsqlRowUpdatedEventArgs.
> >
> > The problem is twofold:
> >
> > 1. monodocer generates an error and exits if it sees such a type.
> > 2. What should Monodoc do with such a type?
> >
> > Assuming that telling the Npgsql authors to rename their types is
> > undesirable, we need a way to support types in the root namespace.
> ...
> > We could just say "Don't Do That," and be done with it. :-)
>
> Putting types in the root namespaces sounds to me like a Bad Thing,
> violating naming guidelines etc. IMO this isn't something that MonoDoc
> should care about -- if anything, it should throw an error (as it
> does) or ignore them.
>
> --
> Michael Hutchinson
> http://mjhutchinson.com
> _______________________________________________
> Mono-docs-list maillist  -  Mono-docs-list at lists.ximian.com
> http://lists.ximian.com/mailman/listinfo/mono-docs-list
>

From valentin.sawadski at googlemail.com  Thu Dec 20 06:19:07 2007
From: valentin.sawadski at googlemail.com (Valentin Sawadski)
Date: Thu, 20 Dec 2007 12:19:07 +0100
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup
	of	malformamed	generic types.
In-Reply-To: <1198117534.4430.73.camel@lina.magi.jprl.com>
References: <1197652393.22207.4.camel@pi1536.local>
	<1197988279.4430.54.camel@lina.magi.jprl.com>
	<1198087193.3987.6.camel@pi1536.local>
	<1198089209.4430.66.camel@lina.magi.jprl.com>
	<1198089803.3398.3.camel@pi1536.local>
	<1198117534.4430.73.camel@lina.magi.jprl.com>
Message-ID: <1198149547.3996.2.camel@pi1536.local>

Hello,

On Wed, 2007-12-19 at 21:25 -0500, Jonathan Pryor wrote:
> On Wed, 2007-12-19 at 19:43 +0100, Valentin Sawadski wrote:
> > On Wed, 2007-12-19 at 13:33 -0500, Jonathan Pryor wrote:
> > > I can't reproduce this.  What I'm doing:
> > > 
> > > 1. Navigate to System.Array.BinarySearch<T>(T[],T).
> > > 2. Within the Right pane, Click the "IComparable&lt;T&gt;" link above
> > > the prototype.
> > > 
> > > I'm then taken to IComparable<T> documentation.
> > 
> > This is very strange, because it does not work at my machine (rev
> > 91596). Do you have any idea why it is not working for me, but for you?
> > (I'm not using Gecko to render the pages.)
> 
> Did you update & install *both* monodoc/engine AND
> mono-tools/docbrowser?

Yes. I made a full update of monodoc and the mono-tool package.

> 
> One of my recent fixes in monodoc/engine "fixes" "invalid" links that
> were present in the imported ECMA documentation, invalid links of the
> form "T: Namespace.Type" (note the space after the ':').
> 
> Clicking on these links would previously go to a nearly blank page
> containing the only text of the link you just clicked.
> 
> An example of this is M:System.Array.AsReadOnly<T>, which in the summary
> links to "T: System.Collections.Generic.IList&lt;T&gt;" (note the
> space).
> 
> Is it possible that the links you're clicking which lead nowhere are of
> this malformed type?

No, I checked the console output, it prints:

Trying: T:System.IComparable<T>
+----------------------------------------------+
| Here we should locate the provider for the   |
| link.  Maybe using this document as a base?  |
| Maybe having a locator interface?   The short|
| urls are not very useful to locate types     |
+----------------------------------------------+

Kind Regards,
Valentin


From jonpryor at vt.edu  Thu Dec 20 07:17:23 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Thu, 20 Dec 2007 07:17:23 -0500
Subject: [Mono-docs-list] [PATCH] Fix to enable lookup
	of	malformamed	generic types.
In-Reply-To: <1198149547.3996.2.camel@pi1536.local>
References: <1197652393.22207.4.camel@pi1536.local>
	<1197988279.4430.54.camel@lina.magi.jprl.com>
	<1198087193.3987.6.camel@pi1536.local>
	<1198089209.4430.66.camel@lina.magi.jprl.com>
	<1198089803.3398.3.camel@pi1536.local>
	<1198117534.4430.73.camel@lina.magi.jprl.com>
	<1198149547.3996.2.camel@pi1536.local>
Message-ID: <1198153043.4430.100.camel@lina.magi.jprl.com>

On Thu, 2007-12-20 at 12:19 +0100, Valentin Sawadski wrote:
> > Is it possible that the links you're clicking which lead nowhere are of
> > this malformed type?
> 
> No, I checked the console output, it prints:
> 
> Trying: T:System.IComparable<T>
> +----------------------------------------------+
> | Here we should locate the provider for the   |
> | link.  Maybe using this document as a base?  |
> | Maybe having a locator interface?   The short|
> | urls are not very useful to locate types     |
> +----------------------------------------------+

What happens if you type Ctrl+L (File -> Lookup URL...) and enter
T:System.IComparable<T>?  Does that work, or does that error?

If it works, something very bizarre is going on, as clicking on a link
should be identical to typing that URL in the Lookup URL dialog.  If it
fails, something is horribly broken in your install, and I'd suggest
clearing out your current install and installing monodoc & doctools
"from scratch".

 - Jon



From jonpryor at vt.edu  Wed Dec 26 03:39:59 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Wed, 26 Dec 2007 03:39:59 -0500
Subject: [Mono-docs-list] [Mono-dev] Can not checkout trunk on windows
In-Reply-To: <47716040.4090405@lanwin.de>
References: <47716040.4090405@lanwin.de>
Message-ID: <1198658399.29665.11.camel@lina.magi.jprl.com>

On Tue, 2007-12-25 at 20:55 +0100, Steve Wagner wrote:
> Hi, currently i can not checkout the trunk on windows, because in
> "/monodoc/class/System.Security/en" are an file with name
> "System.Security.Cryptography.Xml" and an folder with the same name.
> 
> If i try to check out, ive allways get an "object of the same name
> already exists.

This implies that we'll need to change the directory layout "format"
produced by monodocer so that namespace XML files and the actual
namespace directories live in different locations.  Otherwise every
namespace that ends with "xml" (case-insensitive) will generate problems
on Windows and other case-insensitive platforms.

Suggestions?  All I can suggest is that namespace XML files should
contain some character/string that namespaces are highly unlikely to
contain, e.g. instead of "en/System.xml" for the XML documentation on
the System namespace, use "en/Namespace-System.xml".  Any such
character/string *must* be usable on Windows, so no ':' or similar
characters can be used.

Alternatively, namespace XML files can be placed into a separate
directory.  As long as no namespace can be confused with this directory,
there shouldn't be any ambiguity between type and/or namespace files,
e.g. using "en/Namespace-Docs/System.xml" for the XML documentation of
the System namespace.

Thoughts?

 - Jon



From miguel at novell.com  Wed Dec 26 10:32:54 2007
From: miguel at novell.com (Miguel de Icaza)
Date: Wed, 26 Dec 2007 10:32:54 -0500
Subject: [Mono-docs-list] [Mono-dev] Can not checkout trunk on windows
In-Reply-To: <1198658399.29665.11.camel@lina.magi.jprl.com>
References: <47716040.4090405@lanwin.de>
	<1198658399.29665.11.camel@lina.magi.jprl.com>
Message-ID: <1198683174.11168.172.camel@erandi.boston.ximian.com>


> Suggestions?  All I can suggest is that namespace XML files should
> contain some character/string that namespaces are highly unlikely to
> contain, e.g. instead of "en/System.xml" for the XML documentation on
> the System namespace, use "en/Namespace-System.xml".  Any such
> character/string *must* be usable on Windows, so no ':' or similar
> characters can be used.

We should add support for a different name like:

	ns-System.xml

And then we can rename the files for the docs that we maintain.

And keep the old code for documentation that might be out that has not
been updated by us.

Miguel

From mkestner at novell.com  Wed Dec 26 10:52:17 2007
From: mkestner at novell.com (Mike Kestner)
Date: Wed, 26 Dec 2007 09:52:17 -0600
Subject: [Mono-docs-list] [Mono-dev] Can not checkout trunk on windows
In-Reply-To: <1198683174.11168.172.camel@erandi.boston.ximian.com>
References: <47716040.4090405@lanwin.de>
	<1198658399.29665.11.camel@lina.magi.jprl.com>
	<1198683174.11168.172.camel@erandi.boston.ximian.com>
Message-ID: <1198684337.3102.17.camel@t61p.site>


On Wed, 2007-12-26 at 10:32 -0500, Miguel de Icaza wrote:
> > Suggestions?  All I can suggest is that namespace XML files should
> > contain some character/string that namespaces are highly unlikely to
> > contain, e.g. instead of "en/System.xml" for the XML documentation on
> > the System namespace, use "en/Namespace-System.xml".  Any such
> > character/string *must* be usable on Windows, so no ':' or similar
> > characters can be used.
> 
> We should add support for a different name like:
> 
> 	ns-System.xml
> 
> And then we can rename the files for the docs that we maintain.

An alternative might be to use a namespaces.xml file in the root node
which contains all the namespace summary docs for the directory.

-- 
Mike Kestner <mkestner at novell.com>