Re: [mono-packagers] monodoc & mcs/mono module merging

--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)
Content-type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Background: we'd the treeview to be generated at runtime, so that
distros don't need to patch monodoc.xml to add additional documentation
(without placing all additional documentation under the Various node).

This is doubly useful when we have projects like Gendarme looking to
integrate their documentation (see the gendarme google group), but the
patches I've seen for that _also_ involve monodoc.xml changes, so the
current monodoc.xml architecture hostile toward 3rd parties...

With luck, we can get this finished for Mono 2.2...

On Mon, 2008-10-20 at 23:18 -0400, Jonathan Pryor wrote:
> Consequently, I'm thinking of a slightly different track: drop Testing
> and Libraries as top-level nodes (leaving Languages, Programs/Tools, an=
d
> Various), and make all libraries top-level nodes:
>=20
>   - Base Class Library
>     - Namespaces [ System, etc. ]
>   - Gnome Libraries
>     - Namespaces [ Gtk, Gnome, etc. ]
> =EF=BB=BF  - Languages
>     - C#
>       - ...
>   - Mono Libraries
>     - Namespaces [ Mono.Posix, etc. ]
>   - NUnit Libraries
>     - Namespaces [ NUnit.Framework, etc. ]
>   - ...
>   - Tools
>     - Mono Development Tools
>       - Man pages
>     - MonoDevelop IDE
>     - ...
>   - Various
>=20
> Every layer should be alphabetized (otherwise you can't find anything).
> This is slightly less structured, but should still be ~straightforward
> to implement with the previously suggested /monodoc/node/@parent
> attribute.

Attached is a monodoc.dll patch and sample files to drive the treeview.

parent.patch adds support for the //node/@parent attribute, which allows
a //node element to specify the parent node to use "by name."

With that patch applied, you can use the new monodoc.xml (attached),
which is significantly smaller than before.  *.source files can now
provide additional structure to the tree view.

netdocs.source is a minimal example of adding a root "Base Class
Library" node, under which the normal "classlib" documentation is
displayed.

cs-errors.source creates a "C# / C# Compiler Error Reference" node under
the Languages node, while ecma334.source creates a "C# / C# Language
Specification" node under the Languages node.  Since cs-errors.source &
ecma334.source refer to intermediate nodes with the same name, they get
the same parent at runtime.

The result of patch + these new .source files is the default tree:

  - Base Class Library
  - Languages
    - C#
      - C# Compiler Error Reference
      - C# Language Specification

It's ~fully dynamic, so if any additional structure is desired by a 3rd
party, they can ~trivially add it.

Thoughts?

 - Jon


--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)
Content-type: text/x-patch; name=parent.patch; charset=utf-8
Content-transfer-encoding: 7BIT
Content-disposition: attachment; filename=parent.patch

Index: Monodoc/provider.cs
===================================================================
--- Monodoc/provider.cs	(revision 116332)
+++ Monodoc/provider.cs	(working copy)
@@ -339,7 +339,8 @@
 
 	public void Sort ()
 	{
-		nodes.Sort ();
+		if (nodes != null)
+			nodes.Sort ();
 	}
 
 	public string URL {
@@ -364,7 +365,15 @@
 
 	int IComparable.CompareTo (object obj)
 	{
-		Node other = (Node) obj;
+		Node other = obj as Node;
+		if (other == null)
+			return -1;
+
+		if (position < 0)
+			LoadNode ();
+		if (other.position < 0)
+			other.LoadNode ();
+
 		return String.CompareOrdinal(caption, other.caption);
 	}
 }
@@ -851,6 +860,7 @@
 				foreach (Node n in hs.Tree.Nodes){
 					parent.AddNode (n);
 				}
+				parent.Sort ();
 			}
 		}
 		
@@ -869,6 +879,9 @@
 		// Clean the tree
 		PurgeNode(root);
 
+		// Sort the top 3 levels of the tree
+		root.Sort ();
+
 		return root;
 	}
 	
@@ -949,7 +962,14 @@
 	void Populate (Node parent, XmlNodeList xml_node_list)
 	{
 		foreach (XmlNode xml_node in xml_node_list){
-			XmlAttribute e = xml_node.Attributes ["label"];
+			XmlAttribute e = xml_node.Attributes ["parent"];
+			if (e != null && name_to_node.ContainsKey (e.InnerText)) {
+				Node p = (Node) name_to_node [e.InnerText];
+				xml_node.Attributes.Remove (e);
+				Populate (p, xml_node.SelectNodes ("."));
+				continue;
+			}
+			e = xml_node.Attributes ["label"];
 			if (e == null){
 				Console.Error.WriteLine ("`label' attribute missing in <node>");
 				continue;

--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)
Content-type: application/xml; name=monodoc.xml
Content-transfer-encoding: 7bit
Content-disposition: attachment; filename=monodoc.xml

<?xml version="1.0"?>
<node label="Mono Documentation" name="root">
  <node label="Languages" name="languages" />
  <node label="Testing" name="testing" />
  <node label="Tools" name="tools" />
  <node label="Various" name="various" />
</node>

--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)
Content-type: application/xml; name=cs-errors.source
Content-transfer-encoding: 7bit
Content-disposition: attachment; filename=cs-errors.source

<?xml version="1.0"?>
<monodoc>
  <node label="C#" name="lang-c#" parent="languages">
    <node label="C# Compiler Error Reference" name="cs-errors"/>
  </node>
  <source provider="error" basefile="cs-errors" path="cs-errors"/>
</monodoc>

--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)
Content-type: application/xml; name=ecma334.source
Content-transfer-encoding: 7bit
Content-disposition: attachment; filename=ecma334.source

<?xml version="1.0"?>
<monodoc>
  <node label="C#" name="lang-c#" parent="languages">
    <node label="C# Language Specification" name="ecmaspec"/>
  </node>
  <source provider="ecmaspec" basefile="ecma334" path="ecmaspec"/>
</monodoc>

--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)
Content-type: application/xml; name=netdocs.source
Content-transfer-encoding: 7bit
Content-disposition: attachment; filename=netdocs.source

<?xml version="1.0"?>
<monodoc>
  <node label="Base Class Library" name="classlib" parent="root" />
  <source provider="ecma" basefile="netdocs" path="classlib"/>
</monodoc>

--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
Mono-docs-list maillist  -  [email protected]
http://lists.ximian.com/mailman/listinfo/mono-docs-list

--Boundary_(ID_YDVM7+LesfBDhgEqu4i6lw)--