ocsigen / ocsigen/tyxml

Consistent naming scheme for html and svg elements.

Open
#72 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

breaking html & svg standard
Dominant language
OCaml
Stars
179
Forks
63
Avg merge
5h
Merged PRs (30d)
22

Description

Consistency is not W3C's strong point, but it's made worse in tyxml. The main pain point is dashes, since they are not valid in ocaml's identifiers.

So a more formal version of what we are currently loosely applying:

  • We always keep the name in the specification if it's a valid ocaml identifier, be it snake_case, nocase, CamlCase or whatever, even if it's internally inconsistent (I'm looking at you, fontFace)

  • Dashes are transformed in underscores systematically.

  • Underscores are kept.

  • Any other characters that could ever appear are transformed in an underscore too. I don't think I ever saw one, but better be sure.

  • In case of conflict between attributes of incompatible types. We put the element that it's disambiguated for between underscores, after the a.

    Example: the attribute max for input is transformed in a_input_max.

  • Specific transformation rules:

    • When transforming to an element, the first letter become a lowercase.
    • When transforming to a polymorphic variant, the first letter is capitalized. This is not mandatory (since polymorphic variant can start with a lowercase), but it's acceptable and is already applied almost consistently, so better keep it.
    • When transforming to an attribute, no letter is changed (it's ok, it starts with a_).

These should also keep the breaking rather minimal. Remarks ?
cc @dsheets since you might have an opinion. :)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the current naming rules for HTML and SVG elements, attributes, and polymorphic variants in tyxml, then compare them with the transformations listed in the issue. Done means the naming scheme is agreed on and applied consistently with minimal breaking changes; the issue does not name specific files or tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
html, ocaml
Domain
frontend, web-dev
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.