toml-lang / toml.io Goto Github PK
View Code? Open in Web Editor NEWSource Code for toml.io
Home Page: https://toml.io
License: MIT License
Source Code for toml.io
Home Page: https://toml.io
License: MIT License
This has come up in multiple discussions over on toml-lang/toml, as a suggestion; for placing things that do not belong in the specification itself.
Right now, even if index.html
is translated, changing language will take you to the latest version of the spec. It should take you to the translated index.html
:
Should redirect to https://deploy-preview-34--toml-io.netlify.app/cn/
Note
This repository is for the toml.io website only. If you have a suggestion for the TOML spec itself, head over to https://github.com/toml-lang/toml and open an issue there.
I think there would better be a LICENSE file same with toml-lang/toml
, at least in specs
folder. If not, no one can use the whole translation docs in the futhur, because the default copyright belongs to all translators self.
The TOML .md file also has a supporting .abnf file which together serve as the overall specification.
Right now, I don't think we have the .abnf file in any specific location in this repository. @cannikin Any suggestions on how/where to put this on the website + this repository?
Context: #8 (comment)
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/
Basically a file with a better phrasing of:
Please file issues and questions related to the TOML specification at [link]. This repository/issue tracker is only for the toml.io website and not for the language specification.
Originally posted by @pradyunsg in #16 (comment)
On toml.io/en/v1.0.0-rc.3, go to, say, the part that says "Naming rules for tables are the same as for keys (see definition of Keys above)." The Keys is a link that is supposed to link to the Keys section. However, it does not. It links to https://toml.io/en/v1.0.0-rc.3#user-content-keys
but that doesn't go anywhere. It should link to https://toml.io/en/v1.0.0-rc.3#keys
.
I don't know how this web stack works at all so I figured I would make an issue rather than try to fix it myself. It's very weird that the table of contents uses links that end with (for example) #user-content-keys
and it works perfectly fine, but using that outside of the ToC is clearly not working.
Nowhere in the different versions of the spec published on toml.io it's visible at which date that version was tagged and published. To document TOML's history, it would be good a show a little note "Published on xx April 2020" somewhere at the top or bottom of each version of the spec.
In the page for the 1.0.0.-rc.1 version (https://toml.io/en/v1.0.0-rc.1), under 'Key-Value pair', the links to the types (like string, integer, etc) do not lead to the corresponding content.
But the links in the navigation pane on the left leads to the content.
The hrefs in the links of navigation pane have 'section-' in them and the links under 'Key-Value pair' has 'user-content-'.
And which static site generator is used for the website?
The toml language states:
TOML parsers should feel free to normalize newline to whatever makes sense for their platform.
I am not sure how to interpret "should feel free". Is it obligatory to interpret the newline according to what platform the parser is running on, or is it allowed to be parser-dependent on how to interpret newlines in a stirng literal?
When I click on https://toml.io/en/v1.0.0 on any of the internal links, e.g. in the list of types following "Values must have one of the following types", nothing happens because the link is broken. The problem is that these internal links are tailored for GitHub, but on toml.io the files are rendered in a different way and so the links don't work. For example, "String" is a broken link to https://toml.io/en/v1.0.0#user-content-string, while the correct link would be https://toml.io/en/v1.0.0#string.
toml.io must adjust these internal links when rending the files, to make them work.
For example at 140% I get a horizontal scrollbar:
Which gets even worse if you click a menu item, because it scrolls to the right:
At ~160% the mobile nav kicks in.
The exact values differ a bit per system, depending on screen resolution, window size, screen scaling, etc. You can also reproduce it by just making the window smaller, but the main gist is: there are some width that don't work well.
It should really just make the main content smaller; the reason it doesn't is because some wide pre tags make it larger. pre { max-width: calc(100vw - 21rem); }
fixes it, but there's probably a better way.
The example at the top of the page has the following two lines:
[clients]
data = [ ["delta", "phi"], 3.14159 ]
The problem is the value of data
. which is a mixed-type array, which is invalid in TOML v0.5.0. Although there's an open issue regarding whether mixed-type arrays ought to be allowed, that issue is tagged post-1.0.
So assuming the issue isn't pressed before v1.0.0, do you think we need to remove or replace the mixed-type array from the lead example?
I had a doubt. Wasn't sure which would be the right place to ask.
From the website, I see that.
[ g . h . i ]
is same as [g.h.i]
.
But how will
[ g h . i ]
be parsed.
Will g h
be considered as the first part of the key (not sure if I'm using the right terms (-: )?
Or is it an error?
And in table arrays, are white spaces allowed between the double braces. Is something like [ [ product]]
valid?
Following up on this:
@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?
Originally posted by @cannikin in #1 (comment)
We can do "lossy data, but structural match" or "lossy structure, but data match" translation across JSON : TOML, the data-lossless one involving type annotations embedded in the JSON structure. By default, we can favor the first, cleanest translation (where JSON and TOML are 1 to 1), but when the translation would involve loss of type data like that, we can display an error state or perhaps a "warning state" I guess and point the user to an option to enable alternative translations. After all, we already have to intelligently handle JSON literals ("Uh, Ma'am, this is a hash table").
I think recognizing JSON strings that are exact matches for the subsets of the RFC3339 format that TOML supports and casting them to TOML datetimes is a sane default, because it's lossless as a result, but not if they are off by even a single whitespace(!), and that a similar logic of Maximal Strictness would serve well on all type casts. No guessing and no magic, really, just return to user and comment on the results, maybe offer choices if we can. And I think that's going to be easiest.
Edited: I'm so sorry, I was mid-way through my coffee when I first posted this.
While the syntax highlighting of toml.io is very nice, for some use cases access to the raw Markdown files is more convenient – saw when comparing different released versions (diff). One possibility would be to complement https://toml.io/en/v0.5.0
with a plain text file accessible under e.g. https://toml.io/en/v0.5.0.md – and likewise for all other released versions. Then add a link "Plain text version" to the rendered HTML version to make the other version discoverable.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.