literal continuation rows

[GoogleCodeExporter]

I would like to be able to use special markup in a row to say that it is a 
continuation row, but that the data following the continuation character(s) 
shouldn't be parsed any further. I recommend this markup be {{{:::}}} (ie: 
three colons), though other characters could be considered. 

I try to encourage people on my team to document their keywords. For reusable 
keywords I recommend adding an example, since in my experience people often 
struggle with using keywords they haven't written. However, this becomes very 
tedious to write, since the example usually includes text that uses the same 
separators and robot syntax as the actual keyword. To get this to work, we have 
to escape the separators in the documentation, leading to documentation that is 
hard to write and a little clunky looking. For example:

{{{
*** Keywords ***
| My clever keyword
| | [Documentation]
| | ... | blah blah
| | ... | Example:
| | ... | \| \| My clever keyword \| argument 1 \| argument 2
}}}

If someone forgets to escape a pipe, robot will parse the row and join the 
cells with spaces, yielding examples that don't make sense. There is a similar 
problem with tab or space separated format as well, making it difficult to 
create examples in the same format used in that file.

If we allow three single colons in addition to the three dots, the example 
becomes both easier to write and easier to read:

*** Keywords ***
| My clever keyword
| | [Documentation]
| | ::: | blah blah
| | ::: | Example:
| | ::: | | | My clever keyword | argument 1 | argument 2
}}}

The idea is that if the three quotes appears where three dots appears, robot 
stops parsing at the next separator, and everything following that becomes the 
literal value of that cell for that row. 

Making such a change would likely be 100% backwards compatible, since the only 
thing this would break is if someone had a keyword literally named {{{:::}}}, 
which is highly unlikely. Also, the change would be relatively simple to make, 
as the special case for handling {{{...}}} is isolated to just a couple of 
functions.

Original issue reported on code.google.com by bryan.oa...@gmail.com on 14 May 2014 at 3:23

[GoogleCodeExporter]

Do I get it right that your use case is that you use pipe separated format and 
want to present tables, also constructed with pipes, in keyword documentation 
without needing to escape them? That sounds like a pretty small use case for 
adding totally new syntax, especially when the syntax wouldn't apparently do 
anything in HTML or TSV formats.

Could you consider writing docs using normal space separated format? That way 
pipes in docs wouldn't cause any problems for you.

Notice also that this wouldn't be as easy to implement as you make it sounds. 
Rows are currently split from the separator much before handling the row 
continuation syntax, but this new syntax ought to change how rows are split.

Original comment by pekka.klarck on 15 May 2014 at 10:02

• Changed state: Pending

[GoogleCodeExporter]

Yes, my original use case is any of the plain text formats where you have data 
that is also in the same format -- pipe separated format with pipes in the 
data, space separated format with extra whitespace in the data, tab separated 
with tabs in the data. There are perhaps other use cases such as creating 
actual test data (versus documentation) that has the same format that the test 
is written in. 

I considered mixing spaces and pipes, but the result was just about as 
unpleasant as escaping the pipes. I assume you're suggesting something like 
this:

    } Some test case
    | | [Documentation]
      ...  Example:
      ...  | | my example with pipes | foo | bar | baz
    | | [Tags] | and so on

The goal is for my team to be able to easily document their tests and keywords, 
and for people to be able to easily read the documentation within the file as 
well as from generated documentation.

Original comment by bryan.oa...@gmail.com on 15 May 2014 at 10:23

[GoogleCodeExporter]

I understand your problem but solving it with new syntax is not feasible. It 
would be a huge task to implement it, it would need to be documented, and also 
supporting tools such as RIDE would need to support it.

Original comment by pekka.klarck on 24 Jun 2014 at 1:53

• Changed state: WontFix