unofficial mirror of emacs-orgmode@gnu.org
 help / color / mirror / Atom feed
* 2 Surprises and 2 Questions Regarding Org Tangle
@ 2021-02-09 12:29 Lee Jia Hong
  2021-02-11 17:44 ` Diego Zamboni
                   ` (2 more replies)
  0 siblings, 3 replies; 6+ messages in thread
From: Lee Jia Hong @ 2021-02-09 12:29 UTC (permalink / raw)
  To: emacs-orgmode

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

(First time posting to a mailing list, please correct me if I did something wrong.)

TLDR:
Surprise 1: Different Noweb reference placing styles produces different tangled results.
Question 1: Is it a bug?

Surprise 2: Source block naming with #+NAME: and :noweb-ref produce different tangled results.
Question 2: Is it a bug?
------------------------------------------------------------------------------------

Hi,

I stumble upon this article (https://www.hhyu.org/posts/literate_config/), and there are two things that standout:
1. the way author places the Noweb reference, i.e.:
  (setq org-capture-templates
      '(
        <<ORG_CAPTURE>>
       )
  )
2. the way he uses :noweb-ref to tangle multiple code blocks to the same Noweb reference.



* Surprise 1: Different Noweb Reference Placing Styles Produces Different Tangled Results
------------------------------------------------------------------------------------------------
The way he places the Noweb reference intrigues me, so I try writing it in different (placing) styles:
P1:
(setq org-capture-templates '(<<ORG_CAPTURE>>))

P2:
(setq org-capture-templates
      '(<<ORG_CAPTURE>>))

P3:
(setq org-capture-templates
      '(
        <<ORG_CAPTURE>>))

P4:
(setq org-capture-templates
      '(
        <<ORG_CAPTURE>>
        ))

Tangled results using P3 and P4 styles match my expectations. But the results of P1 and P2 styles surprise me.

Expected result for P1:
#+begin_example
(setq org-capture-templates '(("t" "TODO inbox"
                                   entry
                                   (file "~/gtd/capture.org")
                                   "* TODO %?
                                   SCHEDULED: %t")
                              ("n" "notes inbox"
                                   entry
                                   (file "~/gtd/inbox.org")
                                   "* %T\n%i%?")))
#+end_example

Actual result:
#+begin_example
(setq org-capture-templates '(("t" "TODO inbox"
(setq org-capture-templates '( entry
(setq org-capture-templates '( (file "~/gtd/capture.org")
(setq org-capture-templates '( "* TODO %?
(setq org-capture-templates '(    SCHEDULED: %t")
(setq org-capture-templates '(("n" "notes inbox"
(setq org-capture-templates '( entry
(setq org-capture-templates '( (file "~/gtd/inbox.org")
(setq org-capture-templates '( "* %T\n%i%?")))
#+end_example

Expected result for P2:
#+begin_example
(setq org-capture-templates
      '(("t" "TODO inbox"
         entry
         (file "~/gtd/capture.org")
         "* TODO %?
            SCHEDULED: %t")
        ("n" "notes inbox"
         entry
         (file "~/gtd/inbox.org")
         "* %T\n%i%?")))
#+end_example

Actual result:
#+begin_example
(setq org-capture-templates
      '(("t" "TODO inbox"
      '( entry
      '( (file "~/gtd/capture.org")
      '( "* TODO %?
      '(    SCHEDULED: %t")
      '(("n" "notes inbox"
      '( entry
      '( (file "~/gtd/inbox.org")
      '( "* %T\n%i%?")))
#+end_example

Question 1: Is this a bug? If not, how can I make sure that style P1 and P2 produce the expected results?



* Surprise 2: Source Block Naming with #+NAME: and :noweb-ref Produce Different Tangled Results
-----------------------------------------------------------------------------------------------------------
I have been naming my source blocks with #+NAME, and it's my first time realising that it's possible to tangle multiple source blocks to a single Noweb reference. To try it out, I write the reference holder like this:
#+begin_src emacs-lisp
(setq org-capture-templates
      '(
        <<ORG_CAPTURE>>))
#+end_src
(Note: Use placing style P3 because styles P1 and P2 doesn't work as expected, see Surprise 1 above)

Then follow by source blocks named with #+NAME:
#+NAME: ORG_CAPTURE
#+begin_src emacs-lisp
("t" "TODO inbox"
 entry
 (file "~/gtd/capture.org")
 "* TODO %?
    SCHEDULED: %t")
#+end_src

#+NAME: ORG_CAPTURE
#+begin_src emacs-lisp
("n" "notes inbox"
 entry
 (file "~/gtd/inbox.org")
 "* %T\n%i%?")
#+end_src

Expected result:
#+begin_example
(setq org-capture-templates
      '(
        ("t" "TODO inbox"
         entry
         (file "~/gtd/capture.org")
         "* TODO %?
            SCHEDULED: %t")
        ("n" "notes inbox"
         entry
         (file "~/gtd/inbox.org")
         "* %T\n%i%?")))
#+end_example

Actual result:
#+begin_example
(setq org-capture-templates
      '(
        ("t" "TODO inbox"
         entry
         (file "~/gtd/capture.org")
         "* TODO %?
            SCHEDULED: %t")))
#+end_example
(Not working as expected, because it only tangle the first source block with the given name.)

However, with :noweb-ref <<REFERENCE>>, it's working as expected:
#+begin_src emacs-lisp :noweb-ref ORG_CAPTURE
("t" "TODO inbox"
 entry
 (file "~/gtd/capture.org")
 "* TODO %?
    SCHEDULED: %t")
#+end_src

#+begin_src emacs-lisp :noweb-ref ORG_CAPTURE
("n" "notes inbox"
 entry
 (file "~/gtd/inbox.org")
 "* %T\n%i%?")
#+end_src

Result:
#+begin_example
(setq org-capture-templates
      '(
        ("t" "TODO inbox"
         entry
         (file "~/gtd/capture.org")
         "* TODO %?
            SCHEDULED: %t")
        ("n" "notes inbox"
         entry
         (file "~/gtd/inbox.org")
         "* %T\n%i%?")))
#+end_example

Question 2: Is this a bug? If not, how can I produce the expected result using #+NAME naming?
(I prefer #+NAME over :noweb-ref because that line is more obvious and easily to be read since it can be fontified to stand out in different colour for a given Emacs theme.)



* What I Have Done
--------------------
Read the Org-mode info Section 15.10 "Noweb Reference Syntax".



* My Environments
--------------------
OS: Ubuntu 18.04.3 LTS x86_64
Emacs version: GNU Emacs 28.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.22.30, cairo version 1.15.10) of 2020-10-14
Org-mode version: Org mode version 9.3 (release_9.3 @ /usr/local/share/emacs/28.0.50/lisp/org/)

You can reproduce my "experiment" with the attached Org file. Tangle the attached file and you will get eight files (eight because there are eight different combinations of placing style * naming style). Then tangle each of the eight file to see the result for yourself.



----
Regards,
Jia Hong

[-- Attachment #2: experiment-file.org --]
[-- Type: application/octet-stream, Size: 7166 bytes --]

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: 2 Surprises and 2 Questions Regarding Org Tangle
  2021-02-09 12:29 2 Surprises and 2 Questions Regarding Org Tangle Lee Jia Hong
@ 2021-02-11 17:44 ` Diego Zamboni
  2021-02-13  2:41   ` Kevin M. Stout
  2021-02-13  4:13   ` Kevin M. Stout
  2021-02-11 17:46 ` Greg Minshall
  2021-02-11 17:52 ` Greg Minshall
  2 siblings, 2 replies; 6+ messages in thread
From: Diego Zamboni @ 2021-02-11 17:44 UTC (permalink / raw)
  To: Lee Jia Hong; +Cc: emacs-orgmode

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

Jia,

#2 is known (maybe documented? Not sure) behavior: using :noweb-ref
accumulates multiple blocks with the same name, whereas #+NAME uses only
the first one. I think #+NAME's are supposed to be unique within a document.

I don't know about #1, the output from your P1 example seems surprising to
me as well.

--Diego



On Thu, Feb 11, 2021 at 5:13 PM Lee Jia Hong <jia_hong@live.com.my> wrote:

> (First time posting to a mailing list, please correct me if I did
> something wrong.)
>
> TLDR:
> Surprise 1: Different Noweb reference placing styles produces different
> tangled results.
> Question 1: Is it a bug?
>
> Surprise 2: Source block naming with #+NAME: and :noweb-ref produce
> different tangled results.
> Question 2: Is it a bug?
>
> ------------------------------------------------------------------------------------
>
> Hi,
>
> I stumble upon this article (https://www.hhyu.org/posts/literate_config/),
> and there are two things that standout:
> 1. the way author places the Noweb reference, i.e.:
>   (setq org-capture-templates
>       '(
>         <<ORG_CAPTURE>>
>        )
>   )
> 2. the way he uses :noweb-ref to tangle multiple code blocks to the same
> Noweb reference.
>
>
>
> * Surprise 1: Different Noweb Reference Placing Styles Produces Different
> Tangled Results
>
> ------------------------------------------------------------------------------------------------
> The way he places the Noweb reference intrigues me, so I try writing it in
> different (placing) styles:
> P1:
> (setq org-capture-templates '(<<ORG_CAPTURE>>))
>
> P2:
> (setq org-capture-templates
>       '(<<ORG_CAPTURE>>))
>
> P3:
> (setq org-capture-templates
>       '(
>         <<ORG_CAPTURE>>))
>
> P4:
> (setq org-capture-templates
>       '(
>         <<ORG_CAPTURE>>
>         ))
>
> Tangled results using P3 and P4 styles match my expectations. But the
> results of P1 and P2 styles surprise me.
>
> Expected result for P1:
> #+begin_example
> (setq org-capture-templates '(("t" "TODO inbox"
>                                    entry
>                                    (file "~/gtd/capture.org")
>                                    "* TODO %?
>                                    SCHEDULED: %t")
>                               ("n" "notes inbox"
>                                    entry
>                                    (file "~/gtd/inbox.org")
>                                    "* %T\n%i%?")))
> #+end_example
>
> Actual result:
> #+begin_example
> (setq org-capture-templates '(("t" "TODO inbox"
> (setq org-capture-templates '( entry
> (setq org-capture-templates '( (file "~/gtd/capture.org")
> (setq org-capture-templates '( "* TODO %?
> (setq org-capture-templates '(    SCHEDULED: %t")
> (setq org-capture-templates '(("n" "notes inbox"
> (setq org-capture-templates '( entry
> (setq org-capture-templates '( (file "~/gtd/inbox.org")
> (setq org-capture-templates '( "* %T\n%i%?")))
> #+end_example
>
> Expected result for P2:
> #+begin_example
> (setq org-capture-templates
>       '(("t" "TODO inbox"
>          entry
>          (file "~/gtd/capture.org")
>          "* TODO %?
>             SCHEDULED: %t")
>         ("n" "notes inbox"
>          entry
>          (file "~/gtd/inbox.org")
>          "* %T\n%i%?")))
> #+end_example
>
> Actual result:
> #+begin_example
> (setq org-capture-templates
>       '(("t" "TODO inbox"
>       '( entry
>       '( (file "~/gtd/capture.org")
>       '( "* TODO %?
>       '(    SCHEDULED: %t")
>       '(("n" "notes inbox"
>       '( entry
>       '( (file "~/gtd/inbox.org")
>       '( "* %T\n%i%?")))
> #+end_example
>
> Question 1: Is this a bug? If not, how can I make sure that style P1 and
> P2 produce the expected results?
>
>
>
> * Surprise 2: Source Block Naming with #+NAME: and :noweb-ref Produce
> Different Tangled Results
>
> -----------------------------------------------------------------------------------------------------------
> I have been naming my source blocks with #+NAME, and it's my first time
> realising that it's possible to tangle multiple source blocks to a single
> Noweb reference. To try it out, I write the reference holder like this:
> #+begin_src emacs-lisp
> (setq org-capture-templates
>       '(
>         <<ORG_CAPTURE>>))
> #+end_src
> (Note: Use placing style P3 because styles P1 and P2 doesn't work as
> expected, see Surprise 1 above)
>
> Then follow by source blocks named with #+NAME:
> #+NAME: ORG_CAPTURE
> #+begin_src emacs-lisp
> ("t" "TODO inbox"
>  entry
>  (file "~/gtd/capture.org")
>  "* TODO %?
>     SCHEDULED: %t")
> #+end_src
>
> #+NAME: ORG_CAPTURE
> #+begin_src emacs-lisp
> ("n" "notes inbox"
>  entry
>  (file "~/gtd/inbox.org")
>  "* %T\n%i%?")
> #+end_src
>
> Expected result:
> #+begin_example
> (setq org-capture-templates
>       '(
>         ("t" "TODO inbox"
>          entry
>          (file "~/gtd/capture.org")
>          "* TODO %?
>             SCHEDULED: %t")
>         ("n" "notes inbox"
>          entry
>          (file "~/gtd/inbox.org")
>          "* %T\n%i%?")))
> #+end_example
>
> Actual result:
> #+begin_example
> (setq org-capture-templates
>       '(
>         ("t" "TODO inbox"
>          entry
>          (file "~/gtd/capture.org")
>          "* TODO %?
>             SCHEDULED: %t")))
> #+end_example
> (Not working as expected, because it only tangle the first source block
> with the given name.)
>
> However, with :noweb-ref <<REFERENCE>>, it's working as expected:
> #+begin_src emacs-lisp :noweb-ref ORG_CAPTURE
> ("t" "TODO inbox"
>  entry
>  (file "~/gtd/capture.org")
>  "* TODO %?
>     SCHEDULED: %t")
> #+end_src
>
> #+begin_src emacs-lisp :noweb-ref ORG_CAPTURE
> ("n" "notes inbox"
>  entry
>  (file "~/gtd/inbox.org")
>  "* %T\n%i%?")
> #+end_src
>
> Result:
> #+begin_example
> (setq org-capture-templates
>       '(
>         ("t" "TODO inbox"
>          entry
>          (file "~/gtd/capture.org")
>          "* TODO %?
>             SCHEDULED: %t")
>         ("n" "notes inbox"
>          entry
>          (file "~/gtd/inbox.org")
>          "* %T\n%i%?")))
> #+end_example
>
> Question 2: Is this a bug? If not, how can I produce the expected result
> using #+NAME naming?
> (I prefer #+NAME over :noweb-ref because that line is more obvious and
> easily to be read since it can be fontified to stand out in different
> colour for a given Emacs theme.)
>
>
>
> * What I Have Done
> --------------------
> Read the Org-mode info Section 15.10 "Noweb Reference Syntax".
>
>
>
> * My Environments
> --------------------
> OS: Ubuntu 18.04.3 LTS x86_64
> Emacs version: GNU Emacs 28.0.50 (build 1, x86_64-pc-linux-gnu, GTK+
> Version 3.22.30, cairo version 1.15.10) of 2020-10-14
> Org-mode version: Org mode version 9.3 (release_9.3 @
> /usr/local/share/emacs/28.0.50/lisp/org/)
>
> You can reproduce my "experiment" with the attached Org file. Tangle the
> attached file and you will get eight files (eight because there are eight
> different combinations of placing style * naming style). Then tangle each
> of the eight file to see the result for yourself.
>
>
>
> ----
> Regards,
> Jia Hong
>

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

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: 2 Surprises and 2 Questions Regarding Org Tangle
  2021-02-09 12:29 2 Surprises and 2 Questions Regarding Org Tangle Lee Jia Hong
  2021-02-11 17:44 ` Diego Zamboni
@ 2021-02-11 17:46 ` Greg Minshall
  2021-02-11 17:52 ` Greg Minshall
  2 siblings, 0 replies; 6+ messages in thread
From: Greg Minshall @ 2021-02-11 17:46 UTC (permalink / raw)
  To: Lee Jia Hong; +Cc: emacs-orgmode

Lee Jia Hong,

for your surprise number one, maybe look at this point of the Org Manual
----
Noweb insertions honor prefix characters that appear before the noweb
syntax reference.
----
basically, if the source of a <<noweb>> has multiple lines (N, say), then the
output of a subsequent <<noweb>> *copies* that line N times, replacing
that part of the invoking line where "<<noweb>>" is.

cheers, Greg


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: 2 Surprises and 2 Questions Regarding Org Tangle
  2021-02-09 12:29 2 Surprises and 2 Questions Regarding Org Tangle Lee Jia Hong
  2021-02-11 17:44 ` Diego Zamboni
  2021-02-11 17:46 ` Greg Minshall
@ 2021-02-11 17:52 ` Greg Minshall
  2 siblings, 0 replies; 6+ messages in thread
From: Greg Minshall @ 2021-02-11 17:52 UTC (permalink / raw)
  To: Lee Jia Hong; +Cc: emacs-orgmode

Lee Jia Hong,

on your second surprise, there was some discussion on the e-mail list,
around 19 April, 2020, somewhere near this area.  you might refer to
that.

cheers, again, Greg


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: 2 Surprises and 2 Questions Regarding Org Tangle
  2021-02-11 17:44 ` Diego Zamboni
@ 2021-02-13  2:41   ` Kevin M. Stout
  2021-02-13  4:13   ` Kevin M. Stout
  1 sibling, 0 replies; 6+ messages in thread
From: Kevin M. Stout @ 2021-02-13  2:41 UTC (permalink / raw)
  To: emacs-orgmode

On 2021-02-11 18:44, Diego Zamboni wrote:

> #2 is known (maybe documented? Not sure) behavior: using :noweb-ref
> accumulates multiple blocks with the same name, whereas #+NAME uses only
> the first one.

Deep in org-babel-tangle,                                                                                                                                                                                                                                                                                                                                                                                                                                                                   
  (org-babel-map-src-blocks nil                                                                                                                                                                                                                   (let ((i (let ((org-babel-current-src-block-location (point)))                                                                                                                                                                                           (org-babel-get-src-block-info 'light))))                                                                                                                                                                                             (when (equal (or (cdr (assq :noweb-ref (nth 2 i)))                                                                                                                                                                                                             (nth 4 i))                                                                                                                                                                                                                                source-name)                                                                                                                                                                                                                       ...)))

So, while :noweb-ref gets priority over #+NAME, we can still accumulate blocks
having the same #+NAME (provided there's no overriding :noweb-ref).

> I think #+NAME's are supposed to be unique within a document.

Even though I'm a huge fan of this behavior, which lines up well with the
traditional WEB and Noweb behavior, the Org manual's discussion of code blocks
does say, "For duplicate names, Org mode's behavior is undefined." [Section
14.1] So,

Dear Org Maintainers,

Please do not change org-babel-tangle's accumulation behavior for duplicate
#+NAME's. It's handy, and users of other literate programming tools will find it
familiar. Also, #+NAME is a nicer per-block syntax than :noweb-ref.

Sincerely,
Kevin M. Stout


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: 2 Surprises and 2 Questions Regarding Org Tangle
  2021-02-11 17:44 ` Diego Zamboni
  2021-02-13  2:41   ` Kevin M. Stout
@ 2021-02-13  4:13   ` Kevin M. Stout
  1 sibling, 0 replies; 6+ messages in thread
From: Kevin M. Stout @ 2021-02-13  4:13 UTC (permalink / raw)
  To: emacs-orgmode

On 2021-02-11 18:44, Diego Zamboni wrote:

> #2 is known (maybe documented? Not sure) behavior: using :noweb-ref
> accumulates multiple blocks with the same name, whereas #+NAME uses only
> the first one. I think #+NAME's are supposed to be unique within a document.

It seems that more recent versions of org-babel-expand-noweb-references (not
org-babel-tangle, as I said in an earlier message) no longer accumulate blocks
with common #+NAMEs. (Now, though, #+NAME has priority over :noweb-ref, which is
the opposite of how things were done before.) Looking through some older
discussions on the topic, I do see the downsides of accepting duplicate #+NAMEs,
which are rooted in the assumption of uniqueness made elsewhere. Even so, I
still hold that

#+NAME: this is a cool way to do something
#+BEGIN_SRC language
  stuff
#+END_SRC
 
is a much nicer syntax than

#+BEGIN_SRC language :noweb-ref "this is a cool way to do something"
  stuff
#+END_SRC

especially as a project grows.

Perhaps we could have a variation on #+NAME that doesn't need to be unique?
Maybe something like #+NOREF, to evoke :noweb-ref? Or #+NONAME?

Sincerely,
Kevin M. Stout


^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2021-02-13  4:13 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-09 12:29 2 Surprises and 2 Questions Regarding Org Tangle Lee Jia Hong
2021-02-11 17:44 ` Diego Zamboni
2021-02-13  2:41   ` Kevin M. Stout
2021-02-13  4:13   ` Kevin M. Stout
2021-02-11 17:46 ` Greg Minshall
2021-02-11 17:52 ` Greg Minshall

unofficial mirror of emacs-orgmode@gnu.org

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://yhetil.org/orgmode/0 orgmode/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 orgmode orgmode/ https://yhetil.org/orgmode \
		emacs-orgmode@gnu.org
	public-inbox-index orgmode

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.yhetil.org/yhetil.emacs.orgmode
	nntp://news.gmane.io/gmane.emacs.orgmode


AGPL code for this site: git clone http://ou63pmih66umazou.onion/public-inbox.git