[Maria-docs] KB Macro Proposal
All, Based on an IRC discussion from yesterday, I whipped up a prototype of a couple of macros for use in code examples. The macros would be <<input>> and <<output>> and would be used almost the same way as the <<code>> macro (the main difference being that they cannot be used "inline"). For example: <<input lang=sql>> SELECT * FROM t1 WHERE d LIKE "%es%"; <</input>> <<output>> +-----------+ | d | +-----------+ | Tuesday | | Wednesday | +-----------+ <</output>> I've created a couple of prototypes (screenshots attached) of how it could look (hopefully the list will allow the attachements). I like v1 better, but I'm not enough of a css guru to know how to get the overflow to work right (I like v2 as well). The idea is to be able to easily indicate input and expected output for SQL (and other) examples and have it be consistent across pages in the KB. Thoughts? -- Daniel Bartholomew MariaDB - http://mariadb.org Monty Program - http://montyprogram.com AskMonty Knowledgebase - http://kb.askmonty.org
Hi, Daniel! On Dec 07, Daniel Bartholomew wrote:
All,
Based on an IRC discussion from yesterday, I whipped up a prototype of a couple of macros for use in code examples.
The macros would be <<input>> and <<output>> and would be used almost the same way as the <<code>> macro (the main difference being that they cannot be used "inline"). For example:
<<input lang=sql>> SELECT * FROM t1 WHERE d LIKE "%es%"; <</input>>
<<output>> +-----------+ | d | +-----------+ | Tuesday | | Wednesday | +-----------+ <</output>>
I wanted to reply that one rarely needs separate input and output blocks, and much more often something like a <<tty>> block (or whatever), that includes both input and the output as typed on the terminal. But then, I looked at your screenshots - and indeed, they perfectly supported what I said - in your screenshots you use <<output>> both for input and the output "as typed on the terminal", and <<input>> basically the same as <<sql>>. I mean, that's how you used them, not how they looked. So, at the moment I'm not convinced we need input/output macros (and your screenshots only confirmed that). I'd rather see <<tty>> macro - but with explicit highlighting of what is the input. They can even be called <<input>> and <<output>>: <<output>> MariaDB [test] <<input>> SELECT * FROM t1 WHERE d LIKE "%es%";<</input>> +-----------+ | d | +-----------+ | Tuesday | | Wednesday | +-----------+ 2 rows in set (0.00 sec) <</output>> Regards, Sergei
On Wed, 7 Dec 2011 19:38:59 +0100 Sergei Golubchik <serg@askmonty.org> 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
Hi, Daniel! On Dec 07, Daniel Bartholomew wrote:
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> +-----------+ 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?
Usually the input in highlighted by making it bold or underlined. But using sql highlighting is kind of cool - I've never seen it embedded in the tty output, but it looks nice. Just don't forget that tty input is not always sql: <<output>> $ <<input>>./mtr --force --parallel 5<</input>> ... Failing tests: subselect subselect4 $ <<input>>diff -u r/subselect.re*<</input>> <</output>> Regards, Sergei
On Wed, 7 Dec 2011 22:00:56 +0100 Sergei Golubchik <serg@askmonty.org> wrote: Sergei> Hi, Daniel! Hi! With some prompting from Bryan, I wanted to re-open this conversation. I think this will be a good addition to the KB, and I like the direction that Sergei proposed: <snip> Sergei> Usually the input in highlighted by making it bold or Sergei> underlined. But using sql highlighting is kind of cool - I've Sergei> never seen it embedded in the tty output, but it looks nice. Sergei> Sergei> Just don't forget that tty input is not always sql: Sergei> Sergei> <<output>> Sergei> $ <<input>>./mtr --force --parallel 5<</input>> Sergei> ... Sergei> Failing tests: subselect subselect4 Sergei> $ <<input>>diff -u r/subselect.re*<</input>> Sergei> <</output>> After thinking about this more, I don't think creating new <<input>> and <<output>> macros is the way to go. Instead we should extend the existing <<code>> macro to allow the embedding of a new <<highlight>> macro. Apart from wrapping text inside it in a box, <<highlight>> would have a "lang=" property, just like <<code>>. The way it would work in practice would be for example: <<code>> MariaDB [test]> <<highlight lang="sql">>SELECT * FROM t1 WHERE d LIKE "%es";<</highlight>> +-----------+ | d | +-----------+ | Tuesday | | Wednesday | +-----------+ 2 rows in set (0.00 sec) <</code>> The above code block would then produce output similar to what is shown at the bottom of the attached screenshot. If no "lang=" attribute is given, only the box is drawn, and no syntax colorization or styling of the text happens. Multiple <<highlight>> blocks should be allowed inside an individual <<code>> block. The reason I'm using <<highlight>> as the name for the macro instead of <<input>> is that by making it generic, it becomes more obvious that it can be used for input, output, or anything else that the author of the article wants to highlight. As far as the actual name, <<highlight>> is a bit long, maybe we could use something shorter like <<hl>> (or do both and make one an alias for the other). What do you think? Especially for Bryan: How hard would it be to implement the above? Thanks. -- Daniel Bartholomew MariaDB - http://mariadb.org Monty Program - http://montyprogram.com AskMonty Knowledgebase - http://kb.askmonty.org
Hi Daniel, On 01/24/2012 11:59 AM, Daniel Bartholomew wrote:
After thinking about this more, I don't think creating new<<input>> and<<output>> macros is the way to go. Instead we should extend the existing<<code>> macro to allow the embedding of a new<<highlight>> macro.
Apart from wrapping text inside it in a box,<<highlight>> would have a "lang=" property, just like<<code>>.
The way it would work in practice would be for example:
<<code>> MariaDB [test]> <<highlight lang="sql">>SELECT * FROM t1 WHERE d LIKE "%es";<</highlight>>
+-----------+ | d | +-----------+ | Tuesday | | Wednesday | +-----------+ 2 rows in set (0.00 sec) <</code>>
The above code block would then produce output similar to what is shown at the bottom of the attached screenshot.
If no "lang=" attribute is given, only the box is drawn, and no syntax colorization or styling of the text happens.
Multiple<<highlight>> blocks should be allowed inside an individual <<code>> block.
The reason I'm using<<highlight>> as the name for the macro instead of <<input>> is that by making it generic, it becomes more obvious that it can be used for input, output, or anything else that the author of the article wants to highlight.
As far as the actual name,<<highlight>> is a bit long, maybe we could use something shorter like<<hl>> (or do both and make one an alias for the other).
What do you think?
Especially for Bryan: How hard would it be to implement the above?
I'm not sure how well creole supports nested macros, but if people like this approach I can look into it. Best Regards, -- Bryan Alsdorf, Lead Web Developer Monty Program AB. http://montyprogram.com
participants (3)
-
Bryan Alsdorf -
Daniel Bartholomew -
Sergei Golubchik