Include file documentation revamp.

[DavidSagan]

No description provided.

[ax3l]

Same comment as here

@DavidSagan :

I don't understand this. How can, for example, element specific information be included when the include file does not select any specific element?

I am commenting about where the include is placed: inside he facility: list like other commands -- or alternatively prefixing includes to the list. We already went back and forth on this and decided to put it inside the facility group.

[DavidSagan]

You misunderstood me. There should be no restriction where includes can be placed.

[ax3l]

Let's see if that is necessary by example. Allowing includes everywhere seems a bit overly complicated to me, given that we can already derive from and reference to any element and parameter group

[DavidSagan]

Actually allowing includes anywhere is fairly trivial. An include just means that reading in the lattice information is switched from one file to another and then back when the second file has been read. I have experience doing this with Bmad and it is very straight forward.

[ax3l]

This could have the same effect and would not need a doubly check where include can appear.

Suggested change

	- Q01:
	- include: "../base-lattice.pals.yaml"
	- Q01:

[DavidSagan]

There does not need to be any checking since there should be no restriction where includes can be placed.

[ax3l]

To understand what you try to achieve, can you please make 2-3 examples with exact syntax in the included file shown? I think this is going to be more complicated than it needs to be.

[DavidSagan]

I expanded the example.

[ax3l]

I skipped this here because it is optional (with a default) and introduced later. It is also unrelated to include, which is the focus of this PR.

Suggested change

phase_space_coordinates: KINETIC_AND_MOMENTUM

[DavidSagan]

I modified the sentence before to indicate this is an example.

[ax3l]

Please do not mix multiple changes per PR, this is unrelated. Happy to discuss separately how to restructure examples.

This is the very first example, I would keep it simple and add the bare essentials, i.e., required keys only.

[DavidSagan]

I added that this is optional. We can get the opinion of other people.

[DavidSagan]

Also the two sections changed are linked so I considered this one change.

[ax3l]

This appears overly complicated. For including a single element from antoher file, we could simply do:

  facility:
    - my_drift:
        kind: Drift
    - include: "other_file.pals.yaml:some_quad"
    - QO1:
        kind: Quadrupole
        some_field: some_quad.k1

That way we can use the existing inheritance logic and do not need to add more specific include logic at any place of any kind.

[DavidSagan]

The versatility in being able to include at any point in the information tree is great. If you do want a restriction, you need to come up with a good argument as to why it is necessary. Note: Allowing include logic at any level is trivial to implement in code. In fact, making a restriction will make the code more complicated (but not by much).

[DavidSagan]

And talking about complicated, implementing a construct like include: "other_file.pals.yaml:some_quad" where the included file needs to be searched first to find the structure to be included is way more complicated than simply including a file wholesale.