search

ietf-tools / xml2rfc

Generate RFCs and IETF drafts from document source in XML according to the IETF xml2rfc v2 and v3 vocabularies
https://ietf-tools.github.io/xml2rfc/
BSD 3-Clause "New" or "Revised" License
68 stars 38 forks source link

misleading warning about .ent files #992

Open reschke opened 1 year ago

reschke commented 1 year ago

Describe the issue

The warning

"Warning: /home/rgm/data/htt/Projects/Critical/drafts/rfc2629-xhtml.ent is no longer needed as the special processing of non-ASCII characters has been superseded by direct support for non-ASCII characters in RFCXML."

is completely misleading. From an XML point of view, it doesn't make any difference whether you declare an entity reference like "\ " for "\ ", or use that character literally in the source file. Both is valid, and has been valid all the time.

Code of Conduct

rjsparks commented 1 year ago

What text would you suggest as less misleading?

reschke commented 1 year ago

I don't think there should be a warning at all, unless the file is included from an unsafe location.

JayDaley commented 1 year ago

I disagree on removing the warning entirely. While it is true that character entities are perfectly valid, we have two clear problems here:

  1. We have a set of people who believe that they need to include this file as some sort of secret sauce that makes xml2rfc work rather than because they understand what it is there for. These people need to be warned that this file is not needed to make things work.
  2. We have inadvertently trained some people to think that they must use character entities instead of directly inserting the character. This file is particularly egregious there because it contains entities for many characters that would almost always be inserted directly, such as the accented latin characters. Because of that, we should still be warning people about the use of this file, and encouraging people to specifically pick the character entities that they want to use and declare those directly rather than rely on this file.

I would be happy if we changed the text to be clearer about these, to something like "Please note that rfc2629-xhtml.ent is not required and if you are not using character entities listed then you should not include it. If you are using character entities, the recommended method is to declare those directly rather than include this file."

reschke commented 1 year ago

That sounds good. Maybe even include the web site link you mentioned in the mail thread.

rgmhtt commented 1 year ago

And for those people that have carried it forward in newer drafts from old work when it was required. For them to get with the times.

:)