Use link title from xrefmap.yml (feature request)

[KalleOlaviNiemitalo]

Operation System: Windows

DocFX Version Used: 2.40.12.0

Template used: default

Steps to Reproduce:

1. Define a link reference in xrefmap.yml:

   references:
   - uid: rfc6238
     name: RFC 6238
     href: https://www.rfc-editor.org/rfc/rfc6238.txt
     fullName: "M'Raihi, D., Machani, S., Pei, M., and J. Rydell, \"TOTP: Time-Based One-Time Password Algorithm\", RFC 6238, DOI 10.17487/RFC6238, May 2011, <https://www.rfc-editor.org/info/rfc6238>."

   Note: I don't know whether fullName is a good property for this feature. Perhaps it should be title or linkTitle or description instead.
2. Refer to xrefmap.yml from docfx.json:

   {
     "build": {
       …
       "xref": [
         "xrefmap.yml"
       ],
       … 
     }
   }

3. Refer to xref:rfc6238 from articles/intro.md:

   Link to [RFC 4226].
   
   Link to <xref:rfc6238>.
   
   [RFC 4226]: <https://www.rfc-editor.org/rfc/rfc4226.txt> "M'Raihi, D., Bellare, M., Hoornaert, F., Naccache, D., and O. Ranen, \"HOTP: An HMAC-Based One-Time Password Algorithm\", RFC 4226, DOI 10.17487/RFC4226, December 2005, <https://www.rfc-editor.org/info/rfc4226>."

4. Run docfx build.

Expected Behavior:

The title defined in xrefmap.yml shows up in the HTML title attribute:

<p>Link to <a href="https://www.rfc-editor.org/rfc/rfc4226.txt" title="M'Raihi, D., Bellare, M., Hoornaert, F., Naccache, D., and O. Ranen, &quot;HOTP: An HMAC-Based One-Time Password Algorithm&quot;, RFC 4226, DOI 10.17487/RFC4226, December 2005, &lt;https://www.rfc-editor.org/info/rfc4226&gt;.">RFC 4226</a>.</p>
<p>Link to <a class="xref" href="https://www.rfc-editor.org/rfc/rfc6238.txt" title="M'Raihi, D., Machani, S., Pei, M., and J. Rydell, &quot;TOTP: Time-Based One-Time Password Algorithm&quot;, RFC 6238, DOI 10.17487/RFC6238, May 2011, &lt;https://www.rfc-editor.org/info/rfc6238&gt;.">RFC 6238</a>.</p>

Actual Behavior:

The xref link has no HTML title attribute:

<p>Link to <a href="https://www.rfc-editor.org/rfc/rfc4226.txt" title="M'Raihi, D., Bellare, M., Hoornaert, F., Naccache, D., and O. Ranen, &quot;HOTP: An HMAC-Based One-Time Password Algorithm&quot;, RFC 4226, DOI 10.17487/RFC4226, December 2005, &lt;https://www.rfc-editor.org/info/rfc4226&gt;.">RFC 4226</a>.</p>
<p>Link to <a class="xref" href="https://www.rfc-editor.org/rfc/rfc6238.txt">RFC 6238</a>.</p>

Rationale:

Pro: This would make it easier to ensure that all hyperlinks to the same external site have the same title. Currently, the easiest way to do that seems find . -name "*.md" -print0 | xargs -0 -r grep '^\[\([^][]\|\\.\)\+\]:' | sort -u.

Pro: This would also make it easier to link to a bug-tracking system and copy the bug titles to link titles.

Con: I'm not sure whether Safari on iOS can display link titles at all. Users of mobile devices might not benefit from such a change.

Con: If a documentation set were ported from normal Markdown reference links to xref links in order to use this feature, not all Markdown authoring tools would be able to preview the links correctly. In this respect, it might be better to have a bot update the link titles in each Markdown file.

Workaround: Create a separate file just for the link and use inline file inclusion to embed the link into each article that needs it. However, this does not let the articles change the link text, which can be a problem if the sentence needs a different grammatical case.

Alternative feature: Create a separate file for the link reference definition, use block file inclusion to load the link reference definition to each article that needs it, and use a reference link. This does not currently work in DocFX because link reference definitions in included files are not visible to the including file.

docfx_project.zip demonstrates several of these approaches.