This project has moved. For the latest updates, please go here.

Using it: Observations 1

Dec 29, 2009 at 8:33 AM

Hello,
I have spent the past two days testing and studying this tool so as to integrate
it into my Sandcastle Assist project. 

My conclusion is that it is a very useful tool and well designed. My initial observation
of limitations are due to the fact that I was not applying the Sandcastle Styles, I do not
apply the Sandcastle Styles to the Sandcastle installations, since my own build tools use
the styles in any specified directory.

Besides features I may desire, which could be considered later, the main problem with
the current release is the MAML output generated. I could fixed them for my own copy,
but it will mean keeping a copy different from the main, and I have done this enough already :)

I wish we could discuss some of these issues and fix them.
For illustrations, the  ff. is the introduction tag generated for an element in a schema...

<introduction>
     <ddue:para xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
	<documentation xmlns="http://www.w3.org/2001/XMLSchema">
           The year element describes the year associated with a particular copyright.
	</documentation>
    </ddue:para>
    <markup>
        <p />
        <b>Namespace:</b>
        <a href="/html/c06b9120-0a8b-a170-718e-3227bd547fde.htm">
http://ddue.schemas.microsoft.com/authoring/2003/5</a> <br/> <b>Schema:</b> <a href="/html/182938c3-4594-0c08-bad4-1a8c82a36f2f.htm">inlineCommon.xsd</a> <br/> </markup> </introduction>

In general, the para tag generated is not valid. The externalLink tag can easily be used to provide the content
of the above markup tag, if the normal topic link tag is not applicable here. Also, I am not sure there is a need
for the /html/ in the href attribute, since all the generated HTML files will be in the same directory.
Moreover, the markup tag, must be enclosed in a para tag. 

Please can be work together to fix these problems?

Thanks for the great work and the contributions to the Sandcastle tool box.

Best regards,
Paul. 

Coordinator
Feb 10, 2010 at 2:36 PM
Edited Feb 10, 2010 at 2:38 PM

Hi Paul,

sorry for the late answer but I am in the middle of my diploma thesis...

My conclusion is that it is a very useful tool and well designed.

Thank you very much! That is always a nice thing to hear :-)

Besides features I may desire, which could be considered later, the main problem with the current release is the MAML output generated.

I am aware of that. Some of them are in fact bugs but some of the markup ouput has been done deliberately.

In general, the para tag generated is not valid.

Thanks, that is truely a bug in the standard XSL transform that converts the xsd:documentation element. I fixed it with changeset 40435.

Moreover, the markup tag, must be enclosed in a para tag.

This is a bug as well. Fixed with changeset 40438.

The externalLink tag can easily be used to provide the content of the above markup tag, if the normal topic link tag is not applicable here. Also, I am not sure there is a need for the /html/ in the href attribute, since all the generated HTML files will be in the same directory.

Yes, in theory this markup:

<para>
   <markup>
        <b>Namespace:</b>
        <a href="/html/c06b9120-0a8b-a170-718e-3227bd547fde.htm">
            http://ddue.schemas.microsoft.com/authoring/2003/5</a>
        <br/>
        <b>Schema:</b>
        <a href="/html/182938c3-4594-0c08-bad4-1a8c82a36f2f.htm">inlineCommon.xsd</a>
        <br/>
    </markup>
</para>

could be replaced by pure MAML markup like this:

<para>
    <legacyBold>Namespace:</legacyBold>
    <link xlink:href="c06b9120-0a8b-a170-718e-3227bd547fde" />
</para>

<para>
    <legacyBold>Schema:</legacyBold>
    <link xlink:href="182938c3-4594-0c08-bad4-1a8c82a36f2f" />
</para>

However, this has minor visual glitch. The distance between the namespace and the schema link is the same as the distance between the in summary and the namespace link. Thus it destroys the visual grouping.

My idea was to make it look exactly as in the regular class library documentation. One could also imagine emitting this markup:

<para>
    <legacyBold>Namespace:</legacyBold>
    <link xlink:href="c06b9120-0a8b-a170-718e-3227bd547fde" />
    <markup><br/></markup>
    <legacyBold>Schema:</legacyBold>
    <link xlink:href="182938c3-4594-0c08-bad4-1a8c82a36f2f" />
</para>

but I am not sure if it really makes a difference.

The other area where I emit the a markup element instead of using pure MAML is the "Children" table. Due to the fact that XSD Doc also shows the combinators xsd:all, xsd:choice, xsd:sequence the list of possible child elements in fact constitutes a tree. Since MAML does not provide a built-in way for representing trees (let alone tree tables) I simply solved it by indenting the rows using HTML's non-breaking space character (XML entity markup for &nbsp; is &#160;). It must be non-breaking because you certainly do not want line breaks within the indentation. Unfortunately, this also requires the image and text for the entire first cell to be emitted purely as raw markup because you also do not want to have line breaks between the image and the text.

The same is true for the simple content model because here you can also use various combinators such as restrictions, facets, extensions, unions.

I would be happy to replace that by pure MAML markup but I see no way to accomplish that.

One could also imaging that XSD Doc does not emit MAML but an intermediate XML representation that has one file per topic and contains all the necessary information. This XML could then be translated to HTML. Doing so XSD Doc could use any HTML construct possible and still provide a semantic, valid XML representation. However, this has a huge draw back: one would have to provide output style dependent transformation. But that is exactly what I tried to avoid by emitting MAML in the first place...

Finally a few words on MAML schema validation in general.

Right now, SHFB (as well as XSD Doc) treat the MAML markup element as a last resort mechansim where we pass HTML directly to the output. However, you should be aware that this is not the intention of that element. We are just using it that way because it works. From the MAML documentation:

The markup element describes a string of markup, such as TeX or XML.

You will also find that the type of the markup element is defined as textType (which is basically just a normalized string). So according to the MAML schema this element does not allow any child elements.

Even worse, the MAML schemas have not been designed with extensibility in mind. That means that at every point in the schema it only allows a set of well-known elements from the MAML namespace. One could mitigate this problem by adding xsd:any elements at the right points in the schema (such as inlineType and sectionContentType) so that Sandcastle build components can extend the schema with their own inline and block type elements. For example, XSD Doc provides the new xmlEnityReference element which would be extension of inlineType.

Due to these restrictions it is currently impossible to validate MAML topic files against the MAML schema (at least not without losing a whole bunch of features).

Are you trying to parse the MAML output of XSD Doc or why is it that you require them to be valid MAML?

Best,
Immo

Feb 10, 2010 at 3:50 PM

Hello Immo,

Thanks for the reply. I have moved away from this feature to work on other parts, since there was no response - I did not know you are working on your thesis. 

I will find time to reply to the other parts of the post, but this is an answer to your last question, which will explain why I was looking into the valid MAML generation.

>>Immo: ...or why is it that you require them to be valid MAML?

I expect two uses of your library,

  1. the current approach you are using in the SHFB, where the XSD Docs will always be generated.
  2. as an immediate tool where the generated MAML is further customized and/or edited by the user.

For the second case, the valid MAML will be required. Most schema are fixed, and will hardly change over time, like the schema for specifications. Some are well-annotated, some never annotated and some partially annotated.
For instance, the reflection schema in Sandcastle is not annotated, and it will be better in this case to have an "empty" MAML documentation to edit and compile rather than directly annotating the schema, which is not yours for documentations.

Even though you are adding extensions to the annotations, most will not modify their current annotations to support them, so again being able to edit the generated MAML will be useful.

Now, I know most are currently using invalid MAML and in SHFB, but when the SHFB is finally integrated into VS.NET, the users will not be able to take advantage of the IntelliSense for auto-completion, because it does not work with invalid XML. They will have to fix the errors, which will be a whole work.

In the Sandcastle model, you can easily extend the MAML features with the custom components, even MS is doing the same thing. Sometimes it might be a less inconvenient syntax, as I have done to support both inline and displayed equations (with or without equations numbers) using the only available <math/> tag in my math component. Since you are creating custom component too, you can exploit that extensively instead of extending the MAML schema.

BTW, the more extension is added to MAML, the more difficult it will be for Dave and others working on WYSIWYG MAML Editor to get it right.

Please take your time to complete the thesis, it is more important. I wish you God's guidance and wisdom (sorry, if you do not believe in God).

Best regards,
Paul. 

Feb 10, 2010 at 7:53 PM

The MAML extensions are part of the Sandcastle Styles patch, not SHFB, so they are available to anyone using Sandcastle alone or with any third party front end.  To be complete, the MAML schemas used by Sandcastle should also be updated to include the extensions and should be distributed with the patch so that they are a matched set.  It's something I've got on the To Do list but haven't gotten to yet.

Eric

 

 

Feb 11, 2010 at 1:56 AM

Eric,

If your post is a response to my posting stating invalid MAML in SHFB, then take note that is not about the extensions added by the Sandcastle Styles, where with the exception of the <cite> introduced by Dave, I do not see any real point of MAML extensions.

Most of the invalid MAML has to do with your tool itself. For instance, if you click the ordered, bullet and table toolbar items on your MAML editor, the following templates are generated

 

<list class="ordered">
  <listItem>Item 1</listItem>
  <listItem>Item 2</listItem>
</list>

<list class="bullet">
  <listItem>Item 1</listItem>
  <listItem>Item 2</listItem>
</list>

<table>
  <tableHeader>
    <row>
      <entry>Header 1</entry>
      <entry>Header 2</entry>
    </row>
  </tableHeader>
  <row>
    <entry>Column 1</entry>
    <entry>Column 2</entry>
  </row>
</table>

Can you see that all these are invalid MAML, and for that matter all those using your tool for editing may so far have created invalid MAML documents?

Also, though I have not yet pointed that out, the XSDDocs generates a similar code too.

Best regards,
Paul. 

 

Feb 11, 2010 at 2:59 AM

I assume you're referring to the lack of <para> elements around the <listItem> and <entry> content.  Sandcastle doesn't care if they're there or not and I don't see them as being absolutely necessary.  You can use them if you need multiple paragraphs in the elements in question but they'll render just fine without them.  It's no different than an <li> or <td> element in HTML.  As far as adherence to the schema, I'm more inclined to follow Sandcastle's usage of the elements.  If the transformations need it, it's required.  If not, it's optional.

Eric

 

Feb 11, 2010 at 3:21 AM

>>Eric Sandcastle doesn't care if they're there or not and I don't see them as being absolutely necessary.

I think the topic here is valid MAML, if that is not an issue for you, then I do not see what your first post is about.

Best regards,
Paul. 

Coordinator
Feb 11, 2010 at 10:45 AM
Edited Feb 11, 2010 at 10:46 AM

Hi Paul,

SelormeyPaul wrote:
Thanks for the reply. I have moved away from this feature to work on other parts, since there was no response - I did not know you are working on your thesis.

That is fine. I still feel sorry - I could have notified you earlier about my lack of time right now...

SelormeyPaul wrote:

I expect two uses of your library,

  1. the current approach you are using in the SHFB, where the XSD Docs will always be generated.
  2. as an immediate tool where the generated MAML is further customized and/or edited by the user.

To be honest, I do not think that the second approach provides the best user experience as it is very hard (if not impossible) to update the schema without risking loosing modifications.

SelormeyPaul wrote:
For the second case, the valid MAML will be required. Most schema are fixed, and will hardly change over time, like the schema for specifications. Some are well-annotated, some never annotated and some partially annotated. For instance, the reflection schema in Sandcastle is not annotated, and it will be better in this case to have an "empty" MAML documentation to edit and compile rather than directly annotating the schema, which is not yours for documentations.

I see your point. However, you might find it easier to use a feature of XSD Doc to solve this problem: external documentation. XSD Doc does not care how you document your schemas. The easiest way (as it is a standard means of XML schema) is of course inline documentation using the xs:documenation element.

<xs:element name="myElement" type="xs:string">
<xs:annotation>
<xs:documentation>
This is documentation for myElement that will be used by both Visual Studio as well as
XML Schema Documenter.
</xs:documentation>
</xs:annotation>
</xs:element>

The downside of this element is that is not meant for structured content -- only for simple text. XML Schema also provides an element for structured content: xs:appinfo. XSD Doc provides the xsd:schemaDoc Element to put MAML content directly in the schema file:

<xs:element name="myElement" type="xs:string">
<xs:annotation>
<xs:appinfo>
<schemaDoc xmlns="http://schemas.xsddoc.codeplex.com/schemaDoc/2009/3"
xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
<ddue:summary>
<ddue:para>
This is the summary description.
</ddue:para>
</ddue:summary>
<ddue:remarks>
<ddue:content>
<ddue:para>
This is the remarks section for myElement. As you can see
both sections may contain any legal MAML markup.
</ddue:para>
</ddue:content>
</ddue:remarks>
</schemaDoc>
</xs:appinfo>
</xs:annotation>
</xs:element 

Right now, the only supported elements are summary, remarks, and examples. For a future release I am planning to support arbitrary sections as well.

For the use case you mentioned it would in fact be better to keep the documentation separate from the schema files. This is supported by the feature called external documenation. In that case, the documenation is contained in one or more additional XML files. The structure of those files is similar to those files created by the C# compiler:

<doc xmlns="http://schemas.xsddoc.codeplex.com/schemaDoc/2009/3"
xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
<namespace>
<name>http://schema.example.com</name>
</namespace>
<members>
<member uri="E/rootElement/childElement1">
<ddue:summary>
<ddue:para>
This is the summary information for <ddue:codeInline>childElement1</ddue:codeInline>.
</ddue:para>
</ddue:summary>
<ddue:remarks>
<ddue:content>
<ddue:para>
This is a deeper discussion about <ddue:codeInline>childElement1</ddue:codeInline>.
</ddue:para>
<ddue:para>
You also might want to have a look at
<xmlEntityReference>http://schema.example.com#E/rootElement/childElement2</xmlEntityReference>.
</ddue:para>
</ddue:content>
</ddue:remarks>
</member>
</members>
</doc 

As the structure suggests, you can place as many member elements in that file as you want to. In the extreme, you can put all the documenation in a single file or every piece of documenation in a separate file. In general, I would opt for a balanced approach, e.g. put the documenation for an entire element and all of its attributes in a single file.

The help file that ships with XSD Doc contains detailed discussions about both inline as well as external documentation.

SelormeyPaul wrote:
Now, I know most are currently using invalid MAML and in SHFB, but when the SHFB is finally integrated into VS.NET, the users will not be able to take advantage of the IntelliSense for auto-completion, because it does not work with invalid XML. They will have to fix the errors, which will be a whole work.

I agree. In addition, as VS will automatically validate the XML file against the schema (as long as VS can find the schema files) people will most likely force themselfs to fix the errors. I guess most errors are in fact done by accident and not intentional.

SelormeyPaul wrote:
In the Sandcastle model, you can easily extend the MAML features with the custom components, even MS is doing the same thing. Sometimes it might be a less inconvenient syntax, as I have done to support both inline and displayed equations (with or without equations numbers) using the only available tag in my math component. Since you are creating custom component too, you can exploit that extensively instead of extending the MAML schema.

Here I am not sure whether got you right. In fact, XSD Doc has a Sandcastle build component that is used to expand my MAML extension xmlEntityReference into the standard MAML link element.

I think one of the most important aspects of MAML is that it designed to encapsulate semantics rather than formatting. In theory, you could imagine getting rid of all the different elements that are basically links (such as link, externalLink, and codeEntityReference) and replace all of the by a single link element (such as HTML's anchor element). But this has the big downside of loosing information and being forced to know the final topic ID. The cool thing with specific links, such as codeEntityReference is that the tool knows that this is meant to refer to a managed code element. Therefore it can validate it. In addtion, this makes reading documentation markup easier as it is certainly easier to figure out what

<codeEntityReference>T:System:String</codeEntityReference>

refers to than

<link xlink:href="fb47fb06-5700-4502-be2c-2975dd68cae3" />

That is exactly why I introduced the xmlEntityReference element as a MAML schema extension: it raises the level of abstraction. And since this element is expanded into a standard MAML link element by a build component it is independent of the style Sandcastle is used with.

I think that MAML schema extensions are not a thing that should be avoided. But I think we as a community should provide them in a consistent and maintainable way. For example, Eric has created an awesome extension to the code element that provides syntax highlighting. This feature did not require any changes to the code element. It is just a build component that processes a standard MAML element differently. However, he also added features such as embedding the code from a file by specifying a file name and (optionally) a region. Since this information must be encoded somewhere the most natural way would be to extend the MAML schema. Unfortunately, Eric has simply added a few attributes to the standard MAML code element that now also live in the MAML namespace. I understand that it was the most appealing implementation but in the long run that makes the MAML unwieldy when everybody adds new elements and attributes to standard MAML elements. It also has the risk of choosing colliding names and could make certain plug-ins incompatible to each other.

That is the reason why my xmlEntityReference does not reside in the MAML namespace but in http://schemas.xsddoc.codeplex.com/schemaDoc/2009/3. This also has the benefit that it gives users a hint which extension is required to process this MAML extension.

For example, Eric could have implemented the code embedding in a new element (such as embeddCode) that resides in an SHFB specific namespace. A build component could just expand it into the standard MAML code element.

SelormeyPaul wrote:
BTW, the more extension is added to MAML, the more difficult it will be for Dave and others working on WYSIWYG MAML Editor to get it right.

Yes and no. Yes, it makes it slightly more difficult to implement an editor. However, the editor could be designed with extensibility in mind.

The most simplistic version could just support what is in the MAML namespace. The next iteration could treat XML elements from the other namespaces as black boxes. That means the editor displays just their name and preseves the location so that changing other parts of the topic and saving it does not result in loosing that XML fragment. The most advanced version could provide a plug-in model so that someone can provide the rendering and manipulation logic for these XML fragments.

If the editor would not be extensible I do not see how people could add links to XML schema elements or Java Script APIs which are not part of the standard Sandcastle functionality.

SelormeyPaul wrote:
Please take your time to complete the thesis, it is more important. I wish you God's guidance and wisdom (sorry, if you do not believe in God).

Thank you very much for you good whishes! :-)

Best,
Immo

Coordinator
Feb 11, 2010 at 10:48 AM

Hi Eric,

EWoodruff wrote:

The MAML extensions are part of the Sandcastle Styles patch, not SHFB, so they are available to anyone using Sandcastle alone or with any third party front end. To be complete, the MAML schemas used by Sandcastle should also be updated to include the extensions and should be distributed with the patch so that they are a matched set. It's something I've got on the To Do list but haven't gotten to yet.

Yes, I am aware of it. I have also something on my to-do list regarding how we could do this in more extensible and reliable way. I am thinking of something similar to the WiX approach. WiX is heavily designed around extensible XML schemas. For example, WiX provides the Extension element (used to register file extensions) but the gaming extension provides the new attribute IsRichSavedGame (which causes this extension being registered for the rich saved games property handler on Windows Vista and later).

Best,
Immo

Feb 11, 2010 at 2:46 PM

Hello Immo,

Thanks for the reply, let me see how I could make this clearer...

>>Immo: ...For a future release I am planning to support arbitrary sections as well.

Yes, you can continue adding more features but you can hardly get it complete and satisfy all. The next thing is how to edit such documents, will you provide the editors or expect others to fill in the gap? For open source project keeping things within a working limit is often desired since most will not have the time to really work on such projects.

>>Immo: ...For the use case you mentioned it would in fact be better to keep the documentation separate from the schema files.

Create external documentation (in a new format) for the XsdDoc to extract from or use the XsdDoc to generate the outline of the documentation and edit in a well-known format. Two different approaches, and I prefer the second because it is easier, and will not require any new tool to complete the project. Some including you may prefer the first approach, it will depend on the project also. Just an illustration, I never ever thought I will need WYSIWYG editor for MAML, until I needed my Japanese fellow worker's help for the Japanese manual of a software we completed. Those ideas are good, but may only apply to companies with the needed staff and resources to use them. 

BTW, you do not need any modification to the XsdDoc to get the second, since you are generating MAML anyway. So I really do not see this as the main point of the discussion. XsdDoc only need to generate a valid and editable MAML.

When integration it into my tools, I will take care of all the uses. In fact, I was going to do that and found issues with the generated output. Modifying the codes to get the kind of output I needed will mean forking your codes, not a crime - anyway, it is open source :)

On a releted note, MAML itself contains a template, developerXmlReference, for the XSD Docs, so the second approach is nothing new, and to me just a faster way of using this template since the links and parts are automatically generated.

>>Immo: That is exactly why I introduced the xmlEntityReference element as a MAML schema extension.

That is exactly what I am taking about, you have provided that feature without having to modify the MAML schema itself, using the very basic meaning of XML!

>>Immo: Unfortunately, Eric has simply added a few attributes to the standard MAML code element that now also live in the MAML namespace.

That is the kind of solution, I do not like or use, unless there is no alternative. As you rightly said, it is a simple way of solving the problem, but in this case where Sandcastle already provides a support for code snippets, I will prefer a solution that take full advantage of this.
Now, on this note let me give illustration of my other point...you have also simply added an attribute to the link to create the "References" resources in the "See Also". So my point is, you could have done this in a different way since like the Sandcastle itself you are also providing a build component. 

>>Immo: If the editor would not be extensible I do not see how people could add links to XML schema elements...

I prefer keeping things more realistic. Again, an illustration...the very first post to this forum is 

Integration with DocProject

but you did not response to that post, and in case you are not aware DocProject is extensible :)

Best regards,
Paul. 

Coordinator
Feb 12, 2010 at 1:35 PM
Edited Feb 12, 2010 at 1:35 PM

Hi Paul,

Paul wrote: Yes, you can continue adding more features but you can hardly get it complete and satisfy all. The next thing is how to edit such documents, will you provide the editors or expect others to fill in the gap? For open source project keeping things within a working limit is often desired since most will not have the time to really work on such projects.

Good point; the answer is: I do not know. Right now there is no WYSIWYG (or actually WYSIWYM) editor for MAML at all. The best editor I am aware of is Visual Studio with registered MAML schemas. What I am trying to say is: let's discuss this matter when there is an editor ;-)

My goal was to create a system in which you can document XML schemas in a maintainable way. I added the external documentation features for the following reasons:

  1. It allows you to keep documentation separate from the schemas. This can be very useful if the person documenting the schema is not the same as the person who is maintaining the schema.
  2. It allows you to localize documentation as you can easily create a 1:n relationship between the schema file and the documentation files.
  3. It keeps your schemas small and concise.
Paul wrote: Create external documentation (in a new format) for the XsdDoc to extract from or use the XsdDoc to generate the outline of the documentation and edit in a well-known format. Two different approaches, and I prefer the second because it is easier, and will not require any new tool to complete the project.

For your use case this might be a good way. I have not anticipated this approach because it does not support iterations. You can generate the documenation only once and then you have to maintain it completely by hand. This does not mean that I am not willing to support you to go down this route. I just wanted to explain the rationale behind the current design of XSD Doc.

Paul wrote: Some including you may prefer the first approach, it will depend on the project also. Just an illustration, I never ever thought I will need WYSIWYG editor for MAML, until I needed my Japanese fellow worker's help for the Japanese manual of a software we completed. Those ideas are good, but may only apply to companies with the needed staff and resources to use them.

I share your pain because we face the exact same problem in our company. We would like to have some documenation created by business analysts but you can hardly tell them to use a text editor and type XML...

Paul wrote: BTW, you do not need any modification to the XsdDoc to get the second, since you are generating MAML anyway. So I really do not see this as the main point of the discussion. XsdDoc only need to generate a valid and editable MAML.

That is understood. I am going to add your suggestion on the backlog of my next iteration. If I understand your scenario correctly, you are willing to sacrifice a minor loss of fidelity if the resulting MAML is valid, is that correct? By minor loss of fidelity I am referring to the issues I mentioned in my first post.

Paul wrote: On a releted note, MAML itself contains a template, developerXmlReference, for the XSD Docs, so the second approach is nothing new, and to me just a faster way of using this template since the links and parts are automatically generated.

I am aware of developerXmlReference but as far as I can remember I did not use it because the current release of Sandcastle did not contain XSLT style sheets that would render its content. In addition, I found all the XML documenation I have seen on MSDN not really satisfying (e.g. they all lack a lot of details such as combinators, ocurrences, constraints, facets).

Paul wrote: That is exactly what I am taking about, you have provided that feature without having to modify the MAML schema itself, using the very basic meaning of XML!

I guess now I understand what you meant when you said that you do not like MAML extensions. With "MAML extension" you mean patching the actual MAML schemas by adding new elements and attributes that reside in the MAML namespace. Is that correct?

My thinking of a "MAML extension" is any approach that adds new elements and attributes to the MAML XML - regardless in which namespace they are living in. However, my thinking of "reliable and maintainable MAML extensions" is that they are living in a different namespace than MAML itself (this implies that they certainly also live in different schema files).

However, as I already pointed out right now MAML itself does not support any kind of extension because it lacks XML schema extensibility points (i.e xs:any and xs:anyAttribute). So the MAML schemas will have to be patched once to support them. Otherwise no XML file containing MAML extensions can be validated successfully.

Paul wrote: Now, on this note let me give illustration of my other point...you have also simply added an attribute to the link to create the "References" resources in the "See Also". So my point is, you could have done this in a different way since like the Sandcastle itself you are also providing a build component.

I guess you are referring to the topicType_id attribute that XSD Doc adds to the expanded xmlEntityReference links:

<relatedTopics>
	<link xlink:href="27ee8c45-5cc9-b18a-9749-02a4c8dea735" topicType_id="3272D745-2FFC-48C4-9E9D-CF2B2B784D5F">doc</link>
</relatedTopics>

Actually, that is part of Sandcastle itself. You find the processing for it in %ProgramFiles%\Sandcastle\Presentation\vs2005\transforms\seeAlsoSection.xsl. Unfortunately, it is not documented in the MAML schema.

Paul wrote:

I prefer keeping things more realistic. Again, an illustration...the very first post to this forum is 

Integration with DocProject

but you did not response to that post, and in case you are not aware DocProject is extensible :)

That is a true but sad point :-)

Best,
Immo

Feb 13, 2010 at 12:13 AM

Hello Immo,

Sorry for taken too much of your previous time.

>>Immo: I just wanted to explain the rationale behind the current design of XSD Doc

Oh, it is my fault. I completely accept your design goals, and think it is really a
step in the right direction. If my post shows anything otherwise, I am sorry.
When evaluating your work I read all the documentations, and understand the direction of the project. 

I hope I will find time to see how best to provide input in that direction, if possible, evaluate text editor support
in the form of auto-completion. 

>>Immo: By minor loss of fidelity I am referring to the issues I mentioned in my first post.

There is not going to be any loss of fidelity, that is why I offered that we discuss it and solve them in my first post.

>>Immo: developerXmlReference but as far as I can remember I did not use...

I will not encourage you to use it, unless you wish to generate this format also as an option (that was my original goal when,
I will planning the XsdDocs myself). Sandcastle does  have all the XSLT for it, but I personally do not like its structure. It is, however,
a very flexible document structure, none of the tables it supports are predefined, so you can include  ocurrences, constraints, facets
etc.

>>Immo: However, as I already pointed out right now MAML itself does not support any kind of extension...

I really like the design goals (what I think they are) of the MAML, simplicity. I will consider the lack
xs:any and xs:anyAttribute as by design, if not you will have seen a lot of "me too" extensions by now.

>>Immo:  Unfortunately, it is not documented in the MAML schema.

Now, you see it. I know about those topic type identifiers. This is how MS itself handles any attributes it needs
in the Sandcastle. These are handled as part of the processing of the document, just like the outline stuff done
with the <token>autoOutline</token>.

Using this for your case, a similar thing could be done for <br/> as <token>lineBreak</token>. And where you are
using the table with the custom indentations, I was planning (for my XsdDoc project, which I have dropped) to use a
Javascript tree, with the items styled with a box to create the hierarchy. Most available Javascript tree are created as list,
so the normal MAML list could be used.

Best regards,
Paul. 

Marked as answer by terrajobst on 2/15/2014 at 6:22 PM