Replacing profiled xrefs with keys

[mbakeranalecta]

I've discovered that there are a number of xrefs that have been incorrectly profiled, so I have been going through fixing them. (There seems to be a tendency to assume that applying a condition to an xref makes the link conditional, when in fact, of course, it makes the text conditional as well, leading to incomplete sentences.)

In going through them, I have found many cases where there are two xrefs side by side with different profiles because they link to different topics. This is frequently because one links to an Eclipse topic and one to a Standalone topic.

A much easier way to do this is to give the paired eclipse and standalone topics the same key and then link to that key. This way there is only one link in the text, with no profiling.

I've tested this approach and it seems to work perfectly.

I'd recommend this as standard practice from now on, and I will at some point convert the existing cases to this method.

Similarly, I recommend that we always use keys for xrefs and always use conkeyref rather than conref.

And since this is a policy I think many organizations ought to adopt, I'd like to recommend an option that would remove direct linking and conrefing as options in the interface, forcing the author to use keys.

[georgebina]

We can implement this though Schematron - add also a rule to the styleguide in the github.com/georgebina/dim project and then we will get a warning (or error) if we use a conref or a cross reference directly.
In fact I was thinking to bring the generated rules from that project in the userguide and set it as automatic validation and we can use it also for batch validation. Currently it shows more than a 1000 issues, most of them related to the use of ; to end list items.

[mbakeranalecta]

I like this idea.

I have been removing the ; at the end of lists as I find them. At some point we should do a sweep through the whole doc set, but probably not while multiple people are working on the docs.No sense in risking merge issues when we don't have to.