Confusion about header arguments

Question

I get that there are different levels at which Header arguments in org mode, specifically LP can be defined and that the more specialized ones, i.e. deeper within the tree hierarchy, take precedence over the higher ones. So there are

- System-wide header arguments (usually in config files)

-File-wide header arguments

#+PROPERTY: header-args :dir "~/literate_test"

- Language-specific header arguments

- Header arguments in Org mode properties

  :PROPERTIES:
  :header-args: :results output :mkdirp yes
  :header-args+: :var image_name=not_finished
  :header-args+: :eval never-export
  :header-args+:elisp: :exports code
  :header-args+:dir: literate_test
  :header-args+:tag: 'test'
  :END:

- Language-specific header arguments in Org mode properties

- Code block specific header arguments

- Header arguments in function calls

and in order for arguments of the same kind to apply, I have to append them with +.

what confuses me though, is when do I have to use specific variables like below

* Header 
:PROPERTIES: 
:PRJ-DIR: ~/prj/dir/ 
:tangle: ~/dir/my/testfile.el
:END:

and when to use the :header-args: syntax

PROPERTIES:
  :header-args: :results output :mkdirp yes
  :END:

is there a rule to this?

Also, org seems to do some caching in the background when it comes to file local variables, header arguments etc. How does that work and how to refresh the entire buffer then?

Answer 1

The rule is that if you want to specify header arguments for source blocks, then you need to use the various headers-args* properties: only those are consulted when a source block is executed.

You can define other properties like PRJ-DIR and tangle, as you did above. But unless you do something special with them, they will not affect the evaluation of a block. You would have to do something like this to make use of them:

* foo
  :PROPERTIES:
  :PRJ-DIR: ~/project
  :END:

  #+begin_src shell :var x=(org-entry-get (point) "PRJ-DIR")
    echo Variable x has the value $x
  #+end_src

  #+RESULTS:
  : Variable x has the value ~/project

Here, I set the variable x of the shell block to the value that I get from looking up the property PRJ-DIR in the current context.