How to use a custom text in codeEntityReference

Mar 3, 2009 at 9:42 AM
The element codeEntityReference displays the name of the class or member to point to. What about displaying a custom text instead? I could not find a suitable element - is there something available? For example, an excerpt from MAML sources:

... use the <link coderef="T:MyProject.Settings.LogSettings">logging configuration</link>.

Well, because I was not able to find anything built-in, my colleague put a few lines to the template ddue:link to get it working. Are you interested to support it in your original transformations or do you see it rather a topic to the Sandcastle Styles Project? I could create a work item and send you the code.

Thanks,
Ferda
Mar 3, 2009 at 10:19 AM
Hello Ferda,
I will  have used 

..use the logging configuration, <codeEntityReference>T...</codeEntityReference>.

and get the work done.

The coderef will break the current schema and is not advisable. I know many are writing their conceptual
help with invalid extensions. I suggest you stick to the schema and get the work done. 
You can be sure stuff like this will not be supported by MS, since any break in their huge documentation
will course a huge financial loss.

If you really need to do some personal link stuff, I suggest you use the legacyLink tag. You can post a version
that will not break the schema, by using say special prefix to attributes or element text to the Sandcastle Styles
for consideration - there is no chance it will be added to the main Sandcastle version (or you can give it a try).

Best regards,
Paul.
Mar 3, 2009 at 12:53 PM
Hi Paul,

Thanks for your suggestions. I may use your alternative but I may not be satisfied with the output it in all cases.

I don't see adding an attribute a breaking change - rather a backwards compatible change. But you're right that it would break checking to a strict scheme. Hmm, modifying an existing element can be seen as an quite invasive change.

I don't se the legacyLink tag as a possible workaround. I would like to render the link in all output - HTML Help 1 & 2 and a web site. Building of the relative URL can be different and it actually is - I assemble the documentation project from more blocks.

Sandcastle Styles could be seen as an inspiration for the future Sandcastle. Something can make way there, something not. Extensions can be introduce there faster than in Sandcastle. The demand makes the movement :-)

I'm not fond of using prefixes or other cluttering of the input for the codeEntityReference. It breaks processing of the element too. It will not break the schema check but basically, it is a breaking change too becase the later tool won't resolve such reference either.

What about adding a new template supporting the custom text, something like codeEntityReference2 (well, it would have some shorter and better name..) with this functionality? XSLT is about to be extensible, isn't it?


Cheers,
Ferda
Mar 3, 2009 at 1:53 PM
Hi Ferda,

You have to wonder why it's not supported in the first place.  In all of the .NET Class Library documentation, do you think there's anything like your example being used?  Probably not.

Here are a couple reasons why the Sandcastle team may have chosen the current approach, where the text for codeEntityReference links is generated automatically:

  1. It ensures that a reader knows the name of a type or member to which you are linking, without having to click the link first.  This enhances the clarity of your documentation so that a reader can decide immediately whether they are interested in following a particular link for more information.  If they're already familiar with the API they may choose to simply skip the link and continue reading.
  2. It ensures a consistent format among all links.  (However, you can use qualifyHint in scenarios where you feel that the default simple name is not clear enough.)
  3. It promotes readable naming conventions in code.  This allows you to use the member name as a regular language term within a sentence and have it linked to an associated API.  (I'm not sure how much of an effect this would have on Microsoft's code in particular, but it does make sense for smaller documentation sets at least.)
- Dave
Mar 3, 2009 at 2:22 PM
>>Ferda: I may use your alternative but I may not be satisfied with the output it in all cases.
Unfortunately, I personally do not see any special benefit in this "feature", other than my style or preference talk.
Why? Reference docs could be huge and letting the user know the names of the classes at any opportunity
is no beneficial than style.
Two people working on the same document may use different text to refer to the same class - I do not know
that benefit it brings to the user. I think MS has experts who study those choices, so we always need to be
careful when making style choices.

>>FerdaI don't se the legacyLink tag as a possible workaround.
There is no real difference between the link and the legacyLink. I used that to implement link anchor for conceptual
tags myself - http://sandcastlestyles.codeplex.com/WorkItem/View.aspx?WorkItemId=4976
It is a valid tag, just like the legacyBold, legacyItalic etc.

>>Ferda: Sandcastle Styles could be seen as an inspiration for the future Sandcastle.
We also needs to be careful if we wanted it to be used by many companies, just throwing in anything in the name
of a demand is not a good way forward.
In my own installations, I have my own customized styles, Sandcastle Styles and the default Sandcastle styles. They all live
in different directories and I use them as I want without having to override any.
My build library, Sandcastle Helpers, supports this simple configuration - still do not know why the other tools are
still not supporting this "feature".

>>Ferda: I'm not fond of using prefixes or other cluttering of the input for...
Just read the XSLT, you will find that even MS does this for some of their own stuff. The point is you extend the transform
to handle your special features, without having to modify the schema.
I supported the math tag with both inline and displayed equations (and more! such as equation number etc) in my Sandcastle
Assist components without having to add any new attribute or extensions, so it will work in any Sandcastle installation.
May because I work here in Japan, they are just very strict on what you make as change to existing or working system.

Please post your stuff to the Sandcastle Styles for further discussions.

Best regards,
Paul.
Mar 3, 2009 at 2:24 PM
>>Dave: Here are a couple reasons why the Sandcastle team may have chosen the current approach...
Thanks for making this even clearer.

Best regards,
Paul.
Mar 3, 2009 at 3:34 PM
Edited Mar 3, 2009 at 3:42 PM
Hi Paul and Dave,

Thanks for your opinions. Basically, I got the answer I wanted: I have not missed anything - Sandcastle does not provide the functionality. Let's move to the Sandcastle Styles. :-)

Cheers,
Ferda