Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem/Motivation
State what you believe is wrong or missing from the current standards.
Benefits
If we adopted this change, the Drupal Project would benefit by ...
Three supporters required
- https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)
- https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)
- https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)
Proposed changes
See #5
The original proposal had these options
... the SPAN element
... the span element
... the <span> element
1. {link to the documentation heading that is to change}
Current text
Add current text in blockquotes
Proposed text
When referring to HTML tags by name in textual documentation, always use angle brackets, lowercase, and no closing tag, e.g.:
<em>. If you are providing a code snippet, use @code/@endcode instead.
2. Repeat the above for each page or sub-page that needs to be changed.
Remaining tasks
Create this issue in the Coding Standards queue, using the defined template- Add supporters
- Create a Change Record
- Review by the Coding Standards Committee
- Coding Standards Committee takes action as required
- Discussed by the Core Committer Committee, if it impacts Drupal Core
- Final review by Coding Standards Committee
- Documentation updates
- Edit all pages
- Publish change record
- Remove 'Needs documentation edits' tag
- If applicable, create follow-up issues for PHPCS rules/sniffs changes
For a full explanation of these steps see the Coding Standards project page
Comments
Comment #2
jhodgdonJust to clarify a few things:
a) I think that this proposal is limited to making a standard for how to refer to HTML tags in PHP API documentation (the doc blocks in files). Correct?
b) Assuming that is the case, I would also note that the API module is fine with things like
or things like that -- and by "fine with" I mean that it will output it as
<p>so that it looks like <p> on the api.drupal.org page.Anyway, I think the issue summary needs an update to clarify the scope of this question.
Comment #3
joachim commented> I think that this proposal is limited to making a standard for how to refer to HTML tags in PHP API documentation (the doc blocks in files). Correct?
Yup. Retitling, but feel free to improve if you like.
Comment #4
jhodgdonOn #2546248: Use consistent style to mention HTML tags in code comments, we discussed this, and it was noted that most places in Core, we are just putting the tag in verbatim. Example would be:
This seems to be the de-facto standard, and the API module handles this type of comment fine on api.drupal.org. So, if we are going to adopt a standard, that is the standard I think we should adopt.
Comment #5
xjmWe just committed a cleanup related to this in #2546248: Use consistent style to mention HTML tags in code comments. In that issue, we implicitly adopt the standard to always use lowercase and angle brackets in comments.
I took a stab at describing the standard adopted there:
We could also create a rule that checks for uppercase tags, e.g.
<HTML>, and indicates that they should be lowercase.Comment #6
andypostSuppose we need a new sniffer and child issue for #2571965: [meta] Fix PHP coding standards in core, stage 1 to apply the sniffer
Comment #7
quietone commentedConvert to new template.
This needs to suggest the page where the proposed text is to be added.
Comment #8
xjmAmending attribution.