ICU-22947 Update user guide for MF2

[catamorphism]

This PR updates the user guide for MF2, moving statements into the present tense instead of future tense. It also adds a section on ICU4C that, for now, links out to https://messageformat.dev .

Checklist

• Required: Issue filed: https://unicode-org.atlassian.net/browse/ICU-22947
• Required: The PR title must be prefixed with a JIRA Issue number. Example: "ICU-1234 Fix xyz"
• Required: The PR description must include the link to the Jira Issue, for example by completing the URL in the first checklist item
• Required: Each commit message must be prefixed with a JIRA Issue number. Example: "ICU-1234 Fix xyz"
• Issue accepted (done by Technical Committee after discussion)
• Tests included, if applicable
• API docs and/or User Guide docs changed or added, if applicable

[jira-pull-request-webhook]

Notice: the branch changed across the force-push!

• docs/userguide/format_parse/messages/mf2.md is different

View Diff Across Force-Push

~ Your Friendly Jira-GitHub PR Checker Bot

[catamorphism]

I'm not sure what to do about things like the table of functions, which I think is correct for ICU 75, but not consistent with the current MF2 spec.

[srl295]

I'm not familiar with this site, is it from MFv2 workign group? Is it implied that that content should be merged back here into this page?

[echeran]

That page's quickstart content looks great, and the site overall is wonderful too. But it's not currently a part of Unicode. @lucacasonato Would you be willing to upstream that content to the ICU User Guide? What are your plans?

I'm guessing @catamorphism wants to provide proper documentation for his ICU4C implementation work, and that overlaps with @lucacasonato's existing great work there.

Regardless, the current text in the PR makes it sound like the canonical documentation for using ICU4C MF2 is available externally. If we can upstream the content to the ICU User Guide, then I think it might be nice to link to messageformat.dev as the source for the contribution, if that's not too out of place for ICU documentation to do. Otherwise we consider rewording to make it clear that it's not the canonical source of docs.

messageformat.dev shows how much better we can aspire for Unicode docs to be, given how much benefit all of the projects & data & specs like this provide to people.

[srl295]

For comprehensive documentation on the C++ implementation, see the ICU API guide. The ICU User Guide contains general information on using ICU, but has not yet been updated to include MF2 documentation.

Upstreaming that page seems like it would be the best for all around- the page seems to anticipate such an update.

[lucacasonato]

@echeran Upstreaming is certainly an option, however the content would lose a lot of value if it was not accompanied by its interactive examples - can we just move the entire site into Unicode control and keep the content and interactive examples on the site as is (maybe change domain to a Unicode one?). Linking to it from the ICU docs should not be a problem then.

[catamorphism]

I just don't want to duplicate the content across two different web sites. I've been contributing my documentation to messageformat.dev so far, but if @lucacasonato wants to move the site under Unicode control, that would solve both problems.

[lucacasonato]

Could do that. But the mfwg repo has a completely different model when it comes to contributions. I for example would still like to have push access to be able to continue to develop the site.

[lucacasonato]

If we want to proceeed with this, I think these are the steps:

• move the repo into unicode-org as message-format-website or something like that
  • i and @catamorphism continue to have commit access to the repo, so we can continue work on the site + docs content
• figure out whether we need to relicense under Unicode license, or whether MIT and CC-BY is OK
• either we keep the messageformat.dev domain, and i transfer it to Unicode, or we change the canonical domain to messageformat.unicode.org and I'll keep the .dev as a redirect until it expires
• we figure out whether anything needs to change on the site to be inline with any Unicode brand guidelines
  • one thing in particular is the logo I designed for MF: is this something Unicode is OK with, and if so can it be transferred into Unicode custody, or is there alternative branding that Unicode would like to use

Maybe we can have a short 30 minute call about this this week with interested parties? (Or if we can figure this all out thru issues, that works for me too.)

[srl295]

@lucacasonato yes that might be good to discuss. I'll raise this with the Unicode infrastructure team also to get that discussion started.

@echeran Upstreaming is certainly an option, however the content would lose a lot of value if it was not accompanied by its interactive examples

I might suggest that the pages that are C++ and Java specific seem like they would be better fits in the ICU userguide because it's a guide to using the API related to but independent from the MF2 syntax. They could certainly link back and forth to the MF2 site (wherever that lives per other discussion.)

[srl295]

@lucacasonato I'm working on getting the meeting together. This week is Unicode's UTW conference, so might be challenging time wise.

Who on this thread needs to be included besides @lucacasonato @echeran @catamorphism ?

[echeran]

That group is good for now. Yes, this week is UTW, and also the final release cut for ICU v76 is planned for this week too, so I appreciate meeting next week. Thanks!

[srl295]

Changes generally LGTM but a question about messageformat.dev

[jira-pull-request-webhook]

Hooray! The files in the branch are the same across the force-push. 😃

~ Your Friendly Jira-GitHub PR Checker Bot