New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make it easier to find long-form ("elem.Anchor") names from short-form HTML tag names ("<a>") in documentation #163

Open
slimsag opened this Issue Nov 5, 2017 · 10 comments

Comments

Projects
None yet
4 participants
@slimsag
Member

slimsag commented Nov 5, 2017

I am thinking that it could be valuable to switch from elem.Header1 to elem.H1 The reason I say this is because:

  1. Sometimes you know the tag name easily (a) but not what it represents (Anchor).
  2. When using any browser dev tools (chrome inspector, etc), you'll see tag names like h1 not their expanded form.
  3. When styling in CSS, you must use their tag name h1 not Header1.

The downside to this change is that it's yet another massive breaking change, so we shouldn't do it needlessly. That said, Vecty is experimental and pre-1.0 still. We could probably offer something like gofix quite easily (IIRC it's quite easy to fork/extend for this purpose in specific).

What do others think? Is elem.H1 or elem.Header1 more readable and usable? elem.A vs. elem.Anchor, etc.?

@slimsag slimsag added this to the 1.0.0 milestone Nov 5, 2017

@slimsag

This comment has been minimized.

Show comment
Hide comment
@slimsag

slimsag Nov 5, 2017

Member

Note we wouldn't do this until #136 is fixed most likely.

Member

slimsag commented Nov 5, 2017

Note we wouldn't do this until #136 is fixed most likely.

@slimsag

This comment has been minimized.

Show comment
Hide comment
@slimsag

slimsag Nov 10, 2017

Member

A new user suggests over Slack that:

I would suggest having elem.Anchor then having docs say, "If you're looking for <a>, use elem.Anchor".

Member

slimsag commented Nov 10, 2017

A new user suggests over Slack that:

I would suggest having elem.Anchor then having docs say, "If you're looking for <a>, use elem.Anchor".

@slimsag

This comment has been minimized.

Show comment
Hide comment
@slimsag

slimsag Nov 10, 2017

Member

(I'm still torn between elem.H1 vs elem.Header1)

Member

slimsag commented Nov 10, 2017

(I'm still torn between elem.H1 vs elem.Header1)

@dmitshur

This comment has been minimized.

Show comment
Hide comment
@dmitshur

dmitshur Nov 10, 2017

Member

I'm okay with both approaches, as long as they're done in consistent way.

I find it pretty easy to get used to the long-form names. I might have to look up that it's Anchor the first time I use the <a> element in vecty, but not the 2nd, 3rd, ..., 100th time that I use it. Same with heading elements.

Maybe if you gave examples of less commonly used names, that'd help provide motivation to switch to tag names.

Perhaps relevant, x/net/html/atom package uses original names:

https://godoc.org/golang.org/x/net/html/atom#Atom

Member

dmitshur commented Nov 10, 2017

I'm okay with both approaches, as long as they're done in consistent way.

I find it pretty easy to get used to the long-form names. I might have to look up that it's Anchor the first time I use the <a> element in vecty, but not the 2nd, 3rd, ..., 100th time that I use it. Same with heading elements.

Maybe if you gave examples of less commonly used names, that'd help provide motivation to switch to tag names.

Perhaps relevant, x/net/html/atom package uses original names:

https://godoc.org/golang.org/x/net/html/atom#Atom

@slimsag

This comment has been minimized.

Show comment
Hide comment
@slimsag

slimsag Nov 10, 2017

Member

I'm okay with both, as long as it's consistent.

This was my initial reaction, too, but only until I realized the inconsistency between Vecty <-> CSS. How do you feel about this inconsistency? e.g. Go:

elem.Anchor(...)

CSS:

a {
   background: red;
}

Maybe if you gave examples of less commonly used names, that'd help provide motivation to switch to tag names.

Full list here:

vecty/elem/generate.go

Lines 21 to 81 in 1ba2b77

"a": "Anchor",
"abbr": "Abbreviation",
"b": "Bold",
"bdi": "BidirectionalIsolation",
"bdo": "BidirectionalOverride",
"blockquote": "BlockQuote",
"br": "Break",
"cite": "Citation",
"col": "Column",
"colgroup": "ColumnGroup",
"datalist": "DataList",
"dd": "Description",
"del": "DeletedText",
"dfn": "Definition",
"dl": "DescriptionList",
"dt": "DefinitionTerm",
"em": "Emphasis",
"fieldset": "FieldSet",
"figcaption": "FigureCaption",
"h1": "Heading1",
"h2": "Heading2",
"h3": "Heading3",
"h4": "Heading4",
"h5": "Heading5",
"h6": "Heading6",
"hgroup": "HeadingsGroup",
"hr": "HorizontalRule",
"i": "Italic",
"iframe": "InlineFrame",
"img": "Image",
"ins": "InsertedText",
"kbd": "KeyboardInput",
"li": "ListItem",
"menuitem": "MenuItem",
"nav": "Navigation",
"noframes": "NoFrames",
"noscript": "NoScript",
"ol": "OrderedList",
"optgroup": "OptionsGroup",
"p": "Paragraph",
"param": "Parameter",
"pre": "Preformatted",
"q": "Quote",
"rp": "RubyParenthesis",
"rt": "RubyText",
"rtc": "RubyTextContainer",
"s": "Strikethrough",
"samp": "Sample",
"sub": "Subscript",
"sup": "Superscript",
"tbody": "TableBody",
"textarea": "TextArea",
"td": "TableData",
"tfoot": "TableFoot",
"th": "TableHeader",
"thead": "TableHead",
"tr": "TableRow",
"u": "Underline",
"ul": "UnorderedList",
"var": "Variable",
"wbr": "WordBreakOpportunity",

Member

slimsag commented Nov 10, 2017

I'm okay with both, as long as it's consistent.

This was my initial reaction, too, but only until I realized the inconsistency between Vecty <-> CSS. How do you feel about this inconsistency? e.g. Go:

elem.Anchor(...)

CSS:

a {
   background: red;
}

Maybe if you gave examples of less commonly used names, that'd help provide motivation to switch to tag names.

Full list here:

vecty/elem/generate.go

Lines 21 to 81 in 1ba2b77

"a": "Anchor",
"abbr": "Abbreviation",
"b": "Bold",
"bdi": "BidirectionalIsolation",
"bdo": "BidirectionalOverride",
"blockquote": "BlockQuote",
"br": "Break",
"cite": "Citation",
"col": "Column",
"colgroup": "ColumnGroup",
"datalist": "DataList",
"dd": "Description",
"del": "DeletedText",
"dfn": "Definition",
"dl": "DescriptionList",
"dt": "DefinitionTerm",
"em": "Emphasis",
"fieldset": "FieldSet",
"figcaption": "FigureCaption",
"h1": "Heading1",
"h2": "Heading2",
"h3": "Heading3",
"h4": "Heading4",
"h5": "Heading5",
"h6": "Heading6",
"hgroup": "HeadingsGroup",
"hr": "HorizontalRule",
"i": "Italic",
"iframe": "InlineFrame",
"img": "Image",
"ins": "InsertedText",
"kbd": "KeyboardInput",
"li": "ListItem",
"menuitem": "MenuItem",
"nav": "Navigation",
"noframes": "NoFrames",
"noscript": "NoScript",
"ol": "OrderedList",
"optgroup": "OptionsGroup",
"p": "Paragraph",
"param": "Parameter",
"pre": "Preformatted",
"q": "Quote",
"rp": "RubyParenthesis",
"rt": "RubyText",
"rtc": "RubyTextContainer",
"s": "Strikethrough",
"samp": "Sample",
"sub": "Subscript",
"sup": "Superscript",
"tbody": "TableBody",
"textarea": "TextArea",
"td": "TableData",
"tfoot": "TableFoot",
"th": "TableHeader",
"thead": "TableHead",
"tr": "TableRow",
"u": "Underline",
"ul": "UnorderedList",
"var": "Variable",
"wbr": "WordBreakOpportunity",

@dmitshur

This comment has been minimized.

Show comment
Hide comment
@dmitshur

dmitshur Nov 10, 2017

Member

Full list

I see, that helps.

I like the full names, but given it's very unlikely you'll be able to take on CSS and other places where the abbreviated names will continue to come up, and fix them all everywhere, it might make sense to stick to the web standards. Consistency is more important.

It will also help people who are coming from HTML and are new to Vecty.

Member

dmitshur commented Nov 10, 2017

Full list

I see, that helps.

I like the full names, but given it's very unlikely you'll be able to take on CSS and other places where the abbreviated names will continue to come up, and fix them all everywhere, it might make sense to stick to the web standards. Consistency is more important.

It will also help people who are coming from HTML and are new to Vecty.

@pdf

This comment has been minimized.

Show comment
Hide comment
@pdf

pdf Nov 10, 2017

Contributor

I prefer the long-form names personally, and I wish HTML used the long-form for clarity too - you can see that this has consistently been the trend for elements introduced in later spec revisions, as bandwidth constraints (and ubiquitous compression) no longer lend significance to character-level economy on the wire.

That said, as @shurcooL points out, consistency likely trumps personal preference here, particularly for new users.

If we wanted to allow transition without an immediate API breakage, wouldn't be much effort to wrap the (new) short-name funcs in (existing) long-name funcs, with a console warning of the deprecation and impending removal.

EDIT: Capitalisation is something to consider for these short names though, for idiomatic func names.

Contributor

pdf commented Nov 10, 2017

I prefer the long-form names personally, and I wish HTML used the long-form for clarity too - you can see that this has consistently been the trend for elements introduced in later spec revisions, as bandwidth constraints (and ubiquitous compression) no longer lend significance to character-level economy on the wire.

That said, as @shurcooL points out, consistency likely trumps personal preference here, particularly for new users.

If we wanted to allow transition without an immediate API breakage, wouldn't be much effort to wrap the (new) short-name funcs in (existing) long-name funcs, with a console warning of the deprecation and impending removal.

EDIT: Capitalisation is something to consider for these short names though, for idiomatic func names.

@dmitshur

This comment has been minimized.

Show comment
Hide comment
@dmitshur

dmitshur Nov 10, 2017

Member

There is another option to consider. It may not be a good idea, but I'll toss it out for consideration anyway.

There could be two elem-type packages (not sure about their location). One would offer the long-form element names like elem.UnorderedList, while the other would offer the unmodified element names like elem.UL.

However, IMO, that simply pushes the (hard) decision of what style to use onto users, which means we (the library creators) are providing less value to users. Specific picky users could define their own such package if they strongly desire. So I wouldn't recommend this route.

Member

dmitshur commented Nov 10, 2017

There is another option to consider. It may not be a good idea, but I'll toss it out for consideration anyway.

There could be two elem-type packages (not sure about their location). One would offer the long-form element names like elem.UnorderedList, while the other would offer the unmodified element names like elem.UL.

However, IMO, that simply pushes the (hard) decision of what style to use onto users, which means we (the library creators) are providing less value to users. Specific picky users could define their own such package if they strongly desire. So I wouldn't recommend this route.

@tbruyelle

This comment has been minimized.

Show comment
Hide comment
@tbruyelle

tbruyelle Nov 29, 2017

Contributor

I share the same opinion, I prefer the long-names, they're more meaningfull.

Contributor

tbruyelle commented Nov 29, 2017

I share the same opinion, I prefer the long-names, they're more meaningfull.

@slimsag

This comment has been minimized.

Show comment
Hide comment
@slimsag

slimsag Dec 4, 2017

Member

However, IMO, that simply pushes the (hard) decision of what style to use onto users, which means we (the library creators) are providing less value to users. Specific picky users could define their own such package if they strongly desire. So I wouldn't recommend this route.

@shurcooL I agree with what you've said here, I don't think that offering both would be ideal in most regards so I'd like to avoid that regardless of which outcome we choose here.

Given what I've heard here from @shurcooL, @pdf, @tbruyelle, and 2(?) newer users over Slack I have consistently heard that using the long-form names is preferred but an easier way to find a mapping of HTML tag names to their Vecty equivalent would be helpful, e.g. the ability to ctrl+f in the godocs for <a> and find Anchor easily.

I'll conclude that using long-form is the right decision here and change the title of this issue accordingly :)

Member

slimsag commented Dec 4, 2017

However, IMO, that simply pushes the (hard) decision of what style to use onto users, which means we (the library creators) are providing less value to users. Specific picky users could define their own such package if they strongly desire. So I wouldn't recommend this route.

@shurcooL I agree with what you've said here, I don't think that offering both would be ideal in most regards so I'd like to avoid that regardless of which outcome we choose here.

Given what I've heard here from @shurcooL, @pdf, @tbruyelle, and 2(?) newer users over Slack I have consistently heard that using the long-form names is preferred but an easier way to find a mapping of HTML tag names to their Vecty equivalent would be helpful, e.g. the ability to ctrl+f in the godocs for <a> and find Anchor easily.

I'll conclude that using long-form is the right decision here and change the title of this issue accordingly :)

@slimsag slimsag changed the title from Reconsider 'expanded' naming scheme used in generated subpackages to Make it easier to find long-form ("elem.Anchor") names from short-form HTML tag names ("<a>") in documentation Dec 4, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment