mdast documentation

[wooorm]

Spin-off from GH-15.

Some points I walked into:

• I’m using function foo(...) and the like for user-defined functions, e.g., function attacher(mdast[, options]), these are still visible in was (e.g., for autocompletion), that seems a bit superfluous;
• wat mdast process doesn’t show the list of parameters, it ends at Parameters and doesn’t show the rest;
• E-mail links are mangled to HTML entities, e.g., Written by Titus Wormer\ntit...;
• It seems I cannot enter wat mdast fileSet/, for some reason?
• Why does wat mdast mdastrc show up? Weird!

P.S. Really cool that it’s possible to search in documents, e.g., what mdast man mdastnode7 delete works great 😄.

[dthree]

Thanks for the detailed feedback and got it on the points!

Glad you like the doc search breakdown :) Btw, I'm also going to add a grep command, do you think that would be useful? The idea is to mirror the real grep command, except on the "files" (input) param, you just say the lib:

mdast | grep delete

It will then skip the API and grep all the docs, since the API is sourced from the docs anyway.

---

Anyway, should get to this in a bit. Getting test coverage into the 90s today, then jumping onto this.

[wooorm]

Cool! 👌

[dthree]

wat mdast process doesn’t show the list of parameters, it ends at Parameters and doesn’t show the rest

Could I get your opinion on something?

Right now, if a certain API command is longer than 20 - 30 lines (bar code samples), I break the remaining text into a detail file, i.e. there's a process.md and a process.detail.md. I was then going to add a note when a detail file is available, like:

to view more on this, run -d with the command

-d then shows the detail. This is why the rest of the param list wasn't showing up, btw.

I did this so that code snippits are kept as minimal as possible, and the user can do -d if he needs to see more.

Given I properly info the user on what's happening, and I add shortcuts (like press [enter] to see more data, or s/g), do you think that's a good idea? Maybe it's a sucky idea. Not sure.

[wooorm]

Seems like a nice addition to me!