search

toml-lang / toml.io

Source Code for toml.io
https://toml.io
MIT License
42 stars 44 forks source link

Make toml.io! #1

Closed workingjubilee closed 4 years ago

workingjubilee commented 5 years ago

It's 1.0 time, and the website is a critical path item according to https://github.com/toml-lang/toml/projects/1 so let's open a tracking issue and see where we are? I'd be happy to get started on this, but I don't know if anyone's secretly been writing stuff for it yet.

Edit by @pradyunsg

There's WIP website here: https://wip--toml-io.netlify.com/v1/en/

pradyunsg commented 5 years ago

@workingjubilee Appreciate the interest! @LongTengDao has expressed interest in this as well.

I had started to tackle this myself but ran out of time. Also, well, doing everything myself is not a good idea. ^>^

On that note, find my notes below:

toml-lang/toml -- development space. toml-lang/toml.io -- where the versioned specifications live.

Structure

TODO: What'll be the "release process" for future versions of TOML and document in README of toml.io? Automate so that it's 1 CLI command.

Maybe:

  • copy toml.abnf & specification.md to toml-lang/toml.io
  • rename
  • git tag

Design

Follow aesthetic of posts on https://pradyunsg.me/blog. Skip any bikeshedding unless @BurntSushi or @mojombo holler.

pradyunsg commented 5 years ago

I realize now that that doesn't consider translations -- I guess, let's have the the translations namespaced, under /<2-letter-lang-short-code>/.

rwitzel commented 5 years ago

What is the benefit of toml.io? Developers like GitHub.com.

Isn't it better to focus on the remaining blocker #631 ?

LongTengDao commented 5 years ago

some suggestion

repo-root/src/ # could we write site source with .toml? to detach data and view, and nice diff
repo-root/build/ # view template and style defination, and build script
repo-root/docs/ # dist to here to get github pages support
repo-root/dist/ # pdf and/or offline single file html hand book
# site-root = repo-root/docs
site-root/ # dont display whole spec, lively introduce and links will be better
site-root/v/ # versions list and change log
site-root/v/?lang=
site-root/v/1.0/spec/
site-root/v/1.0/spec/?lang= # an edition surfix maybe better than pre ns, because not all path has it's translation, like abnf
site-root/v/1.0/abnf/ # a highlighted html page will be better than a raw .abnf file
site-root/v/1.0/edit/ # online toml highlight/mindmap editor
site-root/v/1.0/view/ # online toml highlight/mindmap viewer
# all path hide the .html tech details

url may be the only thing can't change easily in the future (people will link our site)

LongTengDao commented 5 years ago

@rwitzel maybe a offical website born with 1.0 will be good opportunity to disseminate TOML

pradyunsg commented 5 years ago

TOML developers want TOML 1.0 to have a better home than github.com/toml/toml-lang. This also enables freeing the toml-lang repository from the additional overhead of holding releases in-repo.

That's a good enough reason for me to spend my time to work toward it, and collaborate with others on the same.

Anyway, the issue you've referenced is also progressing so, tbh, I'm not sure what you're suggesting here. :)

pradyunsg commented 5 years ago

/v/1.0/spec/?lang=

That's not gonna work with a static website.

reg: multiple formats

Well, that depends on the static site generator we use. Something like Sphinx is fully capable of generating docs in loads of formats, from html to epub.

mojombo commented 5 years ago

I've been working on some ideas for a TOML website with @cannikin, who is now working with me at Preston-Werner Ventures on experimental projects. He should have some capacity to help move TOML forward from now on! I'll make sure he posts them here when he's back tomorrow.

rwitzel commented 5 years ago

@pradyunsg You guys are doing awesome work and it is highly appreciated. My point: I don't understand why the website is critical for TOML v1 (sorry for not mentioning/clarifying that in my previous comment) - as indicated in the project board. But, yes, you mentioned that it increases visibility and this is true, for sure.

workingjubilee commented 5 years ago

As the formal "stable" release, it would be nice if we also were able to pick up a bunch of momentum from declaring 1.0 and get even a tiny bit of social buzz, not only to get people to notice there's an alternative to Yonder Ambitiously Maximalist Language, but to prompt updates to existing parsers and make sure they're in conformation. Not much changed through 0.5, but some are still behind, and saying "we're 1.0!" at the same time as "and we have a site! It's not awful to look at!" would be helpful.

cannikin commented 5 years ago

Hello all! I started comping up a homepage last week:

image

And a different color scheme:

image

I envisioned the links at the top being:

The [try it] area lets you convert JSON <-> YAML <-> TOML.

pradyunsg commented 5 years ago

This looks great @cannikin! I'll refrain from nitpicking. 🙃

@mojombo wanted to include a validator so you could test your implementation

@mojombo Do you see this as different from toml-lang/compliance? My understanding is that it'd be the validator but it'd be good to confirm.

cannikin commented 5 years ago

@pradyunsg haha If there's anything big missing and/or wrong please let me know! Otherwise I'll assume it's perfect ;)

pradyunsg commented 5 years ago

@cannikin some of the broader concerns:

LongTengDao commented 5 years ago

@cannikin looks great!

Do you think JSON5 deserves a comparison?

cannikin commented 5 years ago

@LongTengDao Absolutely, I've never actually used JSON5 myself but if everyone thinks it's popular enough let's include it! Were you thinking a comparison at the top or as part of the "try it" section at the bottom?

LongTengDao commented 5 years ago

@cannikin Hi,

JSON5 is an advanced JSON-like alternative, just like TOML to INI, so I think there is no need to display them at the same time.

If at the top, JSON5 vs YAML vs TOML would be ok (if the sample has comments to compare, that's fair).

If the sample has no comments like now, then the top should be JSON vs YAML vs TOML. (because JSON is more widely used.)

The other one just add into the bottom, because the top area is expensive.

In fact, I think XML is also typical enough for compare in the top, but your current design is so beautiful, if add 3 to 4, will it be ugly?

cannikin commented 5 years ago

@LongTengDao Yes I thought the same thing—3 along the top looks great, 4 won't balance as nicely.

workingjubilee commented 5 years ago

I like it. I favor the warmer color palette. Might warrant tweaking the palette of the syntax highlighting to complement. It overall feels nice as-is, and stands out from the default white/black/blue of the Internet. Both do, actually (the first is blue/black/white, which actually matters a lot in terms of visual engagement).

Amusingly a warmish palette would actually be something shared with the other format sites... compare https://yaml.org/ and http://json.org/ with this. This mock is a lot nicer and more coherent on colors, though, and it's not like they're sharing hex codes.

If the buttons at the top are going to be the primary route to the spec, then it would be best if they were more eye-catching. ( Imagine the bleary-eyed programmer staring at the site at 1 AM. ) Unsure about what the current mock would actually pan out to in that regard, since at least some of that is about interactiveness.

I could see myself liking the "try it" being on its own page, as well as embedded here (so that there's a page where it comes first, mostly). Hm, How many formats would it offer conversion to/from? If just a few, radio buttons maybe?

cannikin commented 5 years ago

Updated comp! Used some feedback from above, tweaked colors a bit, etc, etc.

toml io_v2

LongTengDao commented 5 years ago

I think the the top half part of the first draft is more clear, and make toml center & bigger will obstruct users compare, that's not necessary, because toml being the best is an objective conclusion ;) while json->yaml->toml hinted at the order of evolution. 3-description-text-closing-and-align-to-top-3-samples which not one-to-one correspondence infact is also not intuitive.

But this is just my personal opinion, it depends on you, there are trade-offs and considerations in any scheme.

One place maybe a typo, datetime in toml sample is a string. And toml only has one kind of four datetimes could has offset. And there are no null type in toml. (null is no use in toml design, this is not a imperfection, but the description should be preciseness.)

Of cause, thiese are minor text content layer problems which could be improved by PR, never mind, just as a memo.

Anyway, our design is way ahead of other languages' offical sites. Cheers! Looking forward to come online.

mojombo commented 5 years ago

@cannikin I think it would be a good idea to start with some mobile designs first, it might help us really focus in on what's important for the home page. Then we can see how that translates to a desktop design.

workingjubilee commented 5 years ago

I agree that relying on people reading left-to-right (on desktop) is way better than popping the TOML view front-and-center, and I think it translates better to mobile (since in portrait view on my phone, I would just scroll down).

TOML already has a better syntax highlighting rule making it immediately stand out. ^_^

A subtle stagger or embiggening would be OK. Less ostentatious while still emphasizing. I think saying "it's obvious!" is OK, though, but I would almost save it for a deeper explanation (anatomy of a TOML file?) page. I think I might take a swing at showing what I mean there.

cannikin commented 5 years ago

CHECK IT http://toml.camerontech.io/

The styles are only optimized for mobile right now so open on your phone and/or responsive Chrome. ~And interaction stuff isn't hooked up.~ (23-Aug) Hooked up the snippet tabs at the top!

If you want a quick preview:

cannikin commented 5 years ago

After a discussion with @mojombo I've updated the homepage with more of a focus on TOML features and less on how other formats are garbage. Check it out! https://wip--toml-io.netlify.com/

pradyunsg commented 5 years ago

more of a focus on TOML features and less on how other formats are garbage.

I'm super happy with these changes here. :)

Also... on the use of (verbose) language directly from the specification -- we should probably use more concise language and examples here. That'll also help make that section smaller and a quicker tour. ;)

cannikin commented 5 years ago

Also... on the use of (verbose) language directly from the specification -- we should probably use more concise language and examples here.

Yeah I tried to paraphrase into less technical language in many places but I left most of the code examples as-is since they really show the flexibility of TOML's syntax. We could trim those down if we think people's eyes will glaze over. Let me know which examples are cuttable!

pradyunsg commented 5 years ago

nit: padding at the end of the "quick tour" section.

I can come up with the content for the "quick tour", over the weekend. Lemme know if that's cool/not cool. :)

cannikin commented 5 years ago

@pradyunsg haha yeah I saw that earlier and hoped no one would notice until I had a chance to fix. ;)

It is very cool if you want to take a stab at the quick tour content!

workingjubilee commented 5 years ago

This looks beautiful! Would you like help with the JSON<->TOML translator?

cannikin commented 5 years ago

@workingjubilee Yes please! haha I hadn't figured out how to actually do that yet, but I found this site: https://toolkit.site/format.html so I knew it was possible.

@mojombo had a good point that some types aren't directly translatable, like native datetimes. What do we do in those cases? Maybe just output a string version of the datetime? Or replace the content with a comment (even though it isn't technically legal in JSON)? Likewise do you take a datetime string in JSON and try and covert it to native datetime for TOML?

workingjubilee commented 5 years ago

OK, so these are all good questions but I am going to open this conversation as a separate issue in this repo so that it gets its own pride of place and also we can go back and forth without automatically pinging everyone in this conversation!

cannikin commented 5 years ago

Couple style updates: https://wip--toml-io.netlify.com/

cannikin commented 5 years ago

The site has been updated with styles for desktop! Also the Spec page is up. It pulls the README and parses it on the fly during deploy. Right now it's getting it from master but eventually I'll point it to the forthcoming v1.0.0 tag.

https://wip--toml-io.netlify.com

cannikin commented 5 years ago

Site updated to include spec translations (see locale picker at top of Spec nav):

https://wip--toml-io.netlify.com

eksortso commented 5 years ago

Looking at the spec page on Chrome on my Android phone, I don't see the locale picker anywhere.

cannikin commented 5 years ago

Sorry about that @eksortso, the menu wasn't showing on mobile at all! You should be seeing a "Menu" up there now that toggles to show the table of contents and locale picker at the top.

cannikin commented 5 years ago

Maybe we should just change that to a hamburger so we don't need a translation of "Menu" in every language...

LongTengDao commented 5 years ago

The format in chinese translation is:

[示例](#user-content-example)<a id="user-content-example">&nbsp;</a>
------

which is from:

Example
-------

because I want to keep same location.hash in link, and reader could switch language under same section.

It seems not display correctly in the website (https://wip--toml-io.netlify.com/v1/cn/spec/):

示例<-a><a-id="user-content-example">-</a>" data-target="nav.header">示例<a id="user-content-example"> </a>
cannikin commented 5 years ago

@LongTengDao hmm, this is an interesting problem. None of the other translations have these links so you can't move between cn and ja, for example. You've kind of "hacked" the spec format to support that, but unless everyone else does it's really only useful for jumping between cn and en. It also relies on the user-content- anchor prefix which is unique to GitHub—it adds it when automatically adding the link icon on hover:

image

What do people think? @workingjubilee @pradyunsg @mojombo ?

For reference: open web inspector here and check out one of the <h2> headings (after the table of contents). There's a "secret" link in the header that uses an english id attribute so that it matches up with the id attribute of the same section over in the english README.

workingjubilee commented 5 years ago

While I agree it's a mostly superfluous modification to the README, in principle it should be harmless because a Markdown parser is supposed to support inline HTML, especially including anchor tags.

LongTengDao commented 5 years ago

@cannikin Sorry, I forgot that we now have a website and no longer need to rely on GitHub hack. Just map different translations to each other according to the number of chapters. Is this better? Then just strip the hidden tags I added whether I remove them or not (not only for this case, directly display tag is inherently incorrect markdown rendering behaviour).

pradyunsg commented 5 years ago

If it makes things easier, let's just remove the inline HTML in the cn translation. Once this website goes live, the incentives for folks needing navigation on that document directly, are fairly low.

I'm OK with however we handle this case, as long as the website's output doesn't have raw HTML. ;)

cannikin commented 5 years ago

Okay updated the specs to use numbered section headings for the anchors (#section-1, #section-2) instead of the heading themselves (#strings, #keys). Now when you switch locales it goes right to that same section in the other language! Good idea @LongTengDao !

https://wip--toml-io.netlify.com/v1/en/spec/

LongTengDao commented 5 years ago

Oh, cool when really see it, good job! It was just an idea in the pass time.

Since the content including headings wont be changed in each released version, the hash could be section index + the heading textContent (#1.objectives, #2.table-of-contents, which is more friendly to view), and mapping them between languages by section index only (even translation content changed, section structure wont) internal maybe better. I'm not sure. The present approach is good enough. If there is anything else still need to improve, do them firstly, I'm looking forward to the launch of the website.

BTW: I found links in table of contents are hard coded with #user-content-* even in English edition. After thinking, I think we can remove the TOC section in the website, because we have side menu instead, which is more friendly.

cannikin commented 5 years ago

Question @LongTengDao: we wanted to update the list of locales to include the language IN the languages themselves (similar to how Wikipedia does it). This is what Wikipedia uses, but it lists the country code as "zh":

image

Should we use that? Is our country code of "cn" correct, or should that also change to "zh"?

LongTengDao commented 5 years ago

@cannikin There are a lot of sub languages under zh, and current version is zh-cn (also zh-hans-cn or cn), so keep cn as short url is correct ;)

While use in ui, 简体中文 is better than 中文, because 中文 is zh, and 简体中文 is zh-cn.

workingjubilee commented 5 years ago

Slightly expanding, to provide a bit more background context: Wikipedia likely uses the ISO 639-1 codes, which are based on the language's own name for itself. German is Deutsch, which is why the ISO 639-1 code is "de". Chinese is 中文 (Zhōngwén), which is why the ISO 639-1 code is "zh".

But it's what ISO 639 conceives of as a "macrolanguage", which groups many different languages together, some of which in this case are mutually unintelligible except via the global language of "being really loud, punctuated by throwing things". But there's much fewer variations on the writing system, and the same written text can be understood across the barriers of different spoken languages (at least in common cases), they would just say different things when they read it aloud. So you can expect there might be another translation, but it would follow zh- with something else, and so far there's no 2 letter ISO-639-1 code that uses cn.

LongTengDao commented 5 years ago

@workingjubilee Thanks for expanding.

zh-cn cn are both okay to me, also zh-hans-cn zh-chs... In consideration of there are so many languages alias system, zh-cn maybe not better than short format cn (also not worse).

Just don't use zh, because there could be zh-hk zh-mo zh-tw zh-tw zh-cht, current version is just one of them, which cannot include all of them.

After all, the one-dimensional structure can not fully classify the perceptual language, but will become verbose if it is forced to be rigorous.

Below is just a written pedigree (written language - sub written language - regional terminology habits, I tried to classify them), not involve the subdivision of spoken pronunciation (they are cross sometime...):

Unless there are conflict between sub alias (zh-cn vs xx-cn, I don't know) -- if that exists, cn will be unusable. Otherwise, they are all okay to me, short better, after all en de jp ko xx-xxx-cn looks a little...

pradyunsg commented 4 years ago

Other than the translation hierarchy, I think we're basically there?

~I'll file #??? for discussing the translation hierarchy stuff.~ Actually, even that seems to have been resolved -- I'll wait for @cannikin to chime in there.

@toml-lang/core What else do we want to do w.r.t. the website? Are we at a point where we can have a PR against this repository for the code that @cannikin has worked on?