tidy-html5/README/ATTRIBUTES.md

# Tidy Element Attributes

This is about adding a **new** HTML attribute to one or more HTML tags, i.e., a new attribute such as `attribute=value`.

Tidy’s large number of attributes are supported via number of files:

  - `tidyenum.h` is where you first define a new attribute in order to give it an internal value.
  - `attrs.c` is where you give a unique **string** name to the attribute, as well as a **function** to verify the **value**.
  - `attrdict.c` further refines the definition of your attribute, specifying which version(s) of HTML support this attribute.
  - `tags.c`, finally, determines which tags support the attribute, in the `tag_defs[]` table.

So, to add a new `attribute=value`, on one or more existing tags, consists of the following simple steps -

 1. `tidyenum.h` - Give the attribute an internal name, like `TidyAttr_XXXX`, and thus a value. Please try to keep this enumeration in alphabetical order.

 2. `attrs.c` - Assign the string value of the attribute. Of course this must be unique. And then assign a `function` to verify the attribute value. There are already a considerable number of defined functions to verify specific attribute values, but maybe this new attribute requires a new function, so that should be written, and defined.
 
 3. `attrdict.c` - If this attribute only relates to specific tags, then it should be added to their list. There are some general attributes that are allowed on every, or most tags, so this new attribute and value should be added accordingly.
 
 4. `tags.c` - Now the new attribute will be verified for each tag it is associated with in the `tag_defs[]` table. Like for example the `<button ...>`, `{ TidyTag_BUTTON, ...` has `&TY_(W3CAttrsFor_BUTTON)[0]` assigned.

So, normally, just changing 3 files, `tidyenum.h`, `attrs.c`, and `attrdict.c`, will already adjust `tags.c` to accept a new `attribute=value` for any tag, or all tags. Simple...

Now, one could argue that this is not the **best** way to verify every attribute and value, for every tag, but that is a moot point - that is how Tidy does it!

; eof 20170205
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
+								# Tidy Element Attributes
-												Update README documents with information for the upcoming 5.4.0 release.

											
										
										
											2017-02-24 16:58:30 +00:00
+								This is about adding a **new** HTML attribute to one or more HTML tags, i.e., a new attribute such as `attribute=value`.
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
-												Update README documents with information for the upcoming 5.4.0 release.

											
										
										
											2017-02-24 16:58:30 +00:00
+								Tidy’s large number of attributes are supported via number of files:
 								  - `tidyenum.h` is where you first define a new attribute in order to give it an internal value.
 								  - `attrs.c` is where you give a unique **string** name to the attribute, as well as a **function** to verify the **value**.
 								  - `attrdict.c` further refines the definition of your attribute, specifying which version(s) of HTML support this attribute.
 								  - `tags.c`, finally, determines which tags support the attribute, in the `tag_defs[]` table.
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
 								So, to add a new `attribute=value`, on one or more existing tags, consists of the following simple steps -
-												Continue the documentation effort!
- Many, many updates to the public header files.
- tidyenum.h was reorganized substantially in order to better generate
  documentation with Doxygen.
- This was also a good time to clean up all of the various enums for languages
  and strings. Everything is simple and in a single enum now, other than a
  couple of cases (TidyOptionId, for example, doesn't need to be redefined).
- A full and complete audit of the strings meant some opportunities to delete
  useless strings.
- Reorganized the order of the strings in language_en.h in order to better
  find things when programmers want to make changes. There are a lot fewer
  internal "sections" now, and everything has been painstakingly sorted within
  the remaining sections.
- Consequently rebased all of the PO's, POT, and other language files.
- Updated several of the READMEs with the newest information.
- Made the READMEs easier to copy into the Doxygen project by changing some of
  the code format for compatibility, mainly the use of tildes instead of
  backslashes for code blocks.
- Added tidyGetMessageCode() to message API. Despite the huge diff, this is the
  only externally-visible change, other than removing some enums (but not their
  values!).
- Passing `next` tests on Mac, Linux, Win10.

											
										
										
											2017-03-21 01:07:53 +00:00
+. `tidyenum.h` - Give the attribute an internal name, like `TidyAttr_XXXX`, and thus a value. Please try to keep this enumeration in alphabetical order.
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
-												Update README documents with information for the upcoming 5.4.0 release.

											
										
										
											2017-02-24 16:58:30 +00:00
+. `attrs.c` - Assign the string value of the attribute. Of course this must be unique. And then assign a `function` to verify the attribute value. There are already a considerable number of defined functions to verify specific attribute values, but maybe this new attribute requires a new function, so that should be written, and defined.
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
-												Update README documents with information for the upcoming 5.4.0 release.

											
										
										
											2017-02-24 16:58:30 +00:00
+. `attrdict.c` - If this attribute only relates to specific tags, then it should be added to their list. There are some general attributes that are allowed on every, or most tags, so this new attribute and value should be added accordingly.
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
-												Continue the documentation effort!
- Many, many updates to the public header files.
- tidyenum.h was reorganized substantially in order to better generate
  documentation with Doxygen.
- This was also a good time to clean up all of the various enums for languages
  and strings. Everything is simple and in a single enum now, other than a
  couple of cases (TidyOptionId, for example, doesn't need to be redefined).
- A full and complete audit of the strings meant some opportunities to delete
  useless strings.
- Reorganized the order of the strings in language_en.h in order to better
  find things when programmers want to make changes. There are a lot fewer
  internal "sections" now, and everything has been painstakingly sorted within
  the remaining sections.
- Consequently rebased all of the PO's, POT, and other language files.
- Updated several of the READMEs with the newest information.
- Made the READMEs easier to copy into the Doxygen project by changing some of
  the code format for compatibility, mainly the use of tildes instead of
  backslashes for code blocks.
- Added tidyGetMessageCode() to message API. Despite the huge diff, this is the
  only externally-visible change, other than removing some enums (but not their
  values!).
- Passing `next` tests on Mac, Linux, Win10.

											
										
										
											2017-03-21 01:07:53 +00:00
+. `tags.c` - Now the new attribute will be verified for each tag it is associated with in the `tag_defs[]` table. Like for example the `<button ...>`, `{ TidyTag_BUTTON, ...` has `&TY_(W3CAttrsFor_BUTTON)[0]` assigned.
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
 								So, normally, just changing 3 files, `tidyenum.h`, `attrs.c`, and `attrdict.c`, will already adjust `tags.c` to accept a new `attribute=value` for any tag, or all tags. Simple...
-												Update README documents with information for the upcoming 5.4.0 release.

											
										
										
											2017-02-24 16:58:30 +00:00
+								Now, one could argue that this is not the **best** way to verify every attribute and value, for every tag, but that is a moot point - that is how Tidy does it!
-												Add README for new 'attributes' and 'elements', 'tags'

											
										
										
											2017-02-05 16:27:28 +00:00
 								; eof 20170205