Where should we end up with specification URLs?

[ddbeck]

Since we’ve added new ways of adding specifications to MDN, we ought to have an idea of where we want to end up, so we’re not adding complexity on top of complexity. I’ve written a brief outline of where I think we should go. Please comment with questions or suggestions. Once we have agreement on key points, we can start to plan in reverse to get there (even though there will be some messiness in the meantime).

---

Setting front matter

For pages about specified, standards-track web platform features, authors set specifications by one of these methods, in order of preference:

1. Setting a browser-compat front matter key.

   Authors should prefer this option, even if there’s no compatibility table on the page.

2. Setting a URL string for the spec-urls front matter key.

3. Setting an array of two or more URLs for the spec-urls front matter key.

4. Omitting the browser-compat or and spec-urls keys, where inapplicable.

For pages about unspecified, non-standard features, authors declare this status by one of these methods, in order of preference:

1. Setting a browser-compat front matter key.

   Authors should prefer this option, even if there’s no compatibility table on the page.

2. Setting a special MDN URL string for the spec-urls front matter key (e.g., https://developer.mozilla.org/en-US/docs/non-standard or similar).

Generating tables and text

If both spec-urls and browser-compat are set, then this should provoke an error for conflict front matter keys.

(Previous paragraph replaces the text below, which has been stricken out. See discussion in this thread: #5347 (comment))

If an author uses two or more methods to set specifications (or non-standard status), then Yari should generate specification tables or text that fails useful (i.e., shows URLs from all sources or shows non-standard boilerplate text), with the following caveats:

• If the set of URLs sourced from BCD and the spec-urls key have overlapping members, then this should provoke a duplicate data error.
• If the set of URLs sourced from BCD and the spec-urls key don’t have overlapping members, then this should provoke a warning that BCD is potentially missing data.
• If there exists a conflict between the reported standards status of a feature between BCD or the set of URLs in spec-urls, then this should provoke a conflicting data error.

Authors insert specifications tables (or boilerplate non-standard text) into pages by one of these methods, in order of preference:

1. (Waves hands vigorously.) Automatic insertion by the page type definition system.
2. The Specifications macro with no arguments.

Style and consistency

To ensure the ongoing consistency of BCD and MDN specification URLs and status information, the following rules should apply to allowed values of spec-urls:

• Each URL must be in w3c/browser-specs or added to an allowlist.

  If a URL is added to an allowlist, it must be accompanied by an explanatory comment (for why it won’t ever be included in w3c/browser-specs) or a link to an issue or PR which will bring about its eventual removal from the list.

  Moreover, the allowlist for MDN must be a superset of BCDs (i.e., MDN’s spec-urls validation must always succeed for BCD-sourced URLs).

• Each URL must be a complete and valid URL. If it contains a fragment identifier, that identifier must exist in the target URL.

Finally, BCD and MDN should have mutually compatible guidelines for choosing which part of a specification to link to.

[hamishwillee]

Sounds good. Just FMI (and possibly outside scope), are we allowing multiple BCD keys? The use case is overview page, where the set of specs and browser compat might be the union of multiple classes.
This can of course be done using spec_urls, but BCD would probably be better.

[wbamberg]

API overview pages often (usually?) only have one spec, because an API is really defined by a spec.

About BCD for API overviews: I think this is a tricky problem. There's a thread about this here: https://github.com/mdn/content/discussions/4920 and per https://github.com/mdn/content/discussions/4920#discussioncomment-775162 I'm not sure that just including full BCD for all the components of the spec is a good solution. So I think, for now, until we have something better, it's probably best not to include BCD in API overview pages, but to use the spec-urls key.

[teoli2003]

API overview pages often (usually?) only have one spec, because an API is really defined by a spec.

This is not always the case. E.g. CSSOM that is split in numerous specifications: https://developer.mozilla.org/en-US/docs/Web/API/CSS_Object_Model

We really have 3 cases (at least):

• an API is covered by a whole spec.
• an API is covered by a "chapter" of a spec documents
• an API is split into several spec documents.

[wbamberg]

It seems to me that this allows for two mechanisms in which pages can include a spec URL:

• browser-compat front matter key
• spec-urls front matter key

Am I right in reading this:

• If the set of URLs sourced from BCD and the spec-urls key have overlapping members, then this should provoke a duplicate data error.
• If the set of URLs sourced from BCD and the spec-urls key don’t have overlapping members, then this should provoke a warning that BCD is potentially missing data.

...as saying that including both keys will give at least a warning?

I'm not sure how to interpret "order of preference". Or to put it another way, why not just always do the most-preferred thing? In which circumstances should we choose a less-preferred option? I'm also not sure why setting multiple URLs is less preferred than setting one. If the feature is actually governed by two specifications, why isn't it preferred to set two URLs?

It seems to me that we have:

1. Some (most!) reference pages that have BCD, and BCD includes a spec URL entry. These should use browser-compat.

2. Some reference pages that have BCD, and BCD does not include a spec URL entry. Ideally I'd like us to treat this as an error, but perhaps there's are legit exceptions? The reason I'd like us to treat this as an error is that we could say pages can't have both browser-compat and spec-urls, and that makes it much more obvious to authors what to do.

3. Some reference pages that don't (and should not) have BCD, but would still like to include spec tables. There are a few types here:

   • API overview pages, like https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API. These are an important case really, because an API is really defined by a specification, and because it's generally not possible to have a BCD entry for them, because BCD doesn't work like that. In my mind these were the primary case for the spec-urls key.
   • other reference pages that don't (by choice) have BCD, like https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair . I guess this is basically dictionaries, and I guess these should also use spec-urls, although that feels a little more ad hoc (why does https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey have BCD, but https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair does not?). Well OK, spec-urls is a reasonable fallback here.

4. Some reference pages which do have BCD but want to use a different spec URL for some reason, like https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self. This seems like a weird case where browser-compat is css.properties.justify-self but that level of BCD doesn't have a spec_url key, so the page uses css.properties.justify-self.grid_context, which does, even though the spec isn't specific to grid, and is the same as the spec referenced at css.properties.justify-self.flex_context (https://github.com/mdn/browser-compat-data/blob/main/css/properties/justify-self.json). Is there some reason here why BCD can't include spec_url at the justify-self level, rather than the grid_context level?

5. Some guide pages that would like to include spec tables, like https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest . I think there's a case here for allowing {{Specifications("https://link/to/spec")}} here, for reasons I've outlined in Add spec URLs for all remaining subtrees content#13273 (comment).

[sideshowbarker]

1. Some (most!) reference pages that have BCD, and BCD includes a spec URL entry. These should use browser-compat.

Yes, it seems like every reference page that has data in BCD should have browser-compat and should not have spec-urls.

But we should recognize here that we do have one set of reference docs that don’t (and won’t) have data in BCD: the ARIA attribute and role docs (which are kind of what got the ball rolling on this to begin with).

So in the case of those ARIA docs and any other reference docs we might ever create that don’t have data in BCD, then I think the right way to provide any spec URLs is using the spec-urls frontmatter key (rather than a Specifications("http://foo.bar") call.

2. Some reference pages that have BCD, and BCD does not include a spec URL entry.

I think I may have actually fixed all those. I have one BCD PR open at mdn/browser-compat-data#15141 but after that is merged, I think all the “reference pages that have BCD, and BCD does not include a spec URL entry” cases I ran into so far will have been fixed.

Ideally I'd like us to treat this as an error

Yes, agreed

but perhaps there's are legit exceptions?

I have not run into legit exceptions, and can’t readily imagine any.

The reason I'd like us to treat this as an error is that we could say pages can't have both browser-compat and spec-urls, and that makes it much more obvious to authors what to do.

Yes, ageed

3. Some reference pages that don't (and should not) have BCD, but would still like to include spec tables. There are a few types here:

   • API overview pages, like developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API. These are an important case really, because an API is really defined by a specification, and because it's generally not possible to have a BCD entry for them, because BCD doesn't work like that.

Yes

In my mind these were the primary case for the spec-urls key.

I think the current state of my open MDN PRs for this is that based on my understanding of mdn/content#13273 (comment), I switched them all to Specifications("http://foo.bar").

I understood the logic there to be: Authors should only use the spec-urls key for reference pages that don’t have a browser-compat key — such as the ARIA docs — but should not use the spec-urls key for API overview pages.

I guess if we did it that way, it’s mean we used the spec-urls key only for a small set of docs — maybe in practice just the ARIA docs — and we would use the Specifications("http://foo.bar") for most/all non-reference docs.

I think that’d be fine, if we document it that way for authors and ourselves. But I would also be fine if we said to just use the spec-urls key. That might be less complex, I dunno.

I can imagine we could even have the flaw-checker do a check for “non-reference doc that has a spec-urls key — but the wrinkle there is that it’d need to be based on some heuristics that we are currently maybe not otherwise consistently enforcing.

What I mean is, given the source of a particular existing MDN doc, how do we programmatically identify it as a reference doc?

Maybe the most obvious way that comes to mind for doing that is: We look at the tags — specifically, we look for the Reference tag.

Unfortunately the problem with that in practice right now is that I have found:

• Numerous cases of existing docs which have the Reference tag but are actually API-overview or Guide pages rather than being actual reference docs. (I have pushed some commits to my open PRs to fix those cases where I found them.)
• Some small number of cases where we have reference docs which we missing the Reference tag. (Also pushed some commits with fixes for those.)

Other imaginable ways to identify a non-reference doc are to do things like looking for API or Using in the title or slug, or looking at the path (for example, nothing in the Guide subtree). But those seem fragile in comparison to just checking the tags.

---

I have more comments to make, but I’ve run out of time just now, so will comment here more later.

[wbamberg]

I think I may have actually fixed all those. I have one BCD PR open at mdn/browser-compat-data#15141 but after that is merged, I think all the “reference pages that have BCD, and BCD does not include a spec URL entry” cases I ran into so far will have been fixed.

That is really great news.

Ideally I'd like us to treat this as an error

Yes, agreed

but perhaps there's are legit exceptions?

I have not run into legit exceptions, and can’t readily imagine any.

The reason I'd like us to treat this as an error is that we could say pages can't have both browser-compat and spec-urls, and that makes it much more obvious to authors what to do.

Yes, ageed

3. Some reference pages that don't (and should not) have BCD, but would still like to include spec tables. There are a few types here:

   • API overview pages, like developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API. These are an important case really, because an API is really defined by a specification, and because it's generally not possible to have a BCD entry for them, because BCD doesn't work like that.

Yes

In my mind these were the primary case for the spec-urls key.

I think the current state of my open MDN PRs for this is that based on my understanding of mdn/content#13273 (comment), I switched them all to Specifications("http://foo.bar").

I understood the logic there to be: Authors should only use the spec-urls key for reference pages that don’t have a browser-compat key — such as the ARIA docs — but should not use the spec-urls key for API overview pages.

I guess if we did it that way, it’s mean we used the spec-urls key only for a small set of docs — maybe in practice just the ARIA docs — and we would use the Specifications("http://foo.bar") for most/all non-reference docs.

I think that’d be fine, if we document it that way for authors and ourselves. But I would also be fine if we said to just use the spec-urls key. That might be less complex, I dunno.

I can imagine we could even have the flaw-checker do a check for “non-reference doc that has a spec-urls key — but the wrinkle there is that it’d need to be based on some heuristics that we are currently maybe not otherwise consistently enforcing.

What I mean is, given the source of a particular existing MDN doc, how do we programmatically identify it as a reference doc?

This is where this intersects (or could intersect) with page types. If we have a page-type front matter key that tells us what kind of page something is we can use that to decide which elements it must/may have.

Maybe the most obvious way that comes to mind for doing that is: We look at the tags — specifically, we look for the Reference tag.

Unfortunately the problem with that in practice right now is that I have found:

• Numerous cases of existing docs which have the Reference tag but are actually API-overview or Guide pages rather than being actual reference docs. (I have pushed some commits to my open PRs to fix those cases where I found them.)

• Some small number of cases where we have reference docs which we missing the Reference tag. (Also pushed some commits with fixes for those.)

Other imaginable ways to identify a non-reference doc are to do things like looking for API or Using in the title or slug, or looking at the path (for example, nothing in the Guide subtree). But those seem fragile in comparison to just checking the tags.

I have more comments to make, but I’ve run out of time just now, so will comment here more later.

[ddbeck]

There's quite a lot to respond to here. Let me know if I've failed to address something.

Scope

Before I get into the weeds though, I should add that I've tried to answer the question, what spec-urls controls and conventions can we establish for all pages on MDN? I imagine that page types are the answer to imposing additional controls, but we'll probably always have some free-form page types or legacy content (particularly in translated content). My proposal was meant to speak to the whole site, without expanding the scope to require the implementation of page types or other methods of controlling page contents.

Interpreting "order of preference"

I'm not sure how to interpret "order of preference". Or to put it another way, why not just always do the most-preferred thing?

I meant it as a site-wide convention. I actually expect that, through page type definitions, we can be much more prescriptive about subsets of pages and we should do that. "Just" doing the most-preferred thing is a hard thing to stake out for the whole of the site.

Multiple URLs

I'm also not sure why setting multiple URLs is less preferred than setting one.

Two reasons:

1. It's not very explicit, but I think you've missed another option between one string and an array of two or more URLs: an array of one URL. I want to forbid that (like we do in BCD). This is a hard prescription implied by the list.
2. As a secondary matter, I was writing out my preference for parsimony. If you can successfully cover the topic with one spec URL, then why would you include two? If you can't, then, yes, you should set two or more URLs.

Errors for setting both keys

Three mentions of this case:

Am I right in reading this […] as saying that including both keys will give at least a warning?

Ideally I'd like us to treat [pages that have BCD, and BCD does not include a spec URL entry] as an error, but perhaps there's are legit exceptions?

I have not run into legit exceptions, and can’t readily imagine any.

Yes, I think we should at least warn on setting both keys. It's probably a smell. But I thought I've seen some pages that have compat and also mention related specifications—probably in HTTP docs where there are W3C and IETF specs at work—but I didn't have the time to look closely for them.

(Also, I imagined another possibility, which would be to use a specific compat key to drive status banners, while citing a different specification or the top-level of a spec.)

But if it's possible to forbid both without exception, then great. I'll amend the proposal.

Reference pages with BCD but set an alternative spec URL

Some reference pages which do have BCD but want to use a different spec URL for some reason

This is a known issue in BCD and should be fixed in BCD. I'd expect this would be a step in the overall project to implement. See mdn/browser-compat-data#13804

Macros with arguments

I think there's a case here for allowing {{Specifications("https://link/to/spec")}}

I think this would be acceptable as an intermediate step, but my preferences are toward:

1. Providing fewer ways to author things. Either the key is the only way it's done, or there ought be more unified way of richly citing/embedding non-MDN content.
2. Not committing to Kumascript-isms in Markdown.

In general, I'd really like to get away from macros as a way of embedding stuff in Markdown and it didn't feel like it was in scope for this discussion. That said, I'd like us to explore alternatives to Kumascript macro syntax, particularly the bits that are most unlike Markdown (in this case, arguments).

As an example of an alternative, consider that the spec-macro-with-arguments is a specific case of a more general need, which is to get some rich embed for non-MDN content. A much nicer alternative might be that if you include bare URLs by themselves in a block, they automatically get a pretty embed, whether that's a custom mechanism (e.g., for spec URLs or a YouTube video) or a more off-the-shelf social graph embed.

[sideshowbarker]

In the interest of having concrete cases to discuss, and in regard to the specific category of reference pages that currently have Specifications sections but that don’t have data in BCD, here’s a list of all the current pages in the api subtree in that category —

files/en-us/web/api/window/console/index.md                https://console.spec.whatwg.org/
files/en-us/web/api/cssomstring/index.md                   https://drafts.csswg.org/cssom/#cssomstring-type
files/en-us/web/api/canvasimagesource/index.md             https://html.spec.whatwg.org/multipage/scripting.html#canvasimagesource
files/en-us/web/api/document/rootelement/index.md          https://svgwg.org/svg2-draft/struct.html#__svg__SVGDocument__rootElement
files/en-us/web/api/filerequest/index.md                   https://w3c.github.io/filesystem-api/
files/en-us/web/api/filerequest/lockedfile/index.md        https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/abort/index.md              https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/active/index.md             https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/append/index.md             https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/filehandle/index.md         https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/flush/index.md              https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/getmetadata/index.md        https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/index.md                    https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/location/index.md           https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/mode/index.md               https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/onabort/index.md            https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/oncomplete/index.md         https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/onerror/index.md            https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/readasarraybuffer/index.md  https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/readastext/index.md         https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/truncate/index.md           https://w3c.github.io/filesystem-api/
files/en-us/web/api/lockedfile/write/index.md              https://w3c.github.io/filesystem-api/
files/en-us/web/api/epochtimestamp/index.md                https://w3c.github.io/hr-time/#the-epochtimestamp-typedef
files/en-us/web/api/cryptokeypair/index.md                 https://w3c.github.io/webcrypto/
files/en-us/web/api/aescbcparams/index.md                  https://w3c.github.io/webcrypto/#dfn-AesCbcParams
files/en-us/web/api/aesctrparams/index.md                  https://w3c.github.io/webcrypto/#dfn-AesCtrParams
files/en-us/web/api/aesgcmparams/index.md                  https://w3c.github.io/webcrypto/#dfn-AesGcmParams
files/en-us/web/api/aeskeygenparams/index.md               https://w3c.github.io/webcrypto/#dfn-AesKeyGenParams
files/en-us/web/api/eckeygenparams/index.md                https://w3c.github.io/webcrypto/#dfn-EcKeyGenParams
files/en-us/web/api/eckeyimportparams/index.md             https://w3c.github.io/webcrypto/#dfn-EcKeyImportParams
files/en-us/web/api/ecdhkeyderiveparams/index.md           https://w3c.github.io/webcrypto/#dfn-EcdhKeyDeriveParams
files/en-us/web/api/ecdsaparams/index.md                   https://w3c.github.io/webcrypto/#dfn-EcdsaParams
files/en-us/web/api/hkdfparams/index.md                    https://w3c.github.io/webcrypto/#dfn-HkdfParams
files/en-us/web/api/hmacimportparams/index.md              https://w3c.github.io/webcrypto/#dfn-HmacImportParams
files/en-us/web/api/hmackeygenparams/index.md              https://w3c.github.io/webcrypto/#dfn-HmacKeyGenParams
files/en-us/web/api/pbkdf2params/index.md                  https://w3c.github.io/webcrypto/#dfn-Pbkdf2Params
files/en-us/web/api/rsahashedimportparams/index.md         https://w3c.github.io/webcrypto/#dfn-RsaHashedImportParams
files/en-us/web/api/rsahashedkeygenparams/index.md         https://w3c.github.io/webcrypto/#dfn-RsaHashedKeyGenParams
files/en-us/web/api/rsaoaepparams/index.md                 https://w3c.github.io/webcrypto/#dfn-RsaOaepParams
files/en-us/web/api/rsapssparams/index.md                  https://w3c.github.io/webcrypto/#dfn-RsaPssParams
files/en-us/web/api/arraybufferview/index.md               https://webidl.spec.whatwg.org/#ArrayBufferView
files/en-us/web/api/buffersource/index.md                  https://webidl.spec.whatwg.org/#common-BufferSource
files/en-us/web/api/domtimestamp/index.md                  https://webidl.spec.whatwg.org/#common-DOMTimeStamp

[sideshowbarker]

I’ve come around to finding the following part of #5347 (reply in thread) pretty persuasive —

Macros with arguments

...
…my preferences are toward:

1. Providing fewer ways to author things. Either the key is the only way it's done, or there ought be more unified way of richly citing/embedding non-MDN content.
2. Not committing to Kumascript-isms in Markdown.

In general, I'd really like to get away from macros as a way of embedding stuff in Markdown and it didn't feel like it was in scope for this discussion. That said, I'd like us to explore alternatives to Kumascript macro syntax, particularly the bits that are most unlike Markdown (in this case, arguments).

I’ve been anxious to hear what @wbamberg thinks, but the part of #5347 (reply in thread) cited above has led me to conclude that it’d seem best if we could move toward always using only the spec-urls and browser-compat frontmatter keys and to never use the {{Specifications}} and {{Compat}} macros — in all cases, even for docs that aren’t reference docs with a consistent structure.

To that end, I’ve opened #5971 and #5972, which essentially will allow us to eliminate any need for passing arguments to the {{Specifications}} and {{Compat}} macros — and, ultimately, to completely eliminate need for the {{Compat}} and {{Specifications}} macros altogether.

[wbamberg]

I'm sorry to have not got back about this. I find this a bit hard to express.

My thinking is this: there are roughly three sorts of pages that might want to include spec tables:

1. structured pages that have a corresponding BCD entry. This is most cases: pages like CSS property pages, or JS method pages, or Web API interface pages, or HTML element pages. In this case we can say: a spec URL is a structured part of the documentation for the item, just like, say, the formal syntax for a CSS property. In this case the spec URL lives in BCD, so we satisfy this by putting a BCD query in the front matter, and the page builder can then use it to generate the spec table. At the moment, for pages like this, the {{Specifications}} macro exists only to tell the builder where to put the table. If we ever build pages from recipes, we no longer need it at all for these pages (and as Allow authors to omit the {{Compat}} and {{Specifications}} macros #5971 does, we could just use the H2#Specifications as a marker instead).

2. structured pages that don't have a corresponding BCD entry.. The main case here is API overview pages, like the Fetch API page. I don't know if there are any other legitimate cases actually. These are really just like case 1, except that we don't have a BCD entry to put the spec URL. Again though, we can say that a spec URL is a structured part of the documentation for the item, only in this case we can't use the BCD query, so we use a spec_urls front matter key instead. But again, we can eventually remove the {{Specifications}} macro entirely.

3. unstructured pages. These are pages that want to drop in specifications tables for arbitrary features, in arbitrary places. In cases like this it feels wrong, to me, to say that the spec URL is a part of the documentation for the item the page documents. Partly this is because the part might document lots of items, over various technologies. For example, a guide page about implementing themes in a site is not a documentation page for any particular CSS property, so to say that the BCD for that property belongs to that page feels wrong to me.

   This also comes out in practical ways, though. A guide page wants the freedom to be organized however it wishes. It doesn't want to be tied to have spec tables only in a H2#Specifications section. It wants the freedom to drop in multiple spec tables, for totally disparate features. So one thing that means is, there's no way you can get away from {{Specifications}}, because there's no fixed place where you put the thing. Also, if you want to have two spec tables in two different places, with different URLs in, how can you communicate this without an argument to the macro?

The alternative, it seems to me, is that we disallow spec tables in unstructured pages, and unstructured pages just link to specs using links. I would actually prefer this solution. But if we want to allow spec tables in unstructured pages, I think it is better to use a deliberately unstructured solution like a KS macro, rather than to shoehorn it into a structured content model.

(Another way to look at this is that it's like the difference in Hugo between "partials" and "shortcodes". They're both bits of code that generate some part of a page, but partials are part of the page structure, like a header or a footer, and are designed to fit into a defined page layout. Shortcodes are like functions you can call anywhere to insert that content.)

I'd really like to get away from macros as a way of embedding stuff in Markdown

I mean, me too, kind of. But if we have a need for pages to call into content-generating code in arbitrary places, then we have a need for macros.