Enhance documentation of keywords that can execute commands

[yanne]

I needed to explain how different keywords that execute commands work in a mail. This stuff could be added to the keyword documentation:

I have many testcases where I execute UNIX commands via SSHLibrary. In some of them I need to evaluate the output of a command. SSHLibrary provides several keywords / keyword combinations which could be used for that:

• Write | ${output}= | Read

This reads everything currently available in the output buffer. Good if you know everything has been written, not so good if the command is still writing something.

• Write | ${output}= | Read Until Prompt

This reads everything until the next prompt (that must have been set earlier) appears in the output buffer. If there's no prompt initially, this will wait for it to appear until the configured timeout. Good when you have started a command when the output buffer was empty and are waiting for the to finish. Bad if there are already prompts in the output buffer or the command produces multiple buffers.

• Write Bare | \n ${output}= | Read
• Write Bare | \n ${output}= | Read Until Prompt

These are identical to the previous commands. You are just adding the newline character yourself -- Write adds that automatically but Write Bare doesn't.

• Start Command | ${output}= | Read Command Output

I didn't even know that there are a keywords like these in SSHLibrary. Apparently they start the command on background and you can then read it later.

• ${output}= | Execute Command |

This one executes the command in a separate shell. Easiest to use but not possible when you need to run several shell commands.

This issue was originally opened at Google Code on Aug 11, 2010.