w3c / string-meta

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

Restructuring proposal for NOTE publication #45

Open r12a opened 4 years ago

r12a commented 4 years ago

I read through the document, looking for ways to help people get to the information more quickly and slim down the document, and came up with the following suggestions. Compare this TOC to the current one at https://www.w3.org/TR/2019/WD-string-meta-20190611/

@aphillips what do you think ? (In parallel i'll produce a PR for editorial changes, but it won't include this reorg.)

1. Introduction
    1.1 Terminology
    1.2 The String Lifecycle
        1.2.1 Producers
        1.2.2 Consumers
        1.2.3 Serialization Agreements
2. Best Practices, Recommendations, and Gaps
    2.1 Resource-wide defaults
    2.2 String-specific language information
    2.3 String-specific directional information
    2.4 Other approaches
3. Requirements and Use Cases
    This section should point the reader to the article proposed below.
    1.3 Why is this important?
        1.3.1 An Example
    1.4 Isn't Unicode Enough?
    3.2.7 What consumers need to do

(the rest of this list remains the same as what we currently have)

4. Approaches Considered for Identifying the Base Direction
    4.1 First-strong property detection
        4.1.1 How it works
        4.1.2 Advantages
        4.1.3 Issues
        4.1.4 Additional notes
    4.2 Metadata
        4.2.1 How it works
        4.2.2 Advantages
        4.2.3 Issues
    4.3 Augmenting "first-strong" by inserting RLM/LRM markers
        4.3.1 How it works
        4.3.2 Advantages
        4.3.3 Issues
    4.4 Paired formatting characters
        4.4.1 How it works
        4.4.2 Advantages
        4.4.3 Issues
    4.5 Script subtags
        4.5.1 How it works
        4.5.2 Advantages
        4.5.3 Issues
        4.5.4 Other comments
    4.6 Require bidi markup for content
        4.6.1 How it works
        4.6.2 Advantages
        4.6.3 Issues
    4.7 Create a new bidi datatype
        4.7.1 How it works
        4.7.2 Advantages
        4.7.3 Issues
5. Approaches Considered for Identifying the Language of Content
    5.1 Metadata
        5.1.1 How it works
        5.1.2 Advantages
        5.1.3 Issues
    5.2 Require markup for content
        5.2.1 How it works
        5.2.2 Advantages
        5.2.3 Issues
    5.3 Use Unicode language tag characters
        5.3.1 How it works
        5.3.2 Advantages
        5.3.3 Issues
    5.4 Use a language detection heuristic
        5.4.1 How it works
        5.4.2 Advantages
        5.4.3 Issues
6. Localization Considerations
A. The Localizable WebIDL Dictionary
B. Acknowledgements
C. References
    C.1 Informative references

I propose to completely remove the following sections and to publish them in an article. Because this information is useful to people who don't need to read the other stuff. The title of the article will be something like "Why is language and base direction metadata important?"

    3.1 Identifying the Language of Content
        3.1.1 Definitions
        3.1.2 Language Tagging Use Cases
            3.1.2.1 Capturing the language of the audience
            3.1.2.2 Capturing the text-processing language
            3.1.2.3 Additional Requirements for Localization
    3.2 Identifying the Base Direction of Content
        3.2.1 Final punctuation
        3.2.2 Initial Latin
        3.2.3 Bidirectional text ordering
        3.2.4 Interpreted HTML
        3.2.5 Neutral LTR text
        3.2.6 Spill-over effects
aphillips commented 4 years ago

I like this generally.

The current section 3.2 is the part of the document I refer others to the most. I think it would be great to make an article out of it. But I'd probably want to integrate some of that material into what is now section 1.3 (why is this important) so that readers of string-meta have a clear view of the requirements in mind. Something along the lines of:

For a full exploration of the role of language and direction see our article [xxx]. To briefly summarize, ... [language example] ... [direction example showing spillover and end effects]