search

trogdoro / xiki

A shell console with GUI features
http://xiki.org
Other
3.76k stars 208 forks source link

Proposed getting started guide #146

Open masukomi opened 9 years ago

masukomi commented 9 years ago

Having finally gotten Xiki installed I decided to attempt to use it. I promptly found the glaring absence of a "getting started guide" but was pointed to many screencasts from 3 years ago and promotional ones that came out with the Kickstarter. "I'm a smart geek." I thought to myself. "I'll watch the videos and make a getting started guide for people."

I swear this started out all hopeful. It ended up with despair, frustration, annoyance, and a strong feeling of "fuck this. I've got better things to do with my life." which i really don't think is the sentiment people should walk away with.

So, here's the totally unedited first stab. You'll see it starts off helpful and then spirals downward. My hope in putting it here is that it'll provide a starting place for @trogdoro to work from to see what us newbs would be wondering and what we need answers to to even begin to get use out of xiki. There are a ton of questions that I didn't put in here because i'd just given up by the end.

Getting Started With Xiki

Ok, You've run the one line installer. You've followed the instructions. You've opened xsh in a new terminal. Now what?

(note: all paths mentioned below assume you've used the one line installer which makes the xiki directory ~/xiki-master)

Get Help

To get help run xsh -help (only one hypen there) from your shell.

The source to this is at ~/xiki-master/commands/help.rb

Probably the most important part of the Help doc is the "tutorial". Navigate down to that and start reading through the topics.

Right now (April 2015) the help docs are pretty sparse, and you'll find yourself seemingly at dead ends from time to time. Up arrow past the top and tutorial/ will appear again. Navigate up to it, press ^x to close it, then reopen it and you'll see all the topics listed again.

Basic Usage

At a high level Xiki basically boils down into three types of operations:

One way to run a command is to simply type a command (anywhere) and double click on it. That being said, where you put it has different effects.

Let's look at the ls command for example.

Preceeded by a $

$ ls
  : README.mkdn
  : cdiff
  : integration/

Preceeded by nothing

I typed ls but xiki appended the / after double clicking.

ls/
  : drwxr-xr-x 12 masukomi staff 408B Apr 25 12:33 .git
  : -rw-r--r--  1 masukomi staff 5.9K Mar 23 20:44 README.mkdn
  : -rwxr-xr-x  1 masukomi staff 5.2K Mar 23 20:49 cdiff
  : drwxr-xr-x  1 masukomi staff 5.2K Mar 23 20:44 integration

Why is the result different?

No clue.

Preceeded by a %

I have no clue what this does. I just know things get screwed up, I'm somehow back in a terminal, only inside of xiki and now I have to quit.

Preceeded by an @

In one of the videos this seems to invoke some sort of named menu. @rails brings up things you can do with the rails shell script.

In practice it doesn't matter what follows the @. It always brings up a list of menu items that occasionally have some tangental relation to the at sign: email, tweets, text messages??, call???

Later in the same video it shows @ Shark.clear_cache where Shark is a ruby class saved... somewhere, and cleare_cache is a method on that class. By evaluating the @ Shark.clear_cache line it calls that method on that class.

In short the @ symbol is a very confusing item that requires initiation into a secret society to use. So, just don't bother.

Running a command in a specific location

~/tmp/
  $ ls

Xiki is smart enough to figure out that the preceeding line is a folder, so it switches into that folder before running the command.

Note that if you preceed it with a % instead of a $ xiki will attempt to create some sort of new file named ls in the ~/tmp directory.

Why? No clue.

How do you get out of the "new file" editor? No clue.

Filtering Results

Xiki has keyboard shortcuts that enable you to filter the result sets. They are a mystery shared only amongst a secret sect of hooded monks... and Craig Muth.

The tab key

You may be tempted to use the tab key for tab completion, you know, like on a shell... because xsh stands for "xiki shell". Don't. The tab has special handling designed to fuck with your head by throwing out the command that you had on the line, replacing it with something that starts with the same letter, and then giving you a bunch of menus who's purpose in life appears to be to confuse you.

All the other control keys...

Normally in a shell you jump to the start of the line with ^a this will continue to work, along with ^e to jump to the end. This is provide you with hope. Next you'll try and use ^u and know that it was just an elaborate setup. Xiki is off in the corner giggling at you.

You can try the many other control key commands for navigating the command line. I gave up. I'd lost enough hope for the day.

You can make your own keyboard shortcuts...

Want to add the missing keyboard shortcuts? You can define what handles when ^ is pressed along with various other keys. Well, one of the screencasts claims you can, and provides example code. But it doesn't work.

Despite my attempts, more hope has been lost.

Defining new words to click on

You can define what happens when you double-click on text that matches a given pattern. Again, the screencast just serves to provide hope, then snatch it away. It doesn't work as demonstrated.

Defining new menu items

It's totally trivial. If, for example you you want to make some useful tools for your "sharks" app you can type something like this:

sharks/
  start/
  url/
  clear cache/

Now, evaluate the sharks/ line and it will tell you it doesn't exist and ask you how you'd like to create it: text file, menu items, notes, code, or more.

If you choose "text file" it'll give you the option to "save menu".

If you choose "menu items" it'll tell you "You can type out items literally." and provides four sumbenus to expand: just items, wiki with elements, directions, creating inline. "just items" will offer to "save menu", whereas "wiki with elements" will offer to "save menu". If you choose "directions" it will offer to "save menu" and if you choes "creating inline" it will offer to "save menu".

I'm not even going to try "notes" or "code" because i'm pretty sure they'll offer to "save menu" and I still don't know what the implications of any of these choices are anyway.

What's "just items" and why did it tell me I could "...just type out items literally" before that?

Run the examples

Examples? Where?

Down at the bottom you should see 

^X Expand  ^T Tasks ^K Keys ^Q Quit ^G Grab

Try running ^T (control + t) and you'll see 

$
  ~ examples/
  ~ recent/
  ~ dir history/

Start expanding (^X) examples and you'll find some interesting things to play with.

Another way to get to the examples is to start on your shell and run xsh --examples

Find the source to the examples

In the xiki directory (~/xiki-master if you did the one line install) you'll find a misc/shell_examples directory.

Basic Syntax

Headings

Headings are created by prefacing a line with >: 

> I'm a heading

Menus

...might be things that end with a /. They also might be things that start with a -. I'm really not sure.

Create a new command

You can create a file somewhere, with some extension that contains some stuff that may or may not need to resemble some stuff you saw in a video somewhere. Having done that you can then reap the joyous benefits of a nicely customized xiki.

What next?

You have two options at this point:

  1. Give up, wander off. Come back in 6 months and hope there's some useful documentation.
  2. Read the source code.

If you choose option 2, please write up what you find so that the rest of us can actually use xiki.

Me? I'm going with option 1. I've got my own little enough time to work on my own projects.

masukomi commented 9 years ago

i should note that i'd expect a way to get help from within xsh. There probably is a way as there's obviously a command for it, but i can't figure out how to invoke that command.

JosephViolago commented 8 years ago

xsh -help (outside of xsh) is the same as typing help ctrl + x (inside of xsh)

masukomi commented 8 years ago

cool, now it just needs to be made clear to new users that that's what you do.

trogdoro commented 8 years ago

The behavior of "$ xsh -foo" is going to change in the next version of Xiki, which I'll deploy in a few weeks.

After this next version is out here, things will be much more solidified. At that point getting the docs in order will be a priority.

--Craig

On Fri, Nov 6, 2015 at 7:29 PM, masukomi notifications@github.com wrote:

cool, now it just needs to be made clear to new users that that's what you do.

— Reply to this email directly or view it on GitHub https://github.com/trogdoro/xiki/issues/146#issuecomment-154612210.

charlesg commented 6 years ago

This issue is still open and I've very much had the same experience as @masukomi. Is there a plan to produce a few simple piece of clear documentation to help first time users. I could not find a list of keyboard shortcuts, did I just not find this documentation or it's just not there yet?

@trogdoro, you are likely way too comfortable with xsh to understand how very challenging some of the basic tasks are at first. Maybe an interactive session with a new user would help gather the information needed for a "Getting Started" guide.

I am always VERY impressed with the screencasts and what can be done but my experience is NEVER like in the screencasts, at the base I struggle with basic concepts like when and how to save.

I compare this to a first time user of vim or emacs. You can show them complicated features all day but when they open vim, they fail to understand the basic VIM modes or how to open or save a file.