dthree / wat

Instant, central, community-built docs

hey there

---

I'm the Co-Founder & CTO at MindCloud, a rapidly growing B2B startup in the integration space. I've been writing production software for 16 years with an emphasis on designing and building data-heavy platforms from the ground up.

You can follow me on Twitter.

---

I had fun building some original OSS projects in the past for the Node community:

• Vorpal - Interactive CLI framework for Node
• Cash - Cross-platform unix coreutils in Javascript
• Vantage - Distributed, realtime CLI for live Node apps

wat's Issues

`wat tour` eventually has problems

Here's one issue that I got past---it appears that there's supposed to be stripColor but it's not there? I just went with supportsColor and the tour continued.

? chalk

  enabled  styles  supportsColor  readme/


  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  Nice. That last tab you did shows what's in Chalk. The green items are methods, blue are properties, and the rest are         |
  |  docs, such as Chalk's readme on Github.                                                                                       |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘


  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  Take a look at what's in "stripColor". You've typed half of it already.                                                       |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

? chalk stripColor

? Did you mean: chalk supportsColor

This was also kind of weird because I hadn't already typed half of it (assuming "it" refers to "stripColor").

The problem I'm stuck on now is the grepping option:

? github dthree wat
? Results: 1. GitHub - dthree/wat: Instant, central, community-built docs
     Instant, central, community-built docs. Contribute to wat development by creating  an account on GitHub....
:

  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  You can also run this with "gh ..." or "readme ...".                                                                          |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘


  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  Wat can also grep things! Let's have some fun:                                                                                |
  |                                                                                                                                |
  |  Run "gh awesome node -l | grep simple | less" to find some simply awesome things.                                             |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

? gh awesome node -l | grep simple | less

  Missing required option. Showing Help:

  Usage: grep [options] <pattern> [files...]


  Grep (POSIX) implementation.

  Options:

    --help                    output usage information
    -i, --ignore-case         ignore case distinctions
    -w, --word-regexp         force pattern to match only whole words
    -s, --no-messages         suppress error messages
    -v, --invert-match        select non-matching lines
    -m, --max-count <num>     stop after num matches
    -b, --byte-offset         print the byte offset with output lines
    -n, --line-number         print the line number with output lines
    -H, --with-filename       print the file name for each match
    -h, --no-filename         suppress the file name prefix on output
    -q, --quiet               suppress all normal output
    --silent                  suppress all normal output
    --include <file_pattern>  search only files that match file_pattern

?

(Awesome tool, BTW! The only other thing I've noticed is that navigating my cursor around a line of command I've typed causes the text to flicker and the cursor to jump around. This might be an underlying issue; if it's relevant / fixable, please let me know and I'll open a separate issue for it.)

Mention Dash

It seems that Dash is trying to solve a similar problem. Maybe write a little comparison?

Node Download links

Node download links refers to node 0.12.7 under the faqs.

I think that these should be updated to 4.2.0.

What do you think?

Exiting could be more intuitive

Not sure if that's a Vorpal UX issue instead.

To exit from wat:

• Ctrl-C works
• exit works
• Ctrl-D on an empty line does nothing (I expected exit as in shell-like behaviour)
• q or quit do nothing (I tried q as a reflection / habit from vim/less etc)

CLI REPL requires two ^C to exit

Hitting CTRL+C once puts wat into a weird, hung state and requires a second CTRL+C to actually exit.

wat tries to create folders in /usr/lib

I tried installing wat using npm but when I try to start in fails with access denied trying to mkdir /usr/lib/node_modules/wat/.local as part of clerk.scaffold

the paths look vaguely xdgish so maybe $XDG_DATA_HOME is what you want

wat tour throws error at clerk.js 'error saving to the local filesystem', undefined is not a function

$ npm install -g wat
C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\wat -> C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\bin\index.js
[email protected] C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], collapse-white-space@1
.0.0, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected].
0, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], c
[email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], tunnel-agent@
0.4.2, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected].
5, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], h
[email protected])
├── [email protected]
├── [email protected]
├── [email protected]
└── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], babel-runtime@
6.5.0)

$ wat tour
?

  -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  |                                                                                                                                                                                                                                       |
  |  Welcome to Wat. Let's look up how to use Javascript's "array.slice()" method.                                                                                                                                                        |
  |                                                                                                                                                                                                                                       |
  |  Type "js array slice" and press [enter].                                                                                                                                                                                             |
  |                                                                                                                                                                                                                                       |
  |  (You can exit using [control] + c at any time.)                                                                                                                                                                                      |
  |                                                                                                                                                                                                                                       |
  -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

? js array slice
C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\clerk\clerk.js:368
      this.log('Error saving to the local filesystem: ', e);
           ^
TypeError: undefined is not a function
    at Object.file (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\clerk\clerk.js:368:12)
    at C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\clerk\clerk.js:338:19
    at Request._callback (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\util.js:573:11)
    at Request.self.callback (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\node_modules\request\request.js:199:22)
    at Request.emit (events.js:110:17)
    at Request.<anonymous> (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\node_modules\request\request.js:1036:10)
    at Request.emit (events.js:129:20)
    at IncomingMessage.<anonymous> (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\node_modules\request\request.js:963:12)
    at IncomingMessage.emit (events.js:129:20)
    at _stream_readable.js:908:16

`?`

Typing a single question mark (?), while not necessarily idiomatic, is sometimes used in command line tools to display help. In wat, it's implemented as a quick way to throw an error and return to the shell. This design decision might best be reviewed. Error message follows:

$ wat
? ?
readline.js:924
            throw err;
            ^

SyntaxError: Invalid regular expression: /(?)/: Invalid group
    at new RegExp (native)
    at forEachInIndex.filter.okay (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:164:19)
    at traverse (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:138:17)
    at traverse (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:143:13)
    at traverse (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:143:13)
    at Object.forEachInIndex (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:148:5)
    at Object.search (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:154:10)
    at CommandInstance.<anonymous> (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/vorpal/catch.js:153:33)
    at EventEmitter.session.execCommandSet (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/node_modules/vorpal/lib/session.js:432:24)
    at EventEmitter.vorpal._exec (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/node_modules/vorpal/lib/vorpal.js:798:18)

Wat exits with non-zero upon ^C

Upon exiting wat with CTRL+C, it returns non-zero (exit code 130 to be exact). It should probably exit with 0 💃

GitHub search dies horribly with `ReferenceError: attacher is not defined`

 wat 
? github testing123

/Users/Ian/gg/timesync-node/node_modules/wat/dist/spider/github.js:36
            var md = mdast().use(stripBadges).use(attacher);
                                                  ^

ReferenceError: attacher is not defined
    at /Users/Ian/gg/timesync-node/node_modules/wat/dist/spider/github.js:36:51
    at Request._callback (/Users/Ian/gg/timesync-node/node_modules/wat/dist/util.js:542:11)
    at Request.self.callback (/Users/Ian/gg/timesync-node/node_modules/request/request.js:198:22)
    at emitTwo (events.js:87:13)
    at Request.emit (events.js:172:7)
    at Request.<anonymous> (/Users/Ian/gg/timesync-node/node_modules/request/request.js:1063:14)
    at emitOne (events.js:82:20)
    at Request.emit (events.js:169:7)
    at IncomingMessage.<anonymous> (/Users/Ian/gg/timesync-node/node_modules/request/request.js:1009:12)
    at emitNone (events.js:72:20)

Wat crashes by creating long tmp path / max call stack exceeded

https://gist.github.com/forivall/e4cf575d0fc8a593f82c

After typing wat tour, I wait for a couple seconds, then the "Maximum call stack size exceeded" error occurs.

linux, iojs 3.2, npm@3. More detail is in the gist terminal log.

wat should support a --version flag

I was writing a bug report and wanted to include the version of wat I had installed.
This is what happened:

 $ wat --version

  Sorry, there's no command like that.

Goodbye!

XO standard

I noticed the readme wanted to be XO compliant. I went ahead and started but it looks like it's going to be a hefty job.

If someone would like to jump in and help complete it, that'd be great :) I can't devote much more time to it, though I got rid of most of the errors and configuration.

---

Gulpfile.js is either going to need to be ES2015 compliant or XO is going to need a way to look at comments to negate the esnext configuration value.

// @sindresorhus

mdast documentation

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 😄.

"Language?", or some sort of clarity engine

I could see this having a huge impact on other languages, such as C (for instance). Yes, man pages help, but are sometimes much more than what you need (i.e. the common example you use of argument order, etc.).

---

If I do wat printf, I'm going to get a few different results for a few different languages. Likewise, if I do wat println, I might get a few different options for clarification.

What would be cool to see in Wat is an engine for determining what result the user is most likely looking for, and filling in any missing pieces through continued prompt(s).

For instance, when I do type printf and there are are a few languages - c and php, namely - wat would ask Language?, in which I could respond c.

Further, for the REPL version, it might even be useful to specify what language(s) you're looking for. If I'm a C/JS developer, I will literally never be looking for PHP information. lang c, js or some similar command would be a hint to the clarity engine that I'm going to be looking for language results in either c or js (javascript).

This would be an incredible tool in my arsenal.

Latest version of wat fails

Looks like a module was introduced that's causing problems?

This is right after a fresh npm i -g wat.

Textual error:

module.js:338
    throw err;
    ^

Error: Cannot find module 'unzip'
    at Function.Module._resolveFilename (module.js:336:15)
    at Function.Module._load (module.js:286:25)
    at Module.require (module.js:365:17)
    at require (module.js:384:17)
    at Object.<anonymous> (/Users/qix/.nvm/versions/io.js/v3.1.0/lib/node_modules/wat/lib/clerk.js:10:15)
    at Module._compile (module.js:430:26)
    at Object.Module._extensions..js (module.js:448:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Module.require (module.js:365:17)

DOS→UNIX line endings?

Files seem to have CRLF (DOS-style) line-endings over here. Source code more commonly has LF (UNIX-style) line-endings. (More details on Wikipedia.)

Is there a particular reason for the DOS style? Most editors auto-detect, but I suspect this might be the reason behind e.g. wooorm/mdast#43. I haven't investigated that much though!

Hitting tab rapidly in succession causes tabs to be inserted

Title sounds weird, but auto-completion isn't a smooth as it could be. When you hit tab multiple times, the tabs flood the console. Some of them are compensated for, but most of the time they get put in there. It seems wat is handling them correctly, but cosmetically it makes it look all weird.

"err wrong command" on correct command

So this happened. Got Err... wrong command when the comment was corrected.

Can't use tab completion for selcting themes

I expected to be able to type theme de<TAB> to select the default theme but nothing happened.

Failed to install on Windows

Hello you have an intresting project that would be awesome for me to contribute. Though I am having trouble installing it or installing it correctly as seen here:

26980 verbose stack Error: ENOENT, open 'C:\Program Files\nodejs\?.cmd'
26980 verbose stack     at Error (native)
26981 verbose cwd C:\WINDOWS\system32
26982 error Windows_NT 6.3.9600
26983 error argv "C:\\Program Files\\nodejs\\\\node.exe" "C:\\Program           Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "-g" "wat"
26984 error node v0.12.7
26985 error npm  v3.2.2
26986 error path C:\Program Files\nodejs\?.cmd
26987 error code ENOENT
26988 error errno -4058
26989 error enoent ENOENT, open 'C:\Program Files\nodejs\?.cmd'
26989 error enoent This is most likely not a problem with npm itself
26989 error enoent and is related to npm not being able to find a file.
26990 verbose exit [ -4058, true ]

Any ideas of why I am receiving these errors? Would it be more appropriate to put this issue on npm?

Trying to create new docs - wont index

Hi,

I need a jump-start again.

I am trying to create new documentation for protractor. As there are no good api-docs for protractor in markdown-format on github, I want to paste them hand-crafted from angular.github.io/protractor to the docs/ folder.

What I have done:

• create no subfolder docs/protractor
• create two files: docs/protractor/element/all/index.md and docs/protractor/element/index.md
• copied config.json from docs/js to docs/protractor and edited it to contains both functions 'element' and 'element/all'
• run indexin wat -> nothing happens
• run gulp index on shell -> nothing happens

What have I exactly to do, to add this new docs?

For me it looks on the first view exactly like the js doc. The files config/config.json and config/index.json were also updated automatically by index command.

For clarity you can see the wip here: https://github.com/defel/wat/tree/protractor-docs/docs/protractor

Proxy Issues?

When I attempt to pull up certain commands in Wat, such as vantage auth or vantage firewall reject, I get this:

Unexpected Error:  { [Error: connect ECONNREFUSED]
  code: 'ECONNREFUSED',
  errno: 'ECONNREFUSED',
  syscall: 'connect' }

My internet is going via an HTTP proxy set in the OSX system settings, and I'm guessing that this may be the issue. Any thoughts? (If it's just a lack of implementation, and you point me to the code in question, I may be able to try some stuff out.)

Wat tour doesn't appear to work

on Elementary OS, zsh. Node v8.11.3 (npm v5.6.0).
Running wat tour simply prints out two question marks.
However I can run wat js array splice 👍

Cant build local version - problem with 'initClerk'

Hi,

I forked the project and tried to build it local:

npm install
gulp all

and get the following error:

[18:20:21] Using gulpfile ~/code/playground/wat/gulpfile.js
[18:20:21] Starting 'initClerk'...
[18:20:21] 'initClerk' errored after 135 ms
[18:20:21] TypeError: undefined is not a function
    at Gulp.<anonymous> (/home/alexander.weiher/code/playground/wat/gulpfile.js:21:9)
    at module.exports (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/lib/runTask.js:34:7)
    at Gulp.Orchestrator._runTask (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/index.js:273:3)
    at Gulp.Orchestrator._runStep (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/index.js:214:10)
    at Gulp.Orchestrator.start (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/index.js:134:8)
    at /home/alexander.weiher/code/playground/wat/node_modules/gulp/bin/gulp.js:129:20
    at process._tickCallback (node.js:355:11)
    at Function.Module.runMain (module.js:503:11)
    at startup (node.js:129:16)
    at node.js:814:3

The problem is in the gulp-task 'initClerk' - the start function does not exist:

gulp.task('initClerk', function(){
  clerk = require('./dist/clerk/clerk');
  clerk.start({
    updateRemotely: false
  });
})

// console.log(clerk);
function (app) {
  clerk.app = app;
  clerk.indexer = require('./indexer')(app);
  clerk.history = require('./history')(app);
  clerk.updater = require('./updater')(app);
  clerk.config = require('./config')(app);
  clerk.autodocs = require('./autodocs')(app);
  clerk.prefs = require('./prefs')(app);
  return clerk;
}

Any ideas what I can do?

SyntaxError: Use of const in strict mode.

Command: $ wat css animation
Path: /node_modules/wat/bin/index.js:5
Error:

const uh = require("./../");
^^^^^
SyntaxError: Use of const in strict mode.
    at exports.runInThisContext (vm.js:73:16)
    at Module._compile (module.js:443:25)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:501:10)
    at startup (node.js:129:16)
    at node.js:814:3

Node version: v0.12.6

Add screenshot to readme

(or screencast)

I personally really like it when there’s an image of how a tool looks in the docs, especially when there’s a lot of docs. I also think more people find it useful :)

Improve search results

Alright so upon first use, specific things like js array splice work great - I love the format and it shows the two things I want the most - syntax, and an example.

I'm not sure if this is just a lack of documentation, or if it's a problem with the search itself, but here are some things that I feel should be pretty rudimentary.

• ES6 constructs (not just methods)
• Missing Object.defineProperty, etc.
• Order of keywords (i.e. splice array)
• If mis-spellings were silently fixed on the fly, I'd love you forever Nevermind, not sure where I thought they weren't.

verb templates

More of an introduction & self-note to use verb's doc templating system as a way to semi-automatically make wat docs.

"Prompt called when mid prompt" a lot

Saw it in the tour immediately after I (also) saw #47. Repro:

1. sudo npm install -g wat; HEAD when I did this was commit e0d96cc
2. wat js object defineproperty

Seems reliable.

Kind of a shame; this is a super neat project but apparently not all that usable yet. (Fair enough; it hasn't had a release.) If I can get a pointer to where to start looking for the bug, I might take the time to turn this into a PR with a fix; there's a lot of wat here and I don't really have time to dig into it from scratch.

Snippit maintenance / automatic doc generation

For intro comments, see 419654c