search

w3c / string-meta

How to add direction and language metadata to strings
https://w3c.github.io/string-meta/
12 stars 18 forks source link

Make decoration note consistent with other I18N specs #71

Closed aphillips closed 2 years ago

aphillips commented 2 years ago

I have been making all of our current WG Note documents use a consistent "example req" note. In a recent PR, @r12a commented out the gap style that is not currently used. In this PR I restore it using the correct style name (issue) and add the example of a terminology definition.

Note that we use the style issue-example (which I add to local.css) because issue has an auto-counter we don't want to trigger.

An argument can be made that we should omit the issue example until it is needed by this document. Thoughts?

Preview | Diff

netlify[bot] commented 2 years ago

Deploy Preview for string-meta ready!

Name Link
Latest commit 01671f73e3974079c890b89ca9f0aa5f133a2301
Latest deploy log https://app.netlify.com/sites/string-meta/deploys/62e2af5fa8057200089f5afc
Deploy Preview https://deploy-preview-71--string-meta.netlify.app/
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

r12a commented 2 years ago

I was looking at this yesterday and it seems to me that the content of this note is in the wrong place. I think we should:

  1. remove the note markup
  2. put it in it's own subsection called something like "Conventions"
  3. move that section to the Introduction, immediately before the Terminology subsection (so that terminology conventions are described before they are used)

I also think that we should at least comment out (not remove) the gap description until we have some gaps. However, that said, i think it would actually make more sense to the reader to use issue markup for these items. I also like that issues have a heading that says what it is.

aphillips commented 2 years ago

This particular document has the note in a weird place. Our other docs have it in different places, but it generally goes were the 2119 keyword definition goes.

We could put it into a potted section we include like "Conventions", although I note that many of our docs have "Terminology and Notation" types of section.

This PR changes to use issue notation for gaps--not gap.

In the editor's copy I favor leaving uncommented. We can comment it out when publishing to TR if there are no open issues.

r12a commented 2 years ago

In the editor's copy I favor leaving uncommented. We can comment it out when publishing to TR if there are no open issues.

Despite echidna's promise, it's still often a pain to publish documents, and if i'm publishing i'd rather not have to remember to comment that out each time. Why don't you want to comment it out if there are no such issues?

aphillips commented 2 years ago

I don't want to have to remember to put it back as a style when I use issue! Actually, we could automate issue-example's appearance with a little JS at the end of the document (checking on the value of the issue counter and only showing the style if non-zero). I'll try adding that to the PR.

aphillips commented 2 years ago

Merging so that I can complete my action item. Can fix any styling nits as needed.