mcs/tools/monodoc/ChangeLog

   1 2009-09-25  Jonathan Pryor  <jpryor@novell.com>
   2
   3         * Monodoc/ecma-provider.cs: Don't return 'null' from GetPublicUrl(),
   4           but instead provide a decent URL even if the url isn't to a single
   5           member, but instead to show all members, e.g. T:System.String/*.
   6         * Monodoc/provider.cs: Obsolete Node.URL.  It's too variable for sane
   7           use; use Node.PublicUrl.
   8
   9 2009-09-09  Jonathan Pryor  <jpryor@novell.com>
  10
  11         * Mono.Documentation/ManifestResourceResolver.cs: Allow it to lookup
  12           files located in multiple directories.  Needed so that 'mdoc
  13           export-html' can properly deal with multiple source directories.
  14
  15 2009-08-13  Jonathan Pryor  <jpryor@novell.com>
  16
  17         * Monodoc/provider.cs: Add a RootTree.AddSource(string) method, so that
  18           additional directories can be checked for .source file loading.
  19
  20 2009-08-13  Jonathan Pryor  <jpryor@novell.com>
  21
  22         * Monodoc/provider.cs: Make RootTree.LoadTree() just call
  23           RootTree.LoadTree(null), and move the .config-file parsing into
  24           .LoadTree(string) (for when basedir==null).  This will simplify the
  25           logic of monodoc, as we want to add the ability to monodoc to use
  26           any arbitrary directory, and this will remove the need to do
  27           `if (d==null) RootTree.LoadTree(); else RootTree.LoadTree(d)`.
  28           This also conforms to FxDG guidelines.
  29
  30 2009-08-12  Jonathan Pryor  <jpryor@novell.com>
  31
  32         * Resources/mdoc-html-format: Added; XSLT file to match
  33           "//format[@type='text/html']//*", to support "pass-through"
  34           semantics.  This allows you to use actual HTML within your
  35           documentation and have it visible to HTML-supporting output formats.
  36           WARNING: Use as a "last resort" -- this is primarily intended for
  37           importing existing HTML w/o needing lots of extra logic to convert
  38           into mdoc format XML first (with a corresponding loss of fidelity).
  39           However, it means that if (when) we get non-HTML output format
  40           support, the <format type="text/html" /> blocks WILL be skipped for
  41           that non-HTML output format.
  42
  43           For example, the forever-on-the-back-burner ROFF output support --
  44           to remove the use of lynx, as no one ever has it installed --
  45           wouldn't be able to support HTML format, so it would skip these
  46           <format type="text/html"/> blocks.
  47
  48           Consider <format /> the moral equivalent of Perl POD's
  49           '=begin formatname' block; see perlpod(1).
  50         * Resources/mdoc-html-utils.xsl: <xsl:import/> mdoc-html-format.xsl.
  51           It *must* be imported (NOT included) so that it will have a lower
  52           priority than other <template/>s, thus allowing the HTML formatter
  53           to <xsl:apply-templates/> which then use the "normal" rules.  This
  54           allows:
  55                 <format type="text/html">
  56                         <p><see cref="T:System.String" /></p>
  57                 </format>
  58           to work as expected.
  59         * Makefile: Add mdoc-html-format.xsl as a resource.
  60
  61 2009-04-16  Jonathan Pryor  <jpryor@novell.com>
  62
  63         * Monodoc/man-provider.cs: NEVER return a non-null string from
  64           HelpSource.GetText() unless *useful* content is being returned, as
  65           when non-null is returned RootTree.RenderUrl() assumes that the url
  66           was handled and won't try any other HelpSources.  In this case, we
  67           can (and do) have multiple ManHelpSources present, but since
  68           ManHelpSource.GetText() was returning "<html>url was null</html>",
  69           RootTree thought it was handled...when it wasn't.  Fix.
  70
  71 2009-04-16  Jonathan Pryor  <jpryor@novell.com>
  72
  73         * Monodoc/provider.cs: Overview: MonoDevelop loads monodoc.dll into
  74           it's own process, and spawns monodoc GUI into a separate process,
  75           then sends Node.URL values (obtained from the MonoDevelop process)
  76           to load the documentation into the monodoc GUI.  Problem:
  77           occasionally the requested documentation isn't loaded, but instead
  78           some completely unrelated documentation is shown instead.  This is
  79           because the Node.URL value contains HelpSource-dependent data, e.g.
  80           a Node.URL value of "ecma:0#Foo/" will specify the 1st file
  81           within...whatever HelpSource is first consulted by monodoc (which
  82           can vary between monodoc runs, the phase of the moon, etc.).
  83           Solution: Add a Node.PublicUrl property which returns _stable_ URLs
  84           which aren't specific to a given HelpSource.
  85           - Add Node.PublicUrl property, which delegates to
  86             Provider.GetPublicUrl(string), so that a Provider can generate a
  87             Provider-independent URL (if possible).
  88           - Print PublicUrl from Node.PrintTree().
  89           - Add RootTree.GetSupportedFormats(), RootTree.GetProvider()
  90             methods.
  91           - Make RootTree.GetHelpSource() public.
  92         * Monodoc/ecma-provider.cs: Add EcmaDoc.GetCref() method (generates an
  93           XML documentation //see/@cref value), override
  94           Provider.GetPublicUrl() (which will return cref's if possible).
  95
  96 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
  97
  98         * Monodoc/ecma-provider.cs: EcmaHelpSource.GetText() doesn't need to
  99           call GetCachedText() twice.
 100
 101 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
 102
 103         * Monodoc/provider.cs: Correct UseWebdocCache logic.
 104         * Monodoc/xhtml-provider.cs: Use GetCachedText().
 105
 106 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
 107
 108         * Monodoc/provider.cs: UseWebdocCache is a better name that
 109           IgnoreCache (considering that cache is disabled by default).
 110
 111 2009-04-15  Jonathan Pryor  <jpryor@novell.com>
 112
 113         * Monodoc/provider.cs:
 114           - Add HelpSource.IgnoreCache field, so that if the cache is present
 115             it will be ignored.  (Required by 'mdoc export-html-webdoc' so it
 116             gets "fresh" content to generate the cache, and by monodoc GUI as
 117             it can't use the cache'd HTML; cache'd HTML is for ASP.NET
 118             webdoc only.)
 119           - Alter the cache directory from e.g. sources/netdocs to
 120             sources/cache/netdocs (as defined by
 121             XmlDocUtils.GetCacheDirectory()).
 122           - Add HelpSource.GetCachedText() method which will return the
 123             contents of the cache for an id.
 124         * Monodoc/addins-provider.cs, Monodoc/ecma-provider.cs,
 125           Monodoc/error-provider.cs, Monodoc/man-provider.cs,
 126           Monodoc/simple-provider.cs: Use GetCachedText().
 127         * Mono.Documentation/XmlDocUtils.cs: Add GetCacheDirectory(),
 128           GetCacheFileName() methods.
 129
 130 2009-04-14  Jonathan Pryor  <jpryor@novell.com>
 131
 132         * Monodoc/provider.cs: Fix NullReferenceException in 'mdoc dump-tree'.
 133
 134 2009-04-09 Gonzalo Paniagua Javier <gonzalo@novell.com>
 135
 136         * ecma-provider.cs: remove 'using'.
 137         * provider.cs: if there's a directory with the base name, read the
 138         files from there instead of from the .zip file.
 139
 140 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
 141
 142         * Monodoc/ecma-provider.cs: Viewing type members (plural, e.g. the
 143           Fields sub-node) would result in a stack overflow within
 144           Resources/mdoc-html-utils.xsl:GetInheritedMembers(), because the
 145           document() XSLT function was being used to obtain the base type's
 146           documentation.  It stack overflowed because the XmlUrlResolver was
 147           being used, which when given e.g. file:///DocAttribute.xml, would
 148           return file:///DocAttribute.xml (which makes sense), but it was
 149           non-terminating.  (I find this troubling as it should have been
 150           trying to resolve e.g. System.Attribute, not DocAttribute; it must
 151           be some XmlTransform-fu that was substituting documents.)
 152           The fix is for EcmaUncompiledHelpSource to provide an alternate
 153           document XmlResolver, one which always returns null from
 154           XmlResolver.ResolveUri(), thus preventing endless recursion.
 155
 156 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
 157
 158         * Mono.Documentation/XmlDocUtils.cs: It's possible for the `loader'
 159           delegate to return `null' if no further base types are found, so
 160           stop processing if we find a null base type.
 161         * Monodoc/provider.cs:
 162           - Make GetHelpStream() virtual so that EcmaUncompiledHelpSource can
 163             override it, as the default zip-based behavior is inappropriate.
 164           - Make GetHelpXmlWithChanges() virtual so that
 165             EcmaUncompiledHelpSource can override it, as the default zip-based
 166             behavior is inappropriate.
 167           - When initializing UncompiledHelpSources, set the
 168             HelpSource.RootTree property (avoids an NRE from
 169             EcmaHelpSource.GetTextFromUrl() when it reads RootTree.HelpSources).
 170         * Monodoc/ecma-provider.cs:
 171           - Within the XmlDocUtils.AddExtensionMethods() call, don't always
 172             prefix the type with "T:", as sometimes the type will already start
 173             with "T:", which is the case with EcmaUncompiledHelpSource ids.
 174           - Add EcmaUncompiledHelpSource.GetHelpStream() and
 175             EcmaUncompiledHelpSource.GetHelpXmlWithChanges(), which Do The
 176             Right Thing for the file-based backend.
 177
 178 2009-03-01  Jonathan Pryor  <jpryor@novell.com>
 179
 180         * Monodoc/ecma-provider.cs: For some reason,
 181           EcmaHelpSource.GetNamespaceDocument() wasn't being used anymore,
 182           which is what EcmaUncompiledHelpSource overrides to permit loading
 183           of local files.  Result: an exception when trying to view namespaces
 184           of local (non-assembled) directories.  Oops.  "Fixes" 443508.
 185
 186 2009-02-26  Jonathan Pryor  <jonpryor@vt.edu>
 187
 188         * Monodoc/provider.cs: Revert; Don't check for Tree.Nodes == null, as it
 189           happens in numerous places.  Instead, take a page out of the "I
 190           never should have invented `null'" book, and ensure that Tree.Nodes
 191           can never be null.  This fixes the "HelpSource has 0 items" issue
 192           and several other related ones.
 193
 194 2009-02-26  Jonathan Pryor  <jonpryor@vt.edu>
 195
 196         * Monodoc/provider.cs: It's possible for a HelpSource to have 0
 197           elements (which can be done by e.g. running `mdoc assemble' on an
 198           empty directory), in which case HelpSource.Tree.Nodes will be null.
 199           Make sure that we don't get a NullReferenceException.
 200           Patch thanks to Theerud Lawtrakul.  Fixes #443699.
 201
 202 2009-02-25  Jonathan Pryor  <jonpryor@vt.edu>
 203
 204         * Makefile:
 205           - s/TEST_FILES/MAN_TEST_FILES/g: $(TEST_FILES) is used by the normal
 206             build process, so the local definition is lost (and thus ignored).
 207             Result: Test/* isn't actually copied.  Oops.  Changing to
 208             MAN_TEST_FILES allows things to be copied.
 209           - Fix the filenames within $(MAN_TEST_FILES) so `make dist-local'
 210             works without error.
 211           - Fixes #479753.
 212
 213 2009-02-09  Jonathan Pryor  <jonpryor@vt.edu>
 214
 215         * Makefile: Don't include mono-ecma-css.js as a resource.
 216         * Monodoc/ecma-provider.cs: Insert helper.js, not mono-ecma-css.js.
 217         * Monodoc/provider.cs: Surround the contents of `helper.js' with a
 218           <script/> block so that valid HTMl is generated.
 219         * Resources/helper.js: Remove <script/> block, so that `helper.js' is an
 220           actual JavaScript file, not an SGML file w/ JavaScript content.
 221         * Resources/mono-ecma-css.js: Remove; use Resources/helper.js instead.
 222
 223 2009-01-05  Jonathan Pryor  <jonpryor@vt.edu>
 224
 225         * Makefile: Fix $(the_lib) dependencies so that monodoc.dll is rebuilt
 226           when one of Resources/* is modified.
 227         * Resources/mdoc-html-utils.xsl: Rework the Requirements block so that
 228           it doesn't require //AssemblyInfo or //AssemblyVersion.  This allows
 229           `mdoc update -fno-assembly-versions ...`-produced XML to still
 230           produce HTML with a Requirements section (skipping the Assembly
 231           Versions block but generating the Namespace and Assembly blocks).
 232           Change the behavior of //since generation so that instead of
 233           printing out a note before the method summary, a Since block is added
 234           to the Requirements section, and the Since block contains the
 235           //since/@version text.  All this to make Mike Kestner happier. :-)
 236
 237 2008-10-29  Jonathan Pryor  <jonpryor@vt.edu>
 238
 239         * Monodoc/xhtml-provider.cs: Use HelpSource.Message(), not
 240           Console.WriteLine().
 241
 242 2008-10-28  Jonathan Pryor  <jonpryor@vt.edu>
 243
 244         * Monodoc/provider.cs: Add HelpSource.InlineCss and
 245           HelpSource.InlineJavaScript virtual properties, so that the help
 246           source can provide specific CSS and JavaScript to be included into
 247           the generated HTML document.  This is used by the ASP.NET front-end,
 248           as it needs to insert the CSS & JavaScript separately (as it also
 249           inserts its own CSS & JavaScript).
 250         * Monodoc/ecma-provider.cs, Monodoc/ecmaspec-provider.cs,
 251           Monodoc/error-provider.cs: Override InlineCss & InlineJavaScript, as
 252           appropriate.
 253
 254 2008-10-24  Jonathan Pryor  <jonpryor@vt.edu>
 255
 256         * Monodoc/addins-provider.cs, Monodoc/ecma-provider.cs,
 257           Monodoc/ecmaspec-provider.cs, Monodoc/error-provider.cs,
 258           Monodoc/man-provider.cs, Monodoc/monohb-provider.cs,
 259           Monodoc/provider.cs: Remove Console.WriteLine() spew; helps cleanup
 260           `make` output in mcs/docs (from `mdoc assemble`, which indirectly
 261           invokes most of the *-provider files).  We solve this problem by
 262           providing a TraceLevel-based message system, so that messages are
 263           only generated if they are less than or equal to the requested
 264           output level (thus skipping the more verbose "every file" messages
 265           from ecma-provider.cs & error-provider.cs).
 266         * provider.cs: Change Node.CompareTo() to use a "natural sorting"
 267           algorithm -- this allows the C# Language Specification nodes to
 268           continue being displayed in the correct order.
 269
 270 2008-10-21  Jonathan Pryor  <jonpryor@vt.edu>
 271
 272         * Monodoc/provider.cs:
 273           - Fix Node.Sort() so that it doesn't NRE if nodes == null.
 274           - Fix Node.CompareTo() so that it can sort Nodes that haven't been
 275             loaded yet.
 276           - Add "libraries" as an alias for "root", so that .source files can
 277             refer to the parent "libraries" (which would allow us to change
 278             the location of "libraries" in the future, should we want to).
 279           - If a /monodoc/source/@path refers to a nonexistant node, then
 280             insert the contents under Various instead of ignoring it.
 281           - Sort the top-level nodes.
 282           - Sort the `parent` node after inserting children under it.  This
 283             allows multiple different .source files to insert nodes under the
 284             same parent node and still have the child nodes sorted as most
 285             mortals would expect.
 286           - Support a //node/@parent attribute, which allows for creating
 287             nodes underneath the specified parent node.  This allows multiple
 288             different .source files to contribute to the tree and depend upon
 289             each other.  Thus, instead of having a single monodoc.xml file
 290             that needs to know the entire tree in advance, the entire tree can
 291             be spread across multiple .source files and filled at runtime.
 292
 293 2008-10-18  Jonathan Pryor  <jonpryor@vt.edu>
 294
 295         * Makefile $(LIBRARY_PACKAGE): Set to `monodoc`, as we historically
 296           have had a monodoc package (and thus should preserve it).
 297
 298 2008-10-17  Jonathan Pryor  <jonpryor@vt.edu>
 299
 300         * Makefile: Distribute monodoc.dll.config.in.
 301
 302 2008-10-17  Jonathan Pryor  <jonpryor@vt.edu>
 303
 304         * Makefile: Generate a monodoc.dll.config (installed by gacutil), so
 305           that monodoc.dll can find the documentation sources.
 306
 307 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 308
 309         * Mono.Documentation/ManifestResourceResolver.cs,
 310           Mono.Documentation/XmlDocUtils.cs: Make types public so that they
 311           can be used from ../mdoc/mdoc.exe.
 312
 313 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 314
 315         * Makefile: Update $(thisdir).
 316
 317 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 318
 319         * Assmbly/AssemblyInfo.cs: Change location of mono.snk (since the
 320           monodoc directory was moved from mcs/class to mcs/tools).
 321
 322 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 323
 324         * Makefile: Improve `make clean` support.
 325
 326 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 327
 328         * Makefile: Add EXTRA_DISTFILES; monodoc.dll should depend upon
 329           Makefile (in case the /resource: lines change); shorten the .gif
 330           resource names.
 331
 332 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 333
 334         * Test (svn:ignore): Ignore generated files.
 335         * Makefile: Add tests for man-provider.
 336
 337 2008-10-16  Jonathan Pryor  <jonpryor@vt.edu>
 338
 339         * ChangeLog: Added/Started.
 340         * Makefile: Added; build monodoc.dll.
 341