Re: [docbook-apps] link linkend xlink:href olink and xinclude, v5

[Thomas Schraitle <tom_schr@web.de>]

Hi,

> Thomas Schraitle wrote:
> > Is the method with @xml:id and linkend not an option for you?
> 
> Yes, I think that was my early concern when I realised there
> are so many options to choose from! If I'm going to use
> the id value, then <xref linkend='idval'/> seems the most
> common one? I'm not sure why glossary targets are so special.

Not glossary target, xrefs to glossentrys. They are "special" as 
xref needs a title to resolve it correctly.
A glossentry doesn't have a title. It could be discussed, if this
is an error and should be corrected. Maybe a xref to a glossentry
should use the glossterm. 


> [...]
> But it would be needed if I use the <glossterm>Domain name</glossterm>
> form? At least if I wanted to be sure it was 'valid' before
> processing with the stylesheets.

Yes, in this case it would make sense to use an additional Schematron rule.


> > Maybe there are scenarios where Schematron is more appropriate, but
> > I'm not sure.
> > 
> If we asked, I'm sure there are quite a few 'options' that
> could be checked with Schematron. Such as:
> using <glossterm>Domain name</glossterm>  without the
> - glossterm.auto.link set to 1 in the customization layer.
> - Mismatches between custom settings (use css, no css stylesheet)
> [...]

Well, I fear, these parameters are only available in the transformation
step, not at validation time.


> >> Or are there just too many link options?
> > 
> > Maybe, maybe not. There have to be many link options as DocBook is
> > very general and users have different needs.
> 
> I wonder how many are becoming redundant as new technologies are
> introduced?

That's a good question. As an example, I'm wondering if coref and
footnoteref are really needed and can be replaced by a simple xref.
But users might have some use cases for it.


> olink and xInclude spring to mind (though they have
> slightly different purposes).
> <glossterm linkend="NetAddr">network address</glossterm> and
> <xref linkend='Netaddr'/>
> and <link linkend="NetAddr">network address</link>

All have their purpose:

1. <glossterm linkend="NetAddr">network address</glossterm>
That's used when you want the "hot link" to be different from the
glossentry/glossterm text.

2. <xref linkend="Netaddr"/>
That's the case where this doesn't really work as in glossentry is
no title. So xref can't automatically generate the linking text.
Bug? Feature?

3. <link linkend="NetAddr">network address</link>
Similar to (1), but with a more general semantic.

4. <olink ...>...</olink>
If you want to create a link across document bounderies, this is
the preferred method. However, it comes at a cost: you can't
validate it in the validation step. They can only be checked 
during the transformation.

5. XInclude
I don't think they count as a "link" as the above elements. 
It's resolved completely, but you know that already. :)

Actually, there are even more: I omitted XLinks and firstterm.


> Providing options is good. Providing too many is confusing!
> Getting the balance right is the hard part.

That's true.


> > Apart from that, linking can also be complicated: you have
> > internal cross references (xref), maybe external URLs (link, ulink)
> > and links that cross your document bounderies (olink) to name the
> > most prominent ones.
> 
> I'm not sure (for db5) what the 'preferred' processing model is?

I don't think DocBook defines a 'preferred' processing model (if
you mean something different than the usual validation->transformation
steps).


> Should we resolve xincludes prior to validation?

In general yes, otherwise you can not resolve any cross references.


> Is olink now deprecated? 

I don't think so. It's more complicated than a simple xref, that's true.
However, it allows you to link to a resource across document bounderies
without destroying your validation.


> [...]


Tom