Buggy :comments link when tangling babel src blocks?

Question

I am using org-mode version 9.5.5

When I tangle code C-c C-v t of this org-mode file:

#+title: Demo
#+property: header-args:sh :tangle example.sh :comments link

* Part A
** source
#+begin_src sh
  echo "Part A"
#+end_src

* Part B
** source
#+begin_src sh
  echo "Part B"
#+end_src

I get this example.sh file

# [[file:poub.org::*source][source:1]]
echo "Part A"
# source:1 ends here

# [[file:poub.org::*source][source:1]]
echo "Part B"
# source:1 ends here

Now I move to the line echo "Part B" and call org-babel-tangle-jump-to-org I jump back to the org-mode code block * Part A instead of the right * Part B.

If I manually modify the generated example.sh file as follows

# [[file:poub.org::*source][source:2]]
echo "Part B"
# source:2 ends here

then org-babel-tangle-jump-to-org works correctly and sends to right * Part B header's source block.

This looks like an org-mode bug. Do you observe the same behavior ?

Answer 1

[Expanded version of my comment above, but now I've gone through the code, so no guessing]

When enabled, link comments on tangled blocks allow you to jump back to the appropriate place in the Org mode file that was used to generate the tangled blocks. When a source block is tangled, the tangled file will contain the body of the source block, surrounded by comments that contain a link. You can then do M-x org-babel-tangle-jump-to-org with your cursor on the tangled block, which will use the link in the comment above to take you back to the Org mode file that generated the file with the tangled source blocks.

What the OP points out is that, unless you take some care, it is easy to create links that don't quite work. In particular, the two source blocks that are tangled are in different sections, but they both have the same name. When the file is tangled (using the function org-babel-tangle-collect-blocks, the links in the comments are constructed using the format section_name:seq_no where the sequence number increments by one for every source block in each section, but is reset to 1 at the beginning of the next section. So one way to disambiguate the links is to make sure that each section has a unique name. The OP had two sections with the same name, producing ambiguous results. That's not necessarily a bug in the code, but the documentation does not make clear how the links are produced, so maybe it can be considered a documentation bug.

Another way (and my preferred way, not only for this reason) is to name each source block uniquely:

#+name: src_a
#+begin_src sh
  echo "Part A"
#+end_src

#+name: src_b
#+begin_src sh
  echo "Part B"
#+end_src

Then it does not matter what the sections are named or whether the blocks are in the same or different sections and the sequence number is not used. Instead you get a tangled file like this:

# [[file:foo302.org::src_a][src_a]]
echo "Part A"
# src_a ends here

# [[file:foo302.org::src_b][src_b]]
echo "Part B"
# src_b ends here

You might say that coming up with unique names for the source blocks is not any safer or simpler than coming up with unique names for the sections: that is correct. But the names of the source blocks can be short identifiers that are easy to make unique, a practice that programmers in particular use all the time; they don't have to be sentences like section headings, which in some cases have to be named identically (e.g. corresponding subsections for two different top-level sections - it might make eminent sense to use the same name for both). Naming blocks has other advantages too: the #+RESULTS blocks of named source blocks are also tagged with the name, so Org Babel can actually find the results block even if it is separated from its source block by other stuff - in particular, if you want to specify attributes to a results block, you will have to use named source blocks if you value your sanity. The OP mentions a different question where I made the same recommendation. See also this question for adding attributes to results blocks and this question for using org-sbe.

Name your source blocks!