chore: fix "Invalid example" warnings from shred map builder

[chalin]

The shred map (xref) builder was issuing warnings. This fix includes

• Adjustments to the shredder map builder itself so that it
  understands, e.g., app-project relative example paths.
• **/guide/glossary.jade now (Jade) includes the shared parent
  glossary.jade rather than (Harp) importing (via partial). This
  fixes makeExample path issues in the glossary.
• Adjusted some makeExample paths that were ok for site build, but
  confused the xref tool.

[chalin]

@Foxandxss @wardbell @kwalrath : ready for review.

Here are the ngio docs related warnings:

warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/dependency-injection/ts/app/app.config-config-alt.ts.md") - doc - from file "dart/latest/guide/dependency-injection.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/toh-5/dart/web/index-router.html.md") - doc - from file "dart/latest/tutorial/toh-pt5.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/app/in-memory-data.service-init.ts.md") - doc - from file "ts/latest/tutorial/toh-pt6.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/app/heroes.component-delete.html.md") - doc - from file "ts/latest/tutorial/toh-pt6.jade"

And here are the ng API doc example warnings (that were repeated for TS):

warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/platform/dom/debug/ts/by/by-by_all.ts.md") - doc - from file "js/latest/api/platform-browser/index/By-class.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/platform/dom/debug/ts/by/by-by_css.ts.md") - doc - from file "js/latest/api/platform-browser/index/By-class.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/platform/dom/debug/ts/by/by-by_directive.ts.md") - doc - from file "js/latest/api/platform-browser/index/By-class.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/router/ts/can_activate/can_activate_example-canActivate.ts.md") - doc - from file "js/latest/api/router-deprecated/index/CanActivate-decorator.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/router/ts/can_deactivate/can_deactivate_example-routerCanDeactivate.ts.md") - doc - from file "js/latest/api/router-deprecated/index/CanDeactivate-interface.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/router/ts/reuse/reuse_example-reuseCmp.ts.md") - doc - from file "js/latest/api/router-deprecated/index/CanReuse-interface.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/router/ts/on_activate/on_activate_example-routerOnActivate.ts.md") - doc - from file "js/latest/api/router-deprecated/index/OnActivate-interface.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/router/ts/on_deactivate/on_deactivate_example-routerOnDeactivate.ts.md") - doc - from file "js/latest/api/router-deprecated/index/OnDeactivate-interface.jade"
warn:    Invalid example (unable to locate fragment file: "public/docs/_fragments/_api/router/ts/reuse/reuse_example-reuseCmp.ts.md") - doc - from file "js/latest/api/router-deprecated/index/OnReuse-interface.jade"

The latter have been fixed via angular/angular#9828.

[Foxandxss]

So this fix the two ToH issues with fragments? Those are fine on the .jade.

[chalin]

Yes it fixes the toh fragment issues. And you are correct: those were fine in the rendered site HTML. The problem arose in the fragment cross referencer which Ward said we will likely be using once again in the future (cf. this comment).

[wardbell]

Can you explain what the consequences of this (and similar changes) are for the way we write examples in Jade?

[chalin]

It has no impact on how we write the Jade, but it allows the shred xref mapper to make sense of the abbreviated makeExample source paths like:

+makeExample('app/hero.service.ts')

vs the original long form:

+makeExample('router/ts/app/main.1.ts','all', 'main.ts')(format=".")

Does that answer your question?

[wardbell]

Merged