Well, the Guidelines are in a more or less constant state of revision, so we will certainly consider these revisions. However, as others have pointed out, they seem to be labouring under some misapprehension about the semantics of the <ptr> element. A <ptr> marks a point in the source where there is a reference to something else: that's all it does. The value of the <at> target attribute identifies the something else: that's all that it does.  Your processing application has to decide for itself how to render the pointer since pointers (unlike words) don't have any obvious output format: in the case of the Guidelines we render the pointer elements with links and do some gymnastics to pick up an appropriate form of words to represent them, along with some forms of magic appropriate to the output medium (if you consider HTML active links to be magic), but we could do it in other ways. Note that if we wanted to constrain the words generated for the output representation of a link we could do so using a different element: <ref>. We don't do this in the Guidelines because the form we want generated includes section numbering which we'd rather not have to worry about, but if we were encoded a text in which we wanted to conserve the words used to indicate a cross reference, things would be different. 

Thus Aristotle in the third chapter of his Poetics saith...

might plausibly be encoded as 

Thus Aristotle<ref target='xxx'> in the third chapter of his Poetics</ref> saith...

 where xxx is a URL taking me off to said third chapter. 

Incidentally, this use of <ptr> in the Guidelines is by no means the only case where output text is generated from special purpose markup in the source code. For consistency, the descriptions of elements and attributes which appear throughout the text as well as in the reference documentation are represented by means of a similar pointing construct (a <specDesc>) in the P5 source. This invariably bewilders people new to the editing of the Guidelines, but us old hands find it as intuitive and natural as driving on the left side of the road....

Lou

If the guidelines do get reviewed,

 I suggest the examples of <ptr> throughout the guidelines be checked.

9.3.4 encodes 'more at pneumatic' as 'more at <ptr target="#pneumatic"/>'.

3.6 encodes 'but the specific form of Figure 2.2 was first studied extensively by Chomsky' as 'but the specific form of <ptr target="#fig22"/> was first studied extensively by Chomsky'.

14.2 has 'As we have seen in equation <ptr target="#f12"/>'

16.2.5.2 has 'The example in section <ptr target="#SABN"/> is taken.' And 22.1.2 has 'elements discussed in section <ptr target="#TDcrystals"/>'.

None of these seem in keeping with the spirit of <ptr>. Their removal would destroy the integrity of the text.

-- JPM



On 4/1/2012 4:25 PM, Martin Holmes wrote:

Hi there,

Doesn't part of this confusion arise out of looking at the source code of the Guidelines itself? That's a non-typical usage scenario, because there is no original source which is being transcribed in the Guidelines; the Guidelines are born-digital, and the encoding conventions used in the Guidelines map directly onto known templates in Sebastian's output XSLT. <ptr/> in the context of the Guidelines is used in a conventional way that we understand to mean "process this into a link to the title of the section being pointed at, and link that title to the section itself" (in the case of the HTML output, at least).

But if you're encoding an existing source text, then there's no requirement that your use of <ptr>, or especially your subsequent processing of that use, should follow what the Guidelines happens to do.

I agree, though, that it might be better to have, as the primary example of <ptr>, something which is more in line with what most people do when encoding existing texts than the XML of the Guidelines.

Cheers,
Martin

On 12-04-01 04:07 PM, John P. McCaskey wrote:

On 4/1/2012 3:36 PM, Daniel O'Donnell wrote:

I wonder if you don't need to see it less from the point of view of
the output and more from the point of view of the encoding

I am indeed looking at this from the output side. I'm writing a
stylesheet that I hope will have some general usability.

But there does seem to be a semantic ambiguity here. Can <at> target of
<ptr>  contain material integral to the text?

. . . In that case using ptr reduces the chances for error, since you
only type the url once. . . . That's the main way we use it in the
lethbridge journal incubator: email addresses and hyperlinks where the
URL is the link text.

Does this say that if you have a source that includes a web address
that, for economy, you'd replace that web address with a<ptr>  to it? If
so, then you really are failing to capture what is in the source, if the
<at> target of a<ptr>  is not presumed to be an integral part of the text. No?

It seems to me the guidance should be that the <at> target of a<ptr>  is not
part of the presentation text. If it should be, either because it was
there in the source or because the encoder wants to add it in, then
<ref>  should be used instead. If the encoder thinks it would be a
misrepresentation for a formatter downstream to replace the<ptr>  with
just a CLICK ME! icon, the encoder should not use<ptr>.

-- JPM