RFR: JDK-8298405: Support Markdown in the standard doclet [v2]

[Jonathan Gibbons]

On Mon, 9 Jan 2023 17:55:05 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with five additional commits since the last revision:
>> 
>>  - Update copyright years
>>  - Rename FFFC variable
>>    Share Markdown parser and renderer in instance of MarkdownHandler
>>  - Move CommonMark to new internal module.
>>    Add legal header to imported CommonMark source files
>>    Always use Text nodes inside AttributeTree values
>>    Unwrap <p> from "simple" paragraphs
>>  - Always use Text nodes inside AttributeTree values
>>  - Update to CommonMark 0.21.
>
> src/jdk.internal.md/share/classes/jdk/internal/org/commonmark/internal/util/Html5Entities.java line 47:
> 
>> 45: 
>> 46:     private static final Map<String, String> NAMED_CHARACTER_REFERENCES = readEntities();
>> 47:     private static final String ENTITY_PATH = "/org/commonmark/internal/util/entities.txt";
> 
> I see that you've added the missing `entities.properties` file, but renamed it to `entities.txt`. IIRC from our offline chat, it's due to how JDK build treats `.properties` files.
> 
> I wonder what would be better: (a) to keep the original extension, but amend the build to ignore this file, or (b) to do what you've done and possibly suggest a PR for CommonMark to do the same.  
> 
> On the one hand, it's not a true Java `.properties` file as one might've though from its extension. On the other hand, this change of yours diverge us from the original snapshot of CommonMark.

I like your option *(b)*
* retain the change to use `entities.txt`
* report the issue to CommonMark, if not actually suggest a PR.

FWIW, the rename is handled automatically by the process I use to import the source code.  I think that automated fix-up is acceptable; manual fix-up that would be needed every time we update the source would not be acceptable.

-------------

PR: https://git.openjdk.org/jdk/pull/11701