From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rainer M Krug Subject: Re: [RFC] Standardized code block keywords Date: Tue, 25 Oct 2011 08:59:37 +0200 Message-ID: References: <87pqhrih3s.fsf@gmail.com> <30891.1319141196@alphaville.dokosmarshall.org> <87fwinifqu.fsf@gmail.com> <32184.1319143892@alphaville.dokosmarshall.org> <808vofwf1w.fsf@somewhere.org> <87y5wfgwn7.fsf_-_@gmail.com> <8895.1319165867@alphaville.dokosmarshall.org> <80hb32vjuz.fsf@somewhere.org> <87r5265mum.fsf@gmail.com> <807h3yxn42.fsf@somewhere.org> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=0016e64c26b42a56ab04b01a152c Return-path: Received: from eggs.gnu.org ([140.186.70.92]:40036) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RIaz6-000210-P5 for emacs-orgmode@gnu.org; Tue, 25 Oct 2011 02:59:43 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RIaz4-0007Z6-BO for emacs-orgmode@gnu.org; Tue, 25 Oct 2011 02:59:40 -0400 Received: from mail-qy0-f169.google.com ([209.85.216.169]:62278) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RIaz4-0007Z1-5K for emacs-orgmode@gnu.org; Tue, 25 Oct 2011 02:59:38 -0400 Received: by qyk29 with SMTP id 29so3125093qyk.0 for ; Mon, 24 Oct 2011 23:59:37 -0700 (PDT) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode --0016e64c26b42a56ab04b01a152c Content-Type: text/plain; charset=ISO-8859-1 On Tue, Oct 25, 2011 at 8:52 AM, Rainer M Krug wrote: > > > On Fri, Oct 21, 2011 at 7:37 PM, Sebastien Vauban < > wxhgmqzgwmuf@spammotel.com> wrote: > >> Hi Eric, >> >> Eric Schulte wrote: >> >> Now, between "srcname" and "source": I'm used to whatever my Yasnippet >> is >> >> entering for me. That's currently "srcname". I don't have a strong >> opinion, >> >> though, to choose one over the other, except that I like Nick's >> argument with >> >> the table analogy. >> >> >> >>> I agree on [2] "call". >> >> >> >> I clearly agree on "call" as well. >> > >> > noted, thanks >> >> I think you'll get unanimity on that one. >> >> >> Here, I'd like to ask: what about "sbe"? In my own understanding, it's >> a >> >> call, absolutely similar to "call". Is there a technical reason to be >> forced >> >> to differentiate both? If no, can we use "call" as well instead of >> "sbe"? >> > >> > The only difference is that sbe is a function name, and to name a >> > function call (a function which will take up that term in the entire >> > Emacs-lisp namespace across all applications) seems somewhat pushy. >> >> OK. Point understood. May I suggest to try to find a better name, still? >> Once >> we're at it, modifying one extra line in the documentation won't hurt. >> >> I don't know what others find, but I've never understood what it meant. >> OK, >> now (since yesterday, in fact), I know it means "source block evaluation", >> but >> that's not really intuitive. >> >> I'd opt for "ob-call" (package name + "call") or something like that, if I >> could choose. >> >> >>> I'm confused by [3] so I will say nothing for now, except to ask some >> >>> questions: are we talking about what a human would use to label a >> piece of >> >>> data for consumption by a block (including perhaps the future >> possibilities >> >>> of lists and paragraphs that Tom brought up)? what babel would use to >> label >> >>> a results block (possibly so that it could be consumed by another >> block in a >> >>> chain)? both? would that mean that #+tblname would go the way of the >> dodo >> >>> and that tables would be labelled with #+data (or #+object or whatever >> else >> >>> we come up with)? >> >> >> >> For point 3, Eric, I guess that whichever term is chosen, that does not >> mean >> >> that "results" will change (I mean: when it's a result of a block >> execution)? >> >> I was expecting you'd always keep "results" for auto-inserted results >> (after a >> code block evaluation). But it makes sense to prefer the one term that >> will >> win. >> > > I would definitely keep #+results as this marks it as an *output* which can > change during the next evaluation, and not an input, which has to be > modified by hand. I would actually go so far and say that #+results *can be* > src or object (using these terms), but is in itself *not* identifying > anything, apart from "this is the result of an evaluation". So: > > #+results > #+object_begin > . > . > . > #+end > > would be the result of an evaluation. > > One could even, for clarities sake, say that > > #+object > > if no #+results is in the line before, > > is a synonym for > > #+input (or #+constant) > #+object_begin > . > . > . > #+end > > Cheers, > > Rainer > > >> > I would be happy for results to change to data or tblname (if a table) >> > or whatever else is selected. >> >> OK, clear. >> >> >> In other words, if we choose for "object", we still will have the >> possibility >> >> to use "results" (automatically generated) and "object" to refer to >> something >> >> we want to use in another call? >> >> >> >>>>> named data [3] -- "tblname" "resname" "results" >> "data" >> >> >> >> I don't specifically like "resname". >> >> >> >> I would keep "results" for automatically generated "results". >> >> >> >> I do like "data", but can learn to like "object" as a more generic >> term, >> >> future-proof for coming extensions. >> > >> > I'll mark you down as undecided for this term. :) >> >> Yep! I'm open to any suggestion you'll make. >> >> >> Last remark: we could get one step further and wonder if it wouldn't be >> good >> >> to impose a single way to pass variables? We currently have two >> different >> >> mechanisms: >> >> >> >> #+srcname: convert-date-to-French-format >> >> #+begin_src sql :var column="" >> >> CONVERT(varchar(10), $column, 103) AS $column >> >> #+end_src >> >> >> >> and >> >> >> >> #+srcname: convert-date-to-French-format(column="") >> >> #+begin_src sql >> >> CONVERT(varchar(10), $column, 103) AS $column >> >> #+end_src >> >> >> >> I guess that the first one is easier if we want to construct complex >> variable >> >> values (which call Emacs Lisp code or such), but... >> > >> > I don't feel that this example causes as much confusion, but if I'm >> > wrong I am open to change on this front. Although the only possible >> > change here would be to remove the second option as the first method of >> > specifying variables is central to code block management. >> >> Just that I remember both syntaxes weren't handled the same way for error >> reporting (remember, when there is no default value: in one case, you can >> get >> the name of the faulty block; in the other, not), and that makes me think >> is >> not as simple as an alias. Hence, your Babel code is or can become >> different >> just because there are different alternatives to write certain things >> down. >> >> Then, as a user, I always wonder what's the best one? "For a good error >> reporting (with the name of the code block being outputted), which one do >> I >> have to use?" and such questions... >> >> If we only have one way, we can be sure everybody experiences the same >> things >> with the same semantical input. >> >> Another point, that may or may not have much to do with this, is that I >> don't >> have anymore the source name exported in HTML -- dunno when it >> disappeared, >> though. I remember that, at some point, it was due to having, or not, a >> default value (at the time, having no default value was still allowed), >> but >> now, even with the default values for every var, I miss those names in the >> HTML (for literate programming support, it is quite useful to be able to >> see >> the name of the block along with the code). >> >> I repeat myself, but thanks, once again, for tackling this naming >> "problem". >> >> Best regards, >> Seb >> >> -- >> Sebastien Vauban >> >> >> > > > -- > Rainer M. Krug, PhD (Conservation Ecology, SUN), MSc (Conservation Biology, > UCT), Dipl. Phys. (Germany) > > Centre of Excellence for Invasion Biology > Stellenbosch University > South Africa > > Tel : +33 - (0)9 53 10 27 44 > Cell: +33 - (0)6 85 62 59 98 > Fax (F): +33 - (0)9 58 10 27 44 > > Fax (D): +49 - (0)3 21 21 25 22 44 > > email: Rainer@krugs.de > > Skype: RMkrug > > -- Rainer M. Krug, PhD (Conservation Ecology, SUN), MSc (Conservation Biology, UCT), Dipl. Phys. (Germany) Centre of Excellence for Invasion Biology Stellenbosch University South Africa Tel : +33 - (0)9 53 10 27 44 Cell: +33 - (0)6 85 62 59 98 Fax (F): +33 - (0)9 58 10 27 44 Fax (D): +49 - (0)3 21 21 25 22 44 email: Rainer@krugs.de Skype: RMkrug --0016e64c26b42a56ab04b01a152c Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable

On Tue, Oct 25, 2011 at 8:52 AM, Rainer = M Krug <r.m.krug= @gmail.com> wrote:


On Fri= , Oct 21, 2011 at 7:37 PM, Sebastien Vauban <wxhgmqzgwmuf@spamm= otel.com> wrote:
Hi Eric,

Eric Schulte wrote:
>> Now, between "srcname" and "source": I'm u= sed to whatever my Yasnippet is
>> entering for me. That's currently "srcname". I don&#= 39;t have a strong opinion,
>> though, to choose one over the other, except that I like Nick'= s argument with
>> the table analogy.
>>
>>> I agree on [2] "call".
>>
>> I clearly agree on "call" as well.
>
> noted, thanks

I think you'll get unanimity on that one.

>> Here, I'd like to ask: what about "sbe"? =A0In my ow= n understanding, it's a
>> call, absolutely similar to "call". Is there a technical= reason to be forced
>> to differentiate both? =A0If no, can we use "call" as we= ll instead of "sbe"?
>
> The only difference is that sbe is a function name, and to name a
> function call (a function which will take up that term in the entire > Emacs-lisp namespace across all applications) seems somewhat pushy.
OK. Point understood. May I suggest to try to find a better name, sti= ll? =A0Once
we're at it, modifying one extra line in the documentation won't hu= rt.

I don't know what others find, but I've never understood what it me= ant. OK,
now (since yesterday, in fact), I know it means "source block evaluati= on", but
that's not really intuitive.

I'd opt for "ob-call" (package name + "call") or so= mething like that, if I
could choose.

>>> I'm confused by [3] so I will say nothing for now, except = to ask some
>>> questions: are we talking about what a human would use to labe= l a piece of
>>> data for consumption by a block (including perhaps the future = possibilities
>>> of lists and paragraphs that Tom brought up)? what babel would= use to label
>>> a results block (possibly so that it could be consumed by anot= her block in a
>>> chain)? both? would that mean that #+tblname would go the way = of the dodo
>>> and that tables would be labelled with #+data (or #+object or = whatever else
>>> we come up with)?
>>
>> For point 3, Eric, I guess that whichever term is chosen, that doe= s not mean
>> that "results" will change (I mean: when it's a resu= lt of a block execution)?

I was expecting you'd always keep "results" for auto-in= serted results (after a
code block evaluation). But it makes sense to prefer the one term that will=
win.

I would definitely keep #+results= as this marks it as an *output* which can change during the next evaluatio= n, and not an input, which has to be modified by hand. I would actually go = so far and say that #+results *can be* src or object (using these terms), b= ut is in itself *not* identifying anything, apart from "this is the re= sult of an evaluation". So:

#+results
#+object_begin
=A0.
=A0.
=A0.
#+end

wou= ld be the result of an evaluation.

One could even, for clarities sak= e, say that

#+object

if no #+results is in the line before,
is a synonym for

#+input (or #+constant)
#+object_begin
= =A0.
=A0.
=A0.
#+end
=A0
Cheers,
=
Rainer


> I would be happy for results to change to data or tblname (if a table)=
> or whatever else is selected.

OK, clear.

>> In other words, if we choose for "object", we still will= have the possibility
>> to use "results" (automatically generated) and "obj= ect" to refer to something
>> we want to use in another call?
>>
>>>>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 named data [3] -- &quo= t;tblname" "resname" "results" "data" >>
>> I don't specifically like "resname".
>>
>> I would keep "results" for automatically generated "= ;results".
>>
>> I do like "data", but can learn to like "object&quo= t; as a more generic term,
>> future-proof for coming extensions.
>
> I'll mark you down as undecided for this term. :)

Yep! =A0I'm open to any suggestion you'll make.

>> Last remark: we could get one step further and wonder if it wouldn= 't be good
>> to impose a single way to pass variables? We currently have two di= fferent
>> mechanisms:
>>
>> =A0 =A0 #+srcname: convert-date-to-French-format
>> =A0 =A0 #+begin_src sql :var column=3D""
>> =A0 =A0 CONVERT(varchar(10), $column, 103) AS $column
>> =A0 =A0 #+end_src
>>
>> and
>>
>> =A0 =A0 #+srcname: convert-date-to-French-format(column=3D"&q= uot;)
>> =A0 =A0 #+begin_src sql
>> =A0 =A0 CONVERT(varchar(10), $column, 103) AS $column
>> =A0 =A0 #+end_src
>>
>> I guess that the first one is easier if we want to construct compl= ex variable
>> values (which call Emacs Lisp code or such), but...
>
> I don't feel that this example causes as much confusion, but if I&= #39;m
> wrong I am open to change on this front. =A0Although the only possible=
> change here would be to remove the second option as the first method o= f
> specifying variables is central to code block management.

Just that I remember both syntaxes weren't handled the same way f= or error
reporting (remember, when there is no default value: in one case, you can g= et
the name of the faulty block; in the other, not), and that makes me think i= s
not as simple as an alias. Hence, your Babel code is or can become differen= t
just because there are different alternatives to write certain things down.=

Then, as a user, I always wonder what's the best one? =A0"For a go= od error
reporting (with the name of the code block being outputted), which one do I=
have to use?" and such questions...

If we only have one way, we can be sure everybody experiences the same thin= gs
with the same semantical input.

Another point, that may or may not have much to do with this, is that I don= 't
have anymore the source name exported in HTML -- dunno when it disappeared,=
though. I remember that, at some point, it was due to having, or not, a
default value (at the time, having no default value was still allowed), but=
now, even with the default values for every var, I miss those names in the<= br> HTML (for literate programming support, it is quite useful to be able to se= e
the name of the block along with the code).

I repeat myself, but thanks, once again, for tackling this naming "pro= blem".

Best regards,
=A0Seb

--
Sebastien Vauban




=

--
Rainer M. Krug, PhD (Conservation Ecolog= y, SUN), MSc (Conservation Biology, UCT), Dipl. Phys. (Germany)

Cent= re of Excellence for Invasion Biology
Stellenbosch University
South Africa

Tel : =A0 =A0 =A0 +33 - (0)9 53 = 10 27 44
Cell: =A0 =A0 =A0 +33 - (0)6 85 62 5= 9 98
Fax (F): =A0 =A0 =A0 +33 - (0)9 58 10 27 44
<= br>Fax (D): =A0 =A0+49 - (0)3 21 21 25 22 44<= /a>

email: =A0 =A0 =A0= Rainer@krugs.de

Skype: =A0 =A0 =A0RMkrug




--
Rainer M. K= rug, PhD (Conservation Ecology, SUN), MSc (Conservation Biology, UCT), Dipl= . Phys. (Germany)

Centre of Excellence for Invasion Biology
Stell= enbosch University
South Africa

Tel : =A0 =A0 =A0 +33 - (0)9 53 10 27 44
Cell: =A0 = =A0 =A0 +33 - (0)6 85 62 59 98
Fax (F): =A0 =A0 =A0 +33 - (0)9 58 10 27 = 44

Fax (D): =A0 =A0+49 - (0)3 21 21 25 22 44

email: =A0 =A0 = =A0Rainer@krugs.de=

Skype: =A0 =A0 =A0RMkrug

--0016e64c26b42a56ab04b01a152c--