fix some typos

[osban]

Found some typos. Mainly unescaped | in tables, but also a few other irregularities. Not all problems are visible in the website docs.

[dead-claudia]

Like the idea, but it needs a few edits.

[dead-claudia]

(Hit the wrong button...)

[dead-claudia]

I do want to note that it renders correctly, so I do want to see it rendered - I don't want a \| literally in the site's output. (The website is higher-priority than GitHub.)

[osban]

What do you prefer? I can remove the table changes too, and if not, is there a way to check how it actually renders on the site?

[dead-claudia]

@osban

What do you prefer?

I'd prefer your patch + my requested edits if it generates correctly, because that lets GitHub and the website both have correct formatting.

I can remove the table changes too, and if not, is there a way to check how it actually renders on the site?

1. npm install http-server -g if you don't already have it installed locally.
2. Run npm run gendocs.
3. Run http-server ./dist to start the web server. It'll open on port 8080 by default, but you can change it via -p PORT.
4. Open a web page to http://localhost:8080/route.html and look at the result.
5. Hit Ctrl+C when you're done.

It's slightly involved, but I've done similar so many times it's almost brainless at this point. And yes, http-server is an absolute life saver here. If you want it running concurrently so you can just refresh and see changes immediately, just open a different terminal to your local repo, run http-server -c-1 (the -c -1 disables caching), run npm run gendocs when you need to update the docs, and open the developer tools. (Just make sure that you at some point have caching disabled in the network tab or equivalent.)

And of course, you can make this a little more magical with chokidar-cli "docs/**" -c "npm run gendocs". I don't usually go that far before writing custom local scripts, though.

[dead-claudia]

I probably should at some point write a utility wrapping the two - I find myself doing this quite a bit in various places. It's nice when dealing with projects with almost no real build system involved, just scripts everywhere.

[osban]

Thanks, it works.

Now, to avoid misunderstandings, when you say that it renders correctly on the website, do you mean that Object<String,Component|RouteResolver> should render as Object (as it does now), or as Object<String,Component|RouteResolver>?

[dead-claudia]

@osban As Object<String,Component|RouteResolver>. And it currently renders as this. Edit: On the website, I mean. It's why I linked to it in the first place, so you could see it in the signature.

BTW, you might want to update your branch - I made a few quality of life improvements to the build scripts. It also enables certain docs lints. There's one major thing you'll appreciate: it has a npm run watch:docs built-in. So you just need to run http-server and npm run watch:docs in parallel. In *nix, it's as easy as http-server -c-1 & npm run watch:docs, and in Windows batch, you can do start /b http-server -c-1 & npm run watch:docs to similar effect (start is what makes it parallel - & is basically Bash's ;).

[osban]

Uhm, are we looking at the same line? I'm seeing Object at the routes argument at the signature (I've checked it in Chrome, Firefox, and Edge).

I'll look at the upgrade tomorrow :)

[dead-claudia]

@osban Better link: https://mithril.js.org/hyperscript.html#signature

Those | are what I'm referring to. Sorry if it wasn't clear.

[osban]

No worries, I will make sure route.md will render correctly on both the website and Github. It turns out jumping through hoops is sometimes necessary 😕

Btw, is there an easy way to update my branch?

[osban]

About the script (in Windows):

• & doesn't work in Powershell, but does work in cmd
• it look like start /b http-server -c-1 & start /b npm run watch:docs is needed to run them both in the same window
• I'm getting an error on the script:

internal/util.js:209
    throw new errors.TypeError('ERR_INVALID_ARG_TYPE', 'original', 'function');
    ^

TypeError [ERR_INVALID_ARG_TYPE]: The "original" argument must be of type function
    at promisify (internal/util.js:209:11)
    at Object.<anonymous> (C:\Users\Oscar\Documents\GitHub\mithril.js\scripts\generate-docs.js:6:18)
    at Module._compile (module.js:652:30)
    at Object.Module._extensions..js (module.js:663:10)
    at Module.load (module.js:565:32)
    at tryModuleLoad (module.js:505:12)
    at Function.Module._load (module.js:497:3)
    at Module.require (module.js:596:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (C:\Users\Oscar\Documents\GitHub\mithril.js\scripts\watch-docs.js:5:18)

[osban]

What is the best way to get the new changes committed? I made this commit online, but I now have a local repo. Shall I amend this commit or PR (not sure how to do that) or create a new one (should that be on a new branch?)?

[dead-claudia]

@osban

Btw, is there an easy way to update my branch?

Try git pull --rebase upstream next (change upstream to whatever your upstream is configured to)

it look like start /b http-server -c-1 & start /b npm run watch:docs is needed to run them both in the same window

Okay, I may have been incorrect on that, then. My bad - I don't use Windows hardly ever, and it's been years since I last regularly used it.

& doesn't work in Powershell, but does work in cmd

Why I said "Windows batch". 😉 Powershell uses ; instead of &, but you probably already knew that.

I'm getting an error on the script:

Upgrade to the latest stable Node. It should work there, and that's what CI uses. (stream.pipeline was added in Node 10.)

If you need to switch between this and an older version, something like nvm but for Windows (like nvm-windows or nodist) could help.

[dead-claudia]

What is the best way to get the new changes committed? I made this commit online, but I now have a local repo. Shall I amend this commit or PR (not sure how to do that) or create a new one (should that be on a new branch?)?

Go to the patch-2 branch in your repo, and navigate to the file you need to modify, and edit it the usual way. Just make sure you commit directly to that branch instead of creating a PR (it's an option below the editor before you click to commit, but IIRC it's direct by default except on the main branch). I wish GH would be a bit more intuitive on that front, but it isn't.

[osban]

Aha, thanks for the explanation. The whole Git thing is very confusing to me, though I'm slowly starting to understand it a little better. I've updated (read: completely overhauled) the original changes.

[dead-claudia]

@osban Just to clarify, does this render correctly to the site also? You can just compile the docs and inspect the HTML output in dist/ pretty easily.

[osban]

@isiahmeadows Yeah, I checked it using the 'old' gendocs 😉

[dead-claudia]

@osban Re-sync your branch with next - I fixed the file descriptor leak. @porsager reported errors of an unclosed HandleScope in C++-land in #2348, but I'm not getting those locally. If you do happen to get those, DM me on either Gitter or on Twitter, because I want to look into it. It's clearly a Node bug (probably a race condition if I had to guess), but I'd like to maybe see if I can get a repro going on my end.

[osban]

@isiahmeadows I have pulled the latest version, upgraded Node to v10, did npm rebuild. When running either npm run watch:docs or npm run build:docs I'm getting:

fatal: invalid reference: gh-pages
Error: Command failed: git checkout gh-pages -- archive
fatal: invalid reference: gh-pages

    at checkExecSyncError (child_process.js:629:11)
    at execFileSync (child_process.js:647:13)
    at generate (C:\Users\Oscar\Documents\GitHub\mithril\scripts\generate-docs.js:57:2)
fatal: invalid reference: gh-pages

[porsager]

I just commented out the 3 lines to work around that 😉

…

On 3 Aug 2019, at 11:48, Oscar ***@***.***> wrote: @isiahmeadows I have pulled the latest version, upgraded Node to v10, did npm rebuild. When running either npm run watch:docs or npm run build:docs I'm getting: fatal: invalid reference: gh-pages Error: Command failed: git checkout gh-pages -- archive fatal: invalid reference: gh-pages at checkExecSyncError (child_process.js:629:11) at execFileSync (child_process.js:647:13) at generate (C:\Users\Oscar\Documents\GitHub\mithril\scripts\generate-docs.js:57:2) fatal: invalid reference: gh-pages — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[osban]

@porsager thanks! For now I'm just using the old generate.js to build the docs...no watching yet, but oh well 😉

[dead-claudia]

@osban @porsager Yeah, I'd say comment them out for now and if you could, file a bug so I know to fetch it to ensure it actually exists. Sorry for the complications! (It works for me locally, but I have a near-full clone of Mithril's repo. 🙃)

[dead-claudia]

Fixed the small conflict and merged.