[Mono-docs-list] Man page support and Linking

[Jonathan Pryor]

On Tue, 2004-10-26 at 08:10, Joshua Tauberer wrote:
> Jonathan Pryor wrote:
> > 1.  Does monodoc support man pages yet?  If not, when will it?
> 
> It would only work in Unix, then.  Are the man pages licensed in such a 
> way as to allow their embedding in Monodoc?  That'd be easier, and it 
> would look nicer.

That wouldn't be a problem, as most of the Mono.Posix functionality
won't work under Windows (no getpwnam(3), etc.), unless you're running
under the POSIX environment (which likely *would* include man pages).

> The problem with having a man page provider is that, I think, every page 
> needs to correspond to a page in the table of contents, and so that 
> would require either having a list of man pages that Monodoc should 
> display in the TOC, or it would need to display all man pages in the TOC.

What I'm thinking is that we'd generate the normal stubs for the
Mono.Posix classes, so we'd have the standard tree view (Members,
Methods, etc.).  *Within* the documentation of a given method would be a
link to the man page, e.g.:

	This function wraps the POSIX function getpwnam(3).

	<a href="man:getpwnam(3)">See the getpwnam(3) man page for 
	details.</a>

Thus, the man page wouldn't be exposed in the tree view or the index,
but inside the method documentation itself.

> > 2.  Is it/will it be possible to link between the different sets of
> > providers?
> 
> Why doesn't it work now?  IIRC, the ECMA docs link between the docs with 
> <a href="T:..."/>...

I mean linking *between* providers.  For example, my "Managed and
Unmanaged Code Integration" guide in Monodoc uses the XHTML provider
(node: /Mono Documentation/Mono Handbook/Advanced
Topics/Interoperability/Platform Invoke).

Within my XHTML document I refer to the class library documentation:

	...create a <a href="T:System.Runtime.InteropServices.DllImport"
	>DllImport</a> function...

Which causes the XHTML provider to reference the ECMA provider.  Except
that this doesn't work; attempts to actually *follow* that link
generates an error:

        No stream for this node:
        html/en/wrapping/T:System.Runtime.InteropServices.DllImportAttribute with code (html/en/wrapping/T:System.Runtime.InteropServices.DllImportAttribute)

So cross-provider linking doesn't work as nicely as I'd like, as I would
*love* to be able to integrate content between the different providers,
but this doesn't seem to work (tested with Mono 1.0.x; HEAD might have
this fixed for all I know).

 - Jon