maria-docs team mailing list archive

[Daniel Bartholomew <dbart@xxxxxxxxxxxxxxxx>]

On Wed, 7 Dec 2011 19:38:59 +0100
Sergei Golubchik <serg@xxxxxxxxxxxx> wrote:

Sergei> Hi, Daniel!

Hello!

Sergei> On Dec 07, Daniel Bartholomew wrote:
Daniel> All,
Daniel> 
Daniel> Based on an IRC discussion from yesterday, I whipped up a
Daniel> prototype of a couple of macros for use in code examples.
Daniel> 
Daniel> The macros would be <<input>> and <<output>> and would be
Daniel> used almost the same way as the <<code>> macro (the main
Daniel> difference being that they cannot be used "inline"). For
Daniel> example:
Daniel> 
Daniel> <<input lang=sql>>
Daniel> SELECT * FROM t1 WHERE d LIKE "%es%";
Daniel> <</input>>
Daniel> 
Daniel> <<output>>
Daniel> +-----------+
Daniel> | d         |
Daniel> +-----------+
Daniel> | Tuesday   |
Daniel> | Wednesday |
Daniel> +-----------+
Daniel> <</output>>

Sergei> I wanted to reply that one rarely needs separate input and
Sergei> output blocks, and much more often something like a <<tty>>
Sergei> block (or whatever), that includes both input and the output as
Sergei> typed on the terminal.
Sergei> 
Sergei> But then, I looked at your screenshots - and indeed, they
Sergei> perfectly supported what I said - in your screenshots you use
Sergei> <<output>> both for input and the output "as typed on the
Sergei> terminal", and <<input>> basically the same as <<sql>>. I mean,
Sergei> that's how you used them, not how they looked.
Sergei> 
Sergei> So, at the moment I'm not convinced we need input/output macros
Sergei> (and your screenshots only confirmed that). I'd rather see
Sergei> <<tty>> macro - but with explicit highlighting of what is the
Sergei> input. They can even be called <<input>> and <<output>>:
Sergei> 
Sergei> <<output>>
Sergei> MariaDB [test] <<input>> SELECT * FROM t1 WHERE d LIKE
Sergei> "%es%";<</input>>
+-----------+
Sergei> | d         |
Sergei> +-----------+
Sergei> | Tuesday   |
Sergei> | Wednesday |
Sergei> +-----------+
Sergei> 2 rows in set (0.00 sec)
Sergei> <</output>>

So are you thinking of something that looks more like the attached?

I'm fine with that. The whole idea is to make it easy for people to
"follow along" with the examples.

I don't know how easy or possible it is to embed macros inside other
macros, but what I would do is just embed an "<<input>>" block inside
of a <<code>> block (so it's basically the same as your example, but
with <<output>> changed to <<code>>). This has the advantage of being
backward compatible with existing <<code>> blocks (so those wouldn't
need to be updated):

<<code>>
MariaDB [test] <<input>> SELECT * FROM t1 WHERE d LIKE "%es%";<</input>>
+-----------+
| d         |
+-----------+
| Tuesday   |
| Wednesday |
+-----------+
2 rows in set (0.00 sec)
<</code>>

Bryan: Is it even possible to do what we're suggesting above?

Tha alternative would be for some sort of <<tty>> macro that can detect
SQL code and highlight it while keeping the rest plain.

Thanks.

-- 
Daniel Bartholomew
MariaDB - http://mariadb.org
Monty Program - http://montyprogram.com
AskMonty Knowledgebase - http://kb.askmonty.org

Attachment: LIKE-v3.png
Description: PNG image