Re: [RFC] Standardized code block keywords

[Rainer M Krug <r.m.krug@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 7269 bytes --]

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@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

[-- Attachment #2: Type: text/html, Size: 9790 bytes --]