Doc: Pacemaker Explained: Add index entries for resource meta-attribu…

[clumens]

…tes.

Fixes T199

[nrwahl2]

The contents look good given the approach being used. I have a couple of thoughts on that approach though.

---

I think we should drop the resource; option, <name> lines, since the resource; meta-attribute, <name> lines make them redundant.

---

Also, looking at T199, I see that Ken's description was:

Add index entries for "resource; meta-attribute" as well as "resource meta-attribute; attribute name" for each meta-attribute

You noted:

I think the first entry is supposed to be "resource; meta-attribute, attribute name". Otherwise the generated index looks incorrect.

I agree, if we're talking about the both entries being per-attribute. However, here is my interpretation of Ken's description:

• index entry "resource; meta-attribute" attached to the section containing the main meta-attributes table: "Resource Meta-Attributes"
• single index entry "resource meta-attribute; attribute name" for each meta-attribute

In that case, we would no longer have the comma-separated entries like the current "option, priority" nested under the top-level "resource" entry. Rather, we'd have a top-level "resource meta-attribute" entry, with "priority" (etc.) nested underneath it.

---

Thoughts on each of the above?

[clumens]

Here's a quick tip: Don't look at the generated index unless you want to start seeing inconsistencies you want to fix. Sigh.

[clumens]

I think we should drop the resource; option, <name> lines, since the resource; meta-attribute, <name> lines make them redundant.

Yeah agreed. We don't have a big block like that anywhere else in Pacemaker Explained except for under clone (see previous comment about finding inconsistencies).

I agree, if we're talking about the both entries being per-attribute. However, here is my interpretation of Ken's description:

* index entry "resource; meta-attribute" attached to the section containing the main meta-attributes table: "Resource Meta-Attributes"

* single index entry "resource meta-attribute; attribute name" for each meta-attribute

In that case, we would no longer have the comma-separated entries like the current "option, priority" nested under the top-level "resource" entry. Rather, we'd have a top-level "resource meta-attribute" entry, with "priority" (etc.) nested underneath it.

I think what I want is three things:

• Top level resource meta-attribute with every meta-attribute listed under it. For instance:

resource meta-attribute
    allow-migrate, 40
    allow-unhealthy-nodes, 40
    ...

• Top level resource with each meta-attribute, attribute listed under it. For instance:

resource, 35
    ...
    meta-attribute, allow-migrate, 40
    meta-attribute, allow-unhealthy-nodes, 40
    ...

I think this is what you're suggesting I get rid of, but if you look through the rest of the index, you'll see plenty of sub-lists like this. On the other hand, just looking at this same page of the index, I don't see any other instances of having both this and the previous thing I listed. For example, rsc_colocation looks like this:

rsc_colocation
    attribute, id, 60
    attribute, influence, 61
    ...

And not this:

rsc_colocation
    attribute, id, 60
    attribute, influence, 61
    ...
rsc_colocation attributes
    id, 60
    influence, 61
    ...

I could go either way with it. I could also be convinced that broader changes are needed.

• Okay finally the third thing. I think every meta-attribute should be listed like this:

remote-allow-migrate
    resource meta-attribute, 44

Instead of the current:

remote-allow-migrate
    resource option, 44

[clumens]

I just noticed this. There's also a top-level meta-attribute entry with some things under it:

meta-attribute
    alert meta-attributes, 130
    enabled (alert), 130
    ...

[nrwahl2]

Top level resource meta-attribute with every meta-attribute listed under it. For instance:
...
Top level resource with each meta-attribute, attribute listed under it. For instance:

I'm not seeing the point of having both of these. Open to discussion.

resource meta-attribute
allow-migrate, 40
allow-unhealthy-nodes, 40
...

Where are the numbers coming from in all these? I don't see them in the generated pages or in the source.

I think this is what you're suggesting I get rid of, but if you look through the rest of the index, you'll see plenty of sub-lists like this

Despite what Ken proposed, the sub-lists seem to me as if they make the most sense. That is, resource; meta-attribute, attribute name. But I don't see any reason to have both that and a list under a top-level resource meta-attribute entry. (Note: in my previous comment, I was just trying to interpret what Ken had proposed. Now, I'm saying that I think I like the sub-list more than my interpretation of what he proposed.)

I could potentially see having a top-level meta-attribute though, or even a three-level meta-attribute; resource; attribute-name. Not sure off the top of my head whether nesting these more than two levels deep using more semicolons is possible.

• Okay finally the third thing. I think every meta-attribute should be listed like this:

remote-allow-migrate
    resource meta-attribute, 44

Instead of the current:

remote-allow-migrate
    resource option, 44

I agree. If we're going to keep having a top-level entry for each meta-attribute, then it should say "meta-attribute".

I'm not sure there's a point in even having top-level entries though. This isn't a book. Consider how people are likely to actually use an index (if anyone uses it at all). They'll probably do a Ctrl+F search. Possibilities:

• User searches for "resource": they find it under the top-level "meta-attribute" entry, or they find a top-level "resource" entry's "meta-attribute" sub-list, depending on how we organize it. Then they read through all of the possible resource meta-attributes in that list.
• User searches for "meta-attribute": same as above, rearranging things as needed
• User searches for "remote-allow-migrate": they'll find it no matter what it's listed underneath, without the need for a top-level entry.

However, there are two (maybe more but that's all I'm seeing besides some duplication under migration-threshold) resource meta-attributes that have something else underneath their top-level entry. I'm seeing "resource-stickiness" and "maintenance."

I could take that or leave it.