Skip to content
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.

Sign up for GitHub

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

Jump to bottom

<py-config> reference improvements #1006

Closed
3 tasks done
fpliger opened this issue Dec 1, 2022 · 8 comments · Fixed by #1022
Closed
3 tasks done

<py-config> reference improvements #1006

fpliger opened this issue Dec 1, 2022 · 8 comments · Fixed by #1022
Assignees
@madhur-tandon
Labels
tag: docs Related to the documentation type: bug Something isn't working type: feature New feature or request user-friendliness

Comments

@fpliger
Copy link
Contributor

fpliger commented Dec 1, 2022

Checklist

  • I added a descriptive title
  • I searched for other issues and couldn't find a solution or duplication
  • I already searched in Google and didn't find any good information or help

What happened?

Capturing a few things that got my attention while reading the reference page:

  • It mentions The <py-config> element should be placed within the <body> element. but I don't think it's correct. It was when <py-config> was a Custom Element but it is not anymore.
  • The Examples section encompasses a lot of value information that is kind of hidden within the examples comments. It ends up being a big wall of text that is not that useful unless I read the entire section (not users are there to read everything and often want to look for the minimum amount of info to solve their problem. I think that splitting the Examples part into smaller sections accompanied with contextual examples with be more useful. For instance, splitting into : Defining an inline config, Defining a file based config, Mixing inline and file based configs, TOML vs. JSON Configs or something along these lines would help the user navigate what they are looking for
  • Packages and local modules instructions are hidden in the wall of text right after example and then called out also later when we talk about fetch. It's confusing and dispersive. Per the item above, we should focus on grouping information that belong together in clusters that are meaningful together.
  • there's no complete configuration example that users can look at
  • the comment above is even more evident for more complex config keys like [[fetch]] and [[runtime]]. Imho we are leaving users with a lot of questions and guesses on these 2

What browsers are you seeing the problem on? (if applicable)

No response

Console info

No response

Additional Context

No response
@fpliger fpliger added type: bug Something isn't working type: feature New feature or request tag: docs Related to the documentation user-friendliness labels Dec 1, 2022
@FabioRosado
Copy link
Contributor

Agreed! I tried to break the wall of text a bit in this PR #982

Also added tutorials specifically for fetch and runtimes. If you have time can you check the PR?

@madhur-tandon
Copy link
Member

  • It mentions The <py-config> element should be placed within the <body> element. but I don't think it's correct. It was when <py-config> was a Custom Element but it is not anymore.

It was initially inside <head> but was later moved to <body>.
Relevant issue: #820
Relevant PR: #827

Tagging @antocuni for this part of the discussion

@madhur-tandon
Copy link
Member

Assigning myself

@madhur-tandon madhur-tandon self-assigned this Dec 2, 2022
@antocuni
Copy link
Contributor

antocuni commented Dec 2, 2022

It was initially inside <head> but was later moved to <body>. Relevant issue: #820 Relevant PR: #827

Tagging @antocuni for this part of the discussion

it still needs to be in <body> 🤷‍♂️
Issue #820 explains everything: if you put <py-config> in the <head>, it fails to validate, that's it.

The fact that it's a custom element or not it's irrelevant: custom elements cannot turn invalid HTML into valid HTML.

@JeffersGlass
Copy link
Member

Adding on to antonio, the result of including a custom element in a tag seems to be that the head is immediately closed, and that custom element tag and any following tags are dumped into the :

<head>
  <title>Hello world</title>
  <py-script id="InHead"></py-script>
  <meta charset="utf-8">
</head>
<body>
  <p>Hello, world!</p>
</body>

becomes:

<head>
  <title>Hello world</title>
</head>
<body>
  <py-script id="InHead"></py-script>
  <meta charset="utf-8">
  <p>Hello, world!</p>
</body>

Upon rendering. (*at least in Chrome, Edge, Firefox).

So, no custom elements in - they'll end up in the body anyway, possibly with unintended consequences.

@fpliger
Copy link
Contributor Author

fpliger commented Dec 5, 2022

Wait, I'm not sure I understand..... <py-config> is not a Custom Element. What am I missing?

@JeffersGlass
Copy link
Member

@fpliger Apologies, I got sloppy with my terminology. I should say any "non-typical" tags for... some version of typical?

Not entirely sure what the standard is or what the canonical list of tags allowed in <head> is, But the behavior above is the same if you use <foo> instead of <py-script> - that tag and everything after it in the head get dumped into the body.

@JeffersGlass
Copy link
Member

JeffersGlass commented Dec 6, 2022 •
edited

Digging a little deeper, I believe this behavior is captured by HTML Spec Section 13.2.6.4.4 - the "in head" insertion mode.

If I'm reading that section right, any tag not named base, basefont, bgsound, link, meta, title, noscript, noframes, style, script, or template will usually end up being inserted "after head", which usually means "in body" (or error).

Lots of edge cases in both those modes around closing tags, templates, noscript etc, but I think that's the gist of it.

@madhur-tandon madhur-tandon mentioned this issue Dec 6, 2022
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@madhur-tandon madhur-tandon

Labels
tag: docs Related to the documentation type: bug Something isn't working type: feature New feature or request user-friendliness
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

split py-config into sections madhur-tandon/pyscript
5 participants
@antocuni @fpliger @JeffersGlass @FabioRosado @madhur-tandon