User:Dominic Mayers/sandbox

Some preliminaries are needed. The Cite extension processes <ref>...</ref> tags to create ref items in <references>...</references> tags and ref links toward these ref items. The tags are parsed in the wikitext source code whereas the ref links and ref items are created in the html. The errors are separated in different categories shown in the following subsections. The first two subsections are about the errors that can be seen before the creation of the ref links and ref items, only looking at each tag individually, for example, without considering if an other ref tag will later provide the content for the associated ref link. The third subsection is for the validation of tags after the text is processed, but before the corresponding <references>...</references> tag has been entirely processed. The fourth subsection is for errors in ref items that can only be seen after all the ref tags for the corresponding <references>...</references> tag have been processed. For example, a missing key error belongs in that third category. The fifth subsection is about the errors that can only be seen at the end, after all <references>...</references> tags have been processed.

The ref tags listed in a <references>...</references> tag are special, because these in list tags must create a ref item in the same <references>...</references> tag and they cannot create a ref link. In contrast, the other tags, the ones that are not in list, but in the body of the wikitex, always create a ref link toward a potential ref item. They might or might not create a ref item.

Some preliminaries are needed. The Cite extension processes <ref>...</ref> tags to create ref items in <references>...</references> tags and ref links toward these ref items. The tags are parsed in the wikitext source code whereas the ref links and ref items are created in the html. The errors are separated in different categories shown in the following subsections. The first two subsections are about the errors that can be seen before the creation of the ref links and ref items, only looking at each tag individually, for example, without considering if an other ref tag will later provide the content for the associated ref link. The third subsection is for the validation of tags after the text is processed, but before the corresponding <references>...</references> tag has been entirely processed. The fourth subsection is for errors in ref items that can only be seen after all the ref tags for the corresponding <references>...</references> tag have been processed. For example, a missing key error belongs in that third category. The fifth subsection is about the errors that can only be seen at the end, after all <references>...</references> tags have been processed.

The ref tags listed in a <references>...</references> tag are special, because these in list tags must create a ref item in the same <references>...</references> tag and they cannot create a ref link. In contrast, the other tags, the ones that are not in list, but in the body of the wikitex, always create a ref link toward a potential ref item. They might or might not create a ref item.

Category 1: Errors immediately seen in a tag that is not in list

This subsection is about the errors that can be seen before the creation of the ref links and ref items, but it considers only tags that are not in list. Here are errors in that category:

• The name of the tag is of a numeric type (the corresponding key can be confused with a numeric key received by an anonymous tag).
• An opening ref tag (named "notclosing") without its matching closing tag. With the issue T3310, which is not going to be addressed soon, if ever, the long text in between the non closed tag and this sentence is simply considered as the content of the previous tag.

Category 2: Same as category 1, but for in list tags

1. The ref tag is in list and has a mismatching group.
2. The ref tag is in list and has no name. It is not possible to have a link to such an item that has no name. To illustrate this error, a {{Refn|group=missingName}} tag is created in the section References du group missingName below.

Category 3: Errors seen after the text is processed

1. A ref item processed in a references tag has no text. This includes an in list ref tag that has no text. This latter case is in the third category, because the text could be a template variable for an empty content.

Category 4: Errors seen after the entire references tag is processed

1. The same key is used for two different contents.
2. A ref item processed in a references tag has missing links. Obviously, it is not possible have a link toward this wrong ref item. To illustrate this error, a {{Refn|group=missingLink|name=nolink}} tag is created in the section References du group missingLink below.

Category 5: Errors (due to a missing references tag) seen only at the end

These are the errors created when a ref link does not have a current or subsequent references tag for its group. These errors are created by ref links, because, by definition, an in list tag has its references tag and the other tags correspond to ref links. There are three sub-cases (which we will not distinguish):

2. In addition, the ref link has missing content.
3. In addition, the ref link has a content still in the stack, only the references tag is missing.
4. In addition, the ref link has a content but it is in a previous references tag, thus removed from the stack

• By definition, errors in that category cannot be localized within a references tag, because they are due to a missing references tag. Here a call is made toward an in list ref named Nb4 in group test-b that tries to refer to ref named Nb5 in the previous group test-a. This creates an error that will be detected at the end, because Nb5 has no corresponding current or subsequent group: the group test-a exists in the wikitext, but it was a thing of the past removed from the stack at the time Nb5 was processed in group test-b.
• Here, still in the fourth type, both the ref Nb8 in group test-b and and its nested ref Nb9 in the previous group test-a are in list. It does not help. Yes, Nb9 was processed in group test-a, because it is in list, but the entire group is discarded at the time test-b is processed. Actually, Nb9 in group test-a would itself have a missing link error, if I would not refer to it here.

Other errors

There are also the errors created because <ref>...</ref> tags are directly nested (i.e., without hiding them in {{Refn}} templates). It is hard to predict how the error will show up.

• This ref link, which is/constains a nested ref tag</ref> fails unless Parser.php finds the balanced closing tag. If you see it works (in the references tags below) it's because a patch was applied to the parser so that it attempts to find the balanced closing tag and succeed in many cases. Unfortunately, such a patch can hardly be guaranteed to work in all cases, because the wikitex language was never designed to be parsed in this way. Therefore, the parser is not designed to accept directly nested <ref>...</ref> tags. Instead, use {{Refn}} templates.
• With a parser that finds the balanced closing angle tag even that wikitex

  <ref>Ar<ref>Br<ref>Cr<ref>Dr</ref></ref></ref></ref>
  

  should work. It fails with the current parser. See it here.</ref></ref></ref>

References

Category 2: Same as category 1, but for in list tags

1. The ref tag is in list and has a mismatching group.
2. The ref tag is in list and has no name.

Category 3: Errors seen after the text is processed

1. A ref item processed in a references tag has no text. This includes an in list ref tag that has no text. This latter case is in the third category, because the text could be a template variable for an empty content.

Category 4: Errors seen after the entire references tag is processed

1. The same key is used for two different contents.
2. A ref item processed in a references tag has missing links. Obviously, it is not possible have a link toward this wrong ref item. To illustrate this error, a {{Refn|group=missingLink|name=nolink}} tag is created in the section References du group missingLink below.

Category 5: Errors (due to a missing references tag) seen only at the end

These are the errors created when a ref link does not have a current or subsequent references tag for its group. These errors are created by ref links, because, by definition, an in list tag has its references tag and the other tags correspond to ref links. There are three sub-cases (which we will not distinguish):

2. In addition, the ref link has missing content.
3. In addition, the ref link has a content still in the stack, only the references tag is missing.
4. In addition, the ref link has a content but it is in a previous references tag, thus removed from the stack

• By definition, errors in that category cannot be localized within a references tag, because they are due to a missing references tag. Here a call is made toward an in list ref named Nb4 in group test-b that tries to refer to ref named Nb5 in the previous group test-a. This creates an error that will be detected at the end, because Nb5 has no corresponding current or subsequent group: the group test-a exists in the wikitext, but it was a thing of the past removed from the stack at the time Nb5 was processed in group test-b.
• Here, still in the fourth type, both the ref Nb8 in group test-b and and its nested ref Nb9 in the previous group test-a are in list. It does not help. Yes, Nb9 was processed in group test-a, because it is in list, but the entire group is discarded at the time test-b is processed. Actually, Nb9 in group test-a would itself have a missing link error, if I would not refer to it here.

Other errors

There are also the errors created because <ref>...</ref> tags are directly nested (i.e., without hiding them in {{Refn}} templates). It is hard to predict how the error will show up.

• This ref link, which is/constains a nested ref tag</ref> fails unless Parser.php finds the balanced closing tag. If you see it works (in the references tags below) it's because a patch was applied to the parser so that it attempts to find the balanced closing tag and succeed in many cases. Unfortunately, such a patch can hardly be guaranteed to work in all cases, because the wikitex language was never designed to be parsed in this way. Therefore, the parser is not designed to accept directly nested <ref>...</ref> tags. Instead, use {{Refn}} templates.
• With a parser that finds the balanced closing angle tag even that wikitex

  <ref>Ar<ref>Br<ref>Cr<ref>Dr</ref></ref></ref></ref>
  

  should work. It fails with the current parser. See it here.</ref></ref></ref>

References