[Mono-docs-list] Documentation browser.

[Miguel de Icaza]

Hello guys,

   [ Executive summary: 

	A documentation browser for mono will have to integrate
	multiple file formats and multiple sources of information,
	so choosing an upfront format is not as important as it
	might seem.
   ]

   I have not shared this with anyone in public before, but I have
mentioned this to a few people on irc or over e-mail discussions, and I
figured it was worth posting this given the recent excitement over doing
documentation.

   We will need to produce a documentation browser that people can use
online while developing applications, and this probably should contain
at least as much information as the equivalent documentation browser
from Microsoft.

* The problem.

   The problem is that the documentation browser will need to provide
access to all the documentation in a uniform way, independently of the
source of the documentation, which might be very varied:

   There are a number of pieces that will be glued together here:

	* APIs
		* Mono C# API documentation (ECMA/XML format)
		* Mono C API documentation
		* Third party API documentation.
			* ECMA.XML format.
			* CSC XML format.

	* Reference
		* C# Compiler reference.
		* other compiler references.

	* Tutorials

	* Quickstarts

    The Mono C# API and some of the third party documentation will be
written using the ECMA.XML format (because it blends best for
translating it, and for reusing the existing documentation, and being
able to reuse "upgrades" as ECMA publishes them).  Some others will be
produced by NDoc/CSC.  

    On the other hand, compiler references will probably come from
exporting the ECMA C# documentation to some XML/HTML format;  Other
programming languages might use other file formats.

    Some tutorials will be in Docbook, some others in HTML, some
quickstarts might be on a simple text format.

* The documentation browser

    I want to see a documentation browser that can be browsed
taxonomically (and you could have multiple entry points if you want into
the same documentation node).

    I like two features about the MS documentation browser:

	* Tree-based taxonomy.
	* Incremental search on the index.
	* Topic search.

    To achieve the above UI, without having to mandate everyone to use a
uniform file format, I think we should produce a documentation browser
that can cope with multiple file formats.

    Each information source would register its "entry point" into the
documentation with a small file:

	<documentation name=".NET Framework">
		<name lang="en">.NET Framework Documentation</name>
		<name lang="es">Documentación de .NET</name>
		<node>/Reference</node>
		<provider name="MonoDoc.EcmaXmlProvider"/>
	</documentation>

    From the above file, the documentation browser would know that this
node (.NET Framework Documentation) has to be inserted into the
/Reference node and to get the children of this tree, it should use the
class MonoDoc.EcmaXmlProvider.

    Basically, we could have:

	interface DocumentationProvider {
		string GetNode (string uri);
		Tree   GetTree (string uri);
		void   GenerateIndex (IndexWriter output);
	}

    And then:

	class EcmaXmlProvider : DocumentationProvider
	
    It would be used like this:

	LoadTree (string uri)
	{
		provider = LookupProvider (uri);
		tree = provider.GetTree (uri);
	}

    The caller would invoke LoadTree for example when the user clicks on
"Reference" and then on ".NET Framework":

	LoadTree ("/Reference/.NET Framework");

    To load a particular document, say to get the documentation for the
`MaxValue' field of System.Int64, the code would do about the same
thing, for example:

	s = provider.GetNode ("/Reference/.NET Framework/System/Int64/Field/MaxValue");

    And the return value is a properly formed HTML document that can be
fed to the HTML rendering engine.

* Providers

    We could have a number of providers for the different kinds of
documentation:

	EcmaXmlProvider
		So we can reuse existing ECMA docs.  This would use
	  	the XSLT stylesheets that were contributed to render
		specific parts of it.

	SimpleHtmlProvider
		A provider for HTML documents, laid out on the file
		system.

	DocbookProvider
		Provides access to Docbook documents.

	CSCProvider
		Provides rendering of CSC/XML documents.

    The details about how the documents are stored is implementation
specific.  They could be stored in a compressed .ZIP file for all we
know.

* Index

    Each documentation blob will have to provide its own index file, and
it would be up to each provider to populate the Index information
(through the IndexWriter class) with relevant data.  This would be used
later by both the Index and the search facilities.

Miguel