Document (sometimes) required metadata for implementation report and CR deadline #2765
Conversation
|
@tabatkins could you review this PR please? Closes a couple of issues. |
| <p><dfn class="dfn-paneled" data-dfn-for="macro" data-dfn-type="dfn" data-export id="macro-title"><code>[TITLE]</code></dfn> gives the spec’s full title, as extracted from either the H1 or the spec metadata.</p> | ||
| <p><dfn data-dfn-for="macro" data-dfn-type="dfn" data-export id="macro-bikeshed-documentation"><code>Bikeshed Documentation</code><a class="self-link" href="#macro-bikeshed-documentation"></a></dfn> gives the spec’s full title, as extracted from either the H1 or the spec metadata.</p> | ||
| <li data-md> | ||
| <p><dfn class="dfn-paneled" data-dfn-for="macro" data-dfn-type="dfn" data-export id="macro-h1"><code>[H1]</code></dfn> gives the desired document heading, in case the in-page title is supposed to be different from the <code><title></code> element value.</p> | ||
| <p><dfn data-dfn-for="macro" data-dfn-type="dfn" data-export id="macro-h1"><code>[H1]</code><a class="self-link" href="#macro-h1"></a></dfn> gives the desired document heading, in case the in-page title is supposed to be different from the <code><title></code> element value.</p> | ||
| <li data-md> | ||
| <p><dfn class="dfn-paneled" data-dfn-for="macro" data-dfn-type="dfn" data-export id="macro-shortname"><code>[SHORTNAME]</code></dfn> gives the document’s shortname, like "css-cascade".</p> | ||
| <p><dfn data-dfn-for="macro" data-dfn-type="dfn" data-export id="macro-bikeshed"><code>bikeshed</code><a class="self-link" href="#macro-bikeshed"></a></dfn> gives the document’s shortname, like "css-cascade".</p> |
There was a problem hiding this comment.
The HTML-generation process seems to have gone very wrong here — the newly-generated HTML is actually replacing the macros, instead of documenting them. It seems strings surrounded by [ and ] are getting replaced even when inside <code>, where previously they were left alone.
| <p>With the above code, you can use <code>[FOO]</code> and <code>[BAZ]</code> macros inside the include file, | ||
| and they’ll be substituted with "bar" and "qux qux qux", respectively. | ||
| (Remember that you can mark text macros as optional by appending a <code>?</code>, like <code>[FOO?]</code>, | ||
| (Remember that you can mark text macros as optional by appending a <code>?</code>, like <code></code>, |
There was a problem hiding this comment.
Same problem here, with (ostensible) macros now being replaced inside literals — though, interestingly, [FOO] and [BAZ] above still weren't replaced.
There was a problem hiding this comment.
Even more confounding, there's nothing different about those two uses. The source for this paragraph, in index.bs, is:
With the above code, you can use `[FOO]` and `[BAZ]` macros inside the include file,
and they'll be substituted with "bar" and "qux qux qux", respectively.
(Remember that you can mark text macros as optional by appending a `?`, like `[FOO?]`,
in which case they'll be replaced with the empty string if Bikeshed can't find a definition.)There was a problem hiding this comment.
I guess the difference is that FOO and BAZ are undefined macros, whereas all of the ones that were replaced were defined. (Even if, as in the case of FOO?, they were defined to be the empty string.)
| <p><dfn class="dfn-paneled" data-dfn-for="metadata" data-dfn-type="dfn" data-export id="metadata-local-boilerplate">Local Boilerplate</dfn> tells Bikeshed which boilerplate include files to look for relative to the specification (as opposed to inside the Bikeshed source). Its value is a comma-separated list of include file basename and <a data-link-type="dfn" href="#boolish" id="ref-for-boolish⑨">boolish</a> value, e.g. <code>Local Boilerplate: footer yes</code> to look for <code>footer.include</code> and <code>footer-[STATUS].include</code> next to the specification. This also works for default includes that aren’t quite boilerplate like <a href="#default-metadata">defaults.include</a>, <a href="#computed-metadata">computed-metadata.include</a>, and <a href="#echidna-hooks">bs-extensions.include</a>.</p> | ||
| <p><dfn class="dfn-paneled" data-dfn-for="metadata" data-dfn-type="dfn" data-export id="metadata-local-boilerplate">Local Boilerplate</dfn> tells Bikeshed which boilerplate include files to look for relative to the specification (as opposed to inside the Bikeshed source). Its value is a comma-separated list of include file basename and <a data-link-type="dfn" href="#boolish" id="ref-for-boolish⑨">boolish</a> value, e.g. <code>Local Boilerplate: footer yes</code> to look for <code>footer.include</code> and <code>footer-LS.include</code> next to the specification. This also works for default includes that aren’t quite boilerplate like <a href="#default-metadata">defaults.include</a>, <a href="#computed-metadata">computed-metadata.include</a>, and <a href="#echidna-hooks">bs-extensions.include</a>.</p> |
There was a problem hiding this comment.
Another undesirable macro-inside-code-element replacement.
| and it populates the <code>[REPOSITORY]</code> and <code>[REPOSITORYURL]</code> text macros accordingly. | ||
| and it populates the <code>speced/bikeshed</code> and <code>https://github.com/speced/bikeshed</code> text macros accordingly. |
|
I wonder if #2721 is responsible for the change in behavior here? |
|
I have a fix for the macro-reference issues in #2773 that will allow the docs to be regenerated correctly, and without |
|
Uh, none of these problems are reproduced in the current version of Bikeshed. I have to assume that Chris's version is substantially behind? |
|
Okay, committed the index.bs changes (and regened index.html myself). Thanks, @svgeesus ! |
This PR would fix #2644 and #2645. Links to pubrules in cases where this is required.
Contributing requires the html to be generated. This has a bunch of fatal errors, which I didn't introduce, so I used -f.