Tags

[mattesmohr]

Wich kind of naming should we go for, when it comes to tags? Currently I am bit confused, if there is a common ground?

Actually there is P {} wich is <p></p>. But there is Italic {} wich is <i></i>.

I am fan of clarity, so should we write it out in full? What do you think?

For example:

<pre></pre> Preformate {} or Pre {}

[MatsMoll]

Hmm 🤔 That is a good question, and it is currently inconsistent which is unfortunate.

Now I personally like the more descriptive names like Italic, Bold, etc. As I find it easier to resonate, and reason over. However, it might be a bit confusing for people coming from HTML, and therefore might struggling to find the correct tags.

Therefore I might think it might make sense with both, where one is a type alias for the other.

E.g:

struct Preformate: ContentNode {
   ...
}

typealias Pre = Preformate

Or do you have any other opinions?

[mattesmohr]

I agree. I am with you on that. The descriptive way seems more readable and I am a fan of it in all my code, but in this case (as HTMLKit) I like the idea being as close as possible to HTML.

Since I have no good idea how we should define tags like <h1></h1>, <h2></h2> or <kbd></kbd> the html-approach seems the easiest way to do so.

If you have nothing against struct Heading1: ContentNode { ... }, I would go with the typealias-approach as you mentioned. I think it is the best of both worlds. I wouldn't have think of it in first place.

<kbd></kbd> would be struct Keyboard: ContentNode { ... } in this case for example. Do you think it is intuitive enough?

Or should I write down all the tags I think are discussable and we talk about it?

[mattesmohr]

Div is a good example as well. Div would be struct Devision: ContentNode { ... }

Would the typealias-approach prevent that everyone has to rework their code also?

[MatsMoll]

I have nothing against the Heading1, so go ahead!

The type alias will make it backward compatible as we never remove any tags, so the old HTMLKit code should be able to run with the new tag changes.

About the kbd tag. I have never used it, but if it is intended as keyboard input or something, then I think the describable name would be appropriate. It is at least much better than kbd 😄
So for me, it is easier if you create a declarative name that you think fits and create a PR, and then I will probably add a comment on the PR if I have any questions or opinions. I think this will make the workflow a bit smoother, and faster as well

[mattesmohr]

Okay. That sound like a plan. Will do. :-)

[mattesmohr]

Here is a list of the aliases, wich I think fit the best. Overall I have tried to stick with the official names. By the way it was fun to browse through the old official HTML documentations and to read the discussions, about implementation, name conventions etcetera.

Aliases

public typealias Nav = Navigation
public typealias H1 = Heading1
public typealias H2 = Heading2
public typealias H3 = Heading3
public typealias H4 = Heading4
public typealias H5 = Heading5
public typealias H6 = Heading6
public typealias Hgroup = HeadingGroup
public typealias P = Paragraph
public typealias Hr = HorizontalRule
public typealias Pre = PreformattedText
public typealias Ol = OrderedList
public typealias Ul = UnorderedList
public typealias Li = ListItem
public typealias Dl = DescriptionList
public typealias Dt = TermName
public typealias Dd = TermDefinition
public typealias Figcaption = FigureCaption
public typealias Div = Division
public typealias A = Anchor
public typealias Em = Emphasized
public typealias S = StrikeThrough
public typealias Q = ShortQuote
public typealias Dfn = Definition
public typealias Abbr = Abbreviation
public typealias Rt = RubyText
public typealias Rp = RubyPronunciation
public typealias V = Variable
public typealias Samp = SampleOutput
public typealias Kbd = KeyboardInput
public typealias Sub = Subscript
public typealias Sup = Superscript
public typealias I = Italic
public typealias B = Boldface
public typealias U = Underline
public typealias Bdi = BiDirectionalIsolation
public typealias Bdo = BiDirectionalOverride
public typealias Br = LineBreak
public typealias Wbr = WordBreak
public typealias Ins = InsertedText
public typealias Del = DeletedText
public typealias Img = Image
public typealias Iframe = InlineFrame
public typealias Param = Parameter
public typealias Colgroup = ColumnGroup
public typealias Col = Column
public typealias Tbody = TableBody
public typealias Thead = TableHead
public typealias Tfoot = TableFoot
public typealias Tr = TableRow
public typealias Td = DataCell
public typealias Th = HeaderCell
public typealias Optgroup = OptionGroup

Undecided

There are some of the aliases I am not satisfied with:

public typealias B = Boldface

Boldface is the official term for the element, but I think Bold is the more common name nowadays.

public typealias S = StrikeThrough

Since we have the variant "Underline" or "Emphasized", I am not sure if we should use Simple Present or Simple Past. Or maybe it just me, overthinking it.

public typealias Bdi = BiDirectionalIsolation
public typealias Bdo = BiDirectionalOverride

In this case I think the alias is too long. But I couldn't find any better term for now.

Deprecated

There already were two aliases.

@MatsMoll: Should we keep them?

public typealias Hyperlink = Anchor
public typealias Acronym = Abbreviation

[MatsMoll]

Nice work!

I think that B could be Bold as that is what I feel is the most common to describe it by.

It is also nice that you are aware of the simpe present and simple past, as it is details polish the develop experience. However, Linguists is not my biggest strength. So maybe Bold, StrikeThrough, Emphasise is better?

When it comes to BiDirectionalIsolation I agree it is too long. So maybe this is a case where only the acronym is better?

Also the I think that the Hyperlink and Acronym might be unnecessary, even tho it is multiple descriptive names. So yes, we could remove them

[mattesmohr]

I think that B could be Bold as that is what I feel is the most common to describe it by.

It is also nice that you are aware of the simpe present and simple past, as it is details polish the develop experience. However, Linguists is not my biggest strength. So maybe Bold, StrikeThrough, Emphasise is better?

I go with it.

When it comes to BiDirectionalIsolation I agree it is too long. So maybe this is a case where only the acronym is better?

Yup, I think so too. I will skip it and maybe think about it another time.

Also the I think that the Hyperlink and Acronym might be unnecessary, even tho it is multiple descriptive names. So yes, we could remove them.

Will do.