public static XRefDetails From(HtmlAgilityPack.HtmlNode node)
{
if (node.Name != "xref")
{
throw new NotSupportedException("Only xref node is supported!");
}
var xref = new XRefDetails();
var rawUid = GetRawUid(node);
if (!string.IsNullOrEmpty(rawUid))
{
var anchorIndex = rawUid.IndexOf("#");
if (anchorIndex == -1)
{
xref.Anchor = string.Empty;
xref.Uid = HttpUtility.UrlDecode(rawUid);
}
else
{
xref.Anchor = rawUid.Substring(anchorIndex);
xref.Uid = HttpUtility.UrlDecode(rawUid.Remove(anchorIndex));
}
}
var overrideName = node.InnerText;
if (!string.IsNullOrEmpty(overrideName))
{
xref.AnchorDisplayName = overrideName;
xref.PlainTextDisplayName = overrideName;
}
else
{
// If name | fullName exists, use the one from xref because spec name is different from name for generic types
// e.g. return type: IEnumerable<T>, spec name should be IEnumerable
xref.AnchorDisplayName = node.GetAttributeValue("name", null);
xref.PlainTextDisplayName = node.GetAttributeValue("fullName", null);
}
xref.Title = node.GetAttributeValue("title", null);
// Both `data-raw-html` and `data-raw` are html encoded. Use `data-raw-html` with higher priority.
// `data-raw-html` will be decoded then displayed, while `data-raw` will be displayed directly.
var raw = node.GetAttributeValue("data-raw-html", null);
if (!string.IsNullOrEmpty(raw))
{
xref.Raw = StringHelper.HtmlDecode(raw);
}
else
{
xref.Raw = node.GetAttributeValue("data-raw", null);
}
xref.ThrowIfNotResolved = node.GetAttributeValue("data-throw-if-not-resolved", false);
return(xref);
}
private static void UpdateXref(HtmlNode node, IDocumentBuildContext context, string language)
{
var xref = XRefDetails.From(node);
// Resolve external xref map first, and then internal xref map.
// Internal one overrides external one
var xrefSpec = context.GetXrefSpec(HttpUtility.HtmlDecode(xref.Uid));
xref.ApplyXrefSpec(xrefSpec);
var convertedNode = xref.ConvertToHtmlNode(language);
node.ParentNode.ReplaceChild(convertedNode, node);
if (xrefSpec == null && xref.ThrowIfNotResolved)
{
throw new CrossReferenceNotResolvedException(xref);
}
}
private (bool resolved, bool warn) UpdateXref(HtmlNode node, IDocumentBuildContext context, string language, out XRefDetails xref)
{
xref = XRefDetails.From(node);
XRefSpec xrefSpec = null;
if (!string.IsNullOrEmpty(xref.Uid))
{
// Resolve external xref map first, and then internal xref map.
// Internal one overrides external one
xrefSpec = context.GetXrefSpec(HttpUtility.HtmlDecode(xref.Uid));
xref.ApplyXrefSpec(xrefSpec);
}
var renderer = xref.TemplatePath == null ? null : _rendererLoader.Load(xref.TemplatePath);
var(convertedNode, resolved) = xref.ConvertToHtmlNode(language, renderer);
node.ParentNode.ReplaceChild(convertedNode, node);
var warn = xrefSpec == null && xref.ThrowIfNotResolved;
return(resolved, warn);
}
private static bool UpdateXref(HtmlNode node, IDocumentBuildContext context, string language, out XRefDetails xref)
{
xref = XRefDetails.From(node);
XRefSpec xrefSpec = null;
if (!string.IsNullOrEmpty(xref.Uid))
{
// Resolve external xref map first, and then internal xref map.
// Internal one overrides external one
xrefSpec = context.GetXrefSpec(HttpUtility.HtmlDecode(xref.Uid));
xref.ApplyXrefSpec(xrefSpec);
}
var convertedNode = xref.ConvertToHtmlNode(language);
node.ParentNode.ReplaceChild(convertedNode, node);
if (xrefSpec == null && xref.ThrowIfNotResolved == true)
{
return(false);
}
return(true);
}
private static void TransformXrefLink(HtmlAgilityPack.HtmlNode node, IDocumentBuildContext context)
{
var convertedNode = XRefDetails.ConvertXrefLinkNodeToXrefNode(node);
node.ParentNode.ReplaceChild(convertedNode, node);
}
public static XRefDetails From(HtmlNode node)
{
if (node.Name != "xref")
{
throw new NotSupportedException("Only xref node is supported!");
}
var rawUid = node.GetAttributeValue("uid", null);
var xref = new XRefDetails()
{
InnerHtml = node.InnerHtml,
Uid = rawUid,
SourceFile = node.GetAttributeValue("sourceFile", null),
SourceStartLineNumber = node.GetAttributeValue("sourceStartLineNumber", 0),
SourceEndLineNumber = node.GetAttributeValue("sourceEndLineNumber", 0),
RawSource = node.GetAttributeValue("data-raw-source", null),
ThrowIfNotResolved = node.GetAttributeValue("data-throw-if-not-resolved", false),
TemplatePath = StringHelper.HtmlDecode(node.GetAttributeValue("template", null)),
};
var rawHref = node.GetAttributeValue("href", null);
if (!string.IsNullOrEmpty(rawHref))
{
if (!string.IsNullOrEmpty(rawUid))
{
Logger.LogWarning($"Both href and uid attribute are defined for {node.OuterHtml}, use href instead of uid.");
}
var(path, query, fragment) = UriUtility.Split(rawHref);
xref.Uid = HttpUtility.UrlDecode(path);
xref.Anchor = fragment;
// extract values from query
var queryValueCollection = HttpUtility.ParseQueryString(query);
xref.DisplayProperty = ExtractValue(queryValueCollection, "displayProperty") ?? xref.DisplayProperty;
xref.AltProperty = ExtractValue(queryValueCollection, "altProperty") ?? xref.AltProperty;
xref.Text = StringHelper.HtmlEncode(ExtractValue(queryValueCollection, "text")) ?? xref.Text;
xref.Alt = StringHelper.HtmlEncode(ExtractValue(queryValueCollection, "alt")) ?? xref.Alt;
xref.Title = ExtractValue(queryValueCollection, "title") ?? xref.Title;
var remainingQuery = queryValueCollection.ToString();
xref.Query = string.IsNullOrEmpty(remainingQuery) ? string.Empty : "?" + remainingQuery;
}
// extract values from HTML attributes
xref.DisplayProperty = node.GetAttributeValue("displayProperty", xref.DisplayProperty);
xref.AltProperty = node.GetAttributeValue("altProperty", xref.AltProperty);
xref.Text = node.GetAttributeValue("text", node.GetAttributeValue("name", xref.Text));
xref.Alt = node.GetAttributeValue("alt", node.GetAttributeValue("fullname", xref.Alt));
xref.Title = node.GetAttributeValue("title", xref.Title);
// Both `data-raw-html` and `data-raw-source` are html encoded. Use `data-raw-html` with higher priority.
// `data-raw-html` will be decoded then displayed, while `data-raw-source` will be displayed directly.
var raw = node.GetAttributeValue("data-raw-html", null);
if (!string.IsNullOrEmpty(raw))
{
xref.Raw = StringHelper.HtmlDecode(raw);
}
else
{
xref.Raw = xref.RawSource;
}
return(xref);
string ExtractValue(NameValueCollection collection, string properName)
{
var value = collection[properName];
collection.Remove(properName);
return(value);
}
}
/// <summary>
/// Export xref map file.
/// </summary>
private static void ExportXRefMap(DocumentBuildParameters parameters, DocumentBuildContext context)
{
Logger.LogVerbose("Exporting xref map...");
var xrefMap = new XRefMap();
xrefMap.References =
(from xref in context.XRefSpecMap.Values.AsParallel().WithDegreeOfParallelism(parameters.MaxParallelism)
select new XRefSpec(xref)
{
Href = ((RelativePath)context.FileMap[xref.Href]).RemoveWorkingFolder().ToString() + "#" + XRefDetails.GetHtmlId(xref.Uid),
}).ToList();
xrefMap.Sort();
YamlUtility.Serialize(
Path.Combine(parameters.OutputBaseDir, XRefMapFileName),
xrefMap);
Logger.LogInfo("XRef map exported.");
}
public static XRefDetails From(HtmlNode node)
{
if (node.Name != "xref")
{
throw new NotSupportedException("Only xref node is supported!");
}
var xref = new XRefDetails();
var uid = node.GetAttributeValue("uid", null);
var rawHref = node.GetAttributeValue("href", null);
NameValueCollection queryString = null;
if (!string.IsNullOrEmpty(rawHref))
{
if (!string.IsNullOrEmpty(uid))
{
Logger.LogWarning($"Both href and uid attribute are defined for {node.OuterHtml}, use href instead of uid.");
}
string others;
var anchorIndex = rawHref.IndexOf("#");
if (anchorIndex == -1)
{
xref.Anchor = string.Empty;
others = rawHref;
}
else
{
xref.Anchor = rawHref.Substring(anchorIndex);
others = rawHref.Remove(anchorIndex);
}
var queryIndex = others.IndexOf("?");
if (queryIndex == -1)
{
xref.Uid = HttpUtility.UrlDecode(others);
}
else
{
xref.Uid = HttpUtility.UrlDecode(others.Remove(queryIndex));
queryString = HttpUtility.ParseQueryString(others.Substring(queryIndex));
}
}
else
{
xref.Uid = uid;
}
xref.InnerHtml = node.InnerHtml;
xref.DisplayProperty = node.GetAttributeValue("displayProperty", queryString?.Get("displayProperty") ?? XRefSpec.NameKey);
xref.AltProperty = node.GetAttributeValue("altProperty", queryString?.Get("altProperty") ?? "fullName");
xref.Text = node.GetAttributeValue("text", node.GetAttributeValue("name", StringHelper.HtmlEncode(queryString?.Get("text"))));
xref.Alt = node.GetAttributeValue("alt", node.GetAttributeValue("fullname", StringHelper.HtmlEncode(queryString?.Get("alt"))));
xref.Title = node.GetAttributeValue("title", queryString?.Get("title"));
xref.SourceFile = node.GetAttributeValue("sourceFile", null);
xref.SourceStartLineNumber = node.GetAttributeValue("sourceStartLineNumber", 0);
xref.SourceEndLineNumber = node.GetAttributeValue("sourceEndLineNumber", 0);
// Both `data-raw-html` and `data-raw-source` are html encoded. Use `data-raw-html` with higher priority.
// `data-raw-html` will be decoded then displayed, while `data-raw-source` will be displayed directly.
xref.RawSource = node.GetAttributeValue("data-raw-source", null);
var raw = node.GetAttributeValue("data-raw-html", null);
if (!string.IsNullOrEmpty(raw))
{
xref.Raw = StringHelper.HtmlDecode(raw);
}
else
{
xref.Raw = xref.RawSource;
}
xref.ThrowIfNotResolved = node.GetAttributeValue("data-throw-if-not-resolved", false);
var templatePath = node.GetAttributeValue("template", null);
if (templatePath != null)
{
xref.TemplatePath = StringHelper.HtmlDecode(templatePath);
}
return(xref);
}
protected CrossReferenceNotResolvedException(SerializationInfo info, StreamingContext context) : base(info, context)
{
XRefDetails = (XRefDetails)info.GetValue(nameof(XRefDetails), typeof(XRefDetails));
}
public CrossReferenceNotResolvedException(XRefDetails xrefDetails) : base()
{
XRefDetails = xrefDetails;
}
public static XRefDetails From(HtmlAgilityPack.HtmlNode node)
{
if (node.Name != "xref") throw new NotSupportedException("Only xref node is supported!");
var xref = new XRefDetails();
var rawUid = GetRawUid(node);
NameValueCollection queryString = null;
if (!string.IsNullOrEmpty(rawUid))
{
string others;
var anchorIndex = rawUid.IndexOf("#");
if (anchorIndex == -1)
{
xref.Anchor = string.Empty;
others = rawUid;
}
else
{
xref.Anchor = rawUid.Substring(anchorIndex);
others = rawUid.Remove(anchorIndex);
}
var queryIndex = others.IndexOf("?");
if (queryIndex == -1)
{
xref.Uid = HttpUtility.UrlDecode(others);
}
else
{
xref.Uid = HttpUtility.UrlDecode(others.Remove(queryIndex));
queryString = HttpUtility.ParseQueryString(others.Substring(queryIndex));
}
}
xref.InnerHtml = node.InnerHtml;
xref.DisplayProperty = node.GetAttributeValue("displayProperty", queryString?.Get("displayProperty") ?? XRefSpec.NameKey);
xref.AltProperty = node.GetAttributeValue("altProperty", queryString?.Get("altProperty") ?? "fullName");
xref.Text = node.GetAttributeValue("text", node.GetAttributeValue("name", StringHelper.HtmlEncode(queryString?.Get("text"))));
xref.Alt = node.GetAttributeValue("alt", node.GetAttributeValue("fullname", StringHelper.HtmlEncode(queryString?.Get("alt"))));
xref.Title = node.GetAttributeValue("title", queryString?.Get("title"));
xref.SourceFile = node.GetAttributeValue("sourceFile", null);
xref.SourceStartLineNumber = node.GetAttributeValue("sourceStartLineNumber", 0);
xref.SourceEndLineNumber = node.GetAttributeValue("sourceEndLineNumber", 0);
// Both `data-raw-html` and `data-raw-source` are html encoded. Use `data-raw-html` with higher priority.
// `data-raw-html` will be decoded then displayed, while `data-raw-source` will be displayed directly.
xref.RawSource = node.GetAttributeValue("data-raw-source", null);
var raw = node.GetAttributeValue("data-raw-html", null);
if (!string.IsNullOrEmpty(raw))
{
xref.Raw = StringHelper.HtmlDecode(raw);
}
else
{
xref.Raw = xref.RawSource;
}
xref.ThrowIfNotResolved = node.GetAttributeValue("data-throw-if-not-resolved", false);
return xref;
}
public static XRefDetails From(HtmlAgilityPack.HtmlNode node)
{
if (node.Name != "xref")
{
throw new NotSupportedException("Only xref node is supported!");
}
var xref = new XRefDetails();
var rawUid = GetRawUid(node);
NameValueCollection queryString = null;
if (!string.IsNullOrEmpty(rawUid))
{
string others;
var anchorIndex = rawUid.IndexOf("#");
if (anchorIndex == -1)
{
xref.Anchor = string.Empty;
others = rawUid;
}
else
{
xref.Anchor = rawUid.Substring(anchorIndex);
others = rawUid.Remove(anchorIndex);
}
var queryIndex = others.IndexOf("?");
if (queryIndex == -1)
{
xref.Uid = HttpUtility.UrlDecode(others);
}
else
{
xref.Uid = HttpUtility.UrlDecode(others.Remove(queryIndex));
queryString = HttpUtility.ParseQueryString(others.Substring(queryIndex));
}
}
xref.InnerHtml = node.InnerHtml;
xref.DisplayProperty = node.GetAttributeValue("displayProperty", queryString?.Get("displayProperty") ?? XRefSpec.NameKey);
xref.AltProperty = node.GetAttributeValue("altProperty", queryString?.Get("altProperty") ?? "fullName");
xref.Text = node.GetAttributeValue("text", node.GetAttributeValue("name", StringHelper.HtmlEncode(queryString?.Get("text"))));
xref.Alt = node.GetAttributeValue("alt", node.GetAttributeValue("fullname", StringHelper.HtmlEncode(queryString?.Get("alt"))));
xref.Title = node.GetAttributeValue("title", queryString?.Get("title"));
// Both `data-raw-html` and `data-raw` are html encoded. Use `data-raw-html` with higher priority.
// `data-raw-html` will be decoded then displayed, while `data-raw` will be displayed directly.
var raw = node.GetAttributeValue("data-raw-html", null);
if (!string.IsNullOrEmpty(raw))
{
xref.Raw = StringHelper.HtmlDecode(raw);
}
else
{
xref.Raw = node.GetAttributeValue("data-raw", null);
}
xref.ThrowIfNotResolved = node.GetAttributeValue("data-throw-if-not-resolved", false);
return(xref);
}
public InvalidCrossReferenceException(XRefDetails xrefDetails) : base()
{
XRefDetails = xrefDetails;
}