Loading ...
Sorry, an error occurred while loading the content.

Re: [dita-users] Customising output for a specialization

Expand Messages
  • Eliot Kimber
    Carl, Re @location: by not valid I mean not allowed by the rules of the DITA specialization mechanism as defined in the DITA specification . That is
    Message 1 of 5 , Apr 1, 2013
    • 0 Attachment
      Carl,

      Re @location: by "not valid" I mean "not allowed by the rules of the DITA
      specialization mechanism as defined in the DITA specification". That is
      different from "DTD valid", meaning that as long as the attribute is
      declared in your DTD no XML processor will complain about it. So the Open
      Toolkit won't complain because it is not validating the correctness of
      specializations.

      That is, this is a rule that is validated by inspection. Of course, one
      could write a document analyzer that checked these sorts of rules, but
      usually knowledge of the rules is sufficient to prevent their occurrence :-)

      Re: How to structure the links

      If the requirement is that authors need to be able to put "John 3:16" or
      John 3:16-18" in the content and have it result in a navigable link then I
      think there are a couple of possibilities:

      1. The <ph>-based solution where all of the linking and addressing semantics
      are specific to your specialization. That gives maximum flexibility but also
      puts all the implementation onus on you. But in this case I think you'll
      have to be responsible for the addressing processing in any case because
      this is such a special use case and you want maximum author convenience.

      2. Use keyrefs and provide some facility for generating or inferring the key
      definitions or otherwise making the addressing sufficiently convenient for
      authors. This would almost certainly require authoring tool extension and/or
      content management extension (to do the reference validation and keydef and
      URI generation). It would not be reasonable to expect authors to create the
      keydefs and URIs themselves.

      On the subject of <xref> (and <cite>) in titles, the same proposal for 1.3
      that allows <cite> in title also allows <xref>. However, in 1.2 you can
      simply wrap the <cite> or <xref> in <ph>:

      <title>Topic title<ph><xref>an xref in ph in title</xref></ph></title>

      Not ideal but it is a workaround in 1.2. It is in part the existence of this
      workaround that motivates the 1.3 proposal: the content model restrictions
      on <title> are toothless and unnecessary.

      So what solution? Before I give my opinion, useful to talk a little about
      the value of using <xref> rather than <ph>.

      An essential architectural driver and key selling point for DITA is
      interoperation and interchange of content. This is accomplished by providing
      a common base markup vocabulary with reasonably-well-understood semantics
      and required or default processing rules or suggestions from which all
      conforming DITA documents are derived using a form of controlled extension
      (specialization).

      By using <xref> as the base for elements that are semantically links you
      ensure that other users of your documents will at a minimum understand that
      your <bibleref> element is semantically a link, even if they don't
      understand your addressing mechanism.

      Likewise, by using DITA's built-in addressing mechanism, keyrefs and URIs,
      you get to take advantage of processing that helps understand and manage the
      dependencies among the resources involved.

      For example, a general-purpose DITA-aware component management system or
      online delivery system can provide services around managing links and
      addresses, gathering resources used from a given root map for packing and
      interchange, and so on.

      In that context, there is a lot of potential value in using the DITA-defined
      facilities.

      On the other hand, as you've observed, these facilities may not always be an
      ideal match to your specific requirements.

      Clearly, some sort of compromise will be required.

      In the context of satisfying a specific requirement in the context of a
      specific system or set of users, a one-off solution may be most
      appropriate--you have no requirement for or expectation of wider interchange
      or use or application and you just need to get your immediate problem
      solved.

      But in the context of a standard or quasi-standard like DITA or Publishers,
      wider interchange and application is the point, so the more standards-based
      the solution the better, as long as the result is in fact useful (it is easy
      to create standards-based solutions that are not in fact useful).

      So that leaves us several possible solutions that reflect different weights
      for immediacy and generality:

      1. A <ph> specialization with an optional <bible-location> subelement,
      specialized from <data>, that serves the role of your original @location
      attribute: a place to put the verse reference when the text is not the verse
      reference. If the <bible-location> is not present then the text is taken to
      be a verse reference. This is the easiest solution but lacks any connection
      to DITA-defined linking or addressing facilities or semantics.

      2. An <xref> specialization and direct or indirect (key-based) references to
      verses as explained previously.

      In this case, it would certainly be possible to have your authoring system
      or CMS provide a facility for capturing Bible verse references and then
      construct the appropriate key definitions and resource URLs. But that may be
      more than your authoring community can support--for example, if you have no
      control over how they are authoring or there's no common editing tool or you
      have no budget for implementing such a facility or you're not using a CMS to
      which you could add this functionality.

      I will observe that the <xref> element does not actually require either the
      @href or @keyref attributes, so one could argue that you could use <xref>
      without either and then provide your own addressing scheme (e.g., using our
      proposed <bible-location> specialization of <data>). But I think that that
      analysis is at odds with the intent of the spec in that the entry for <xref>
      says "The target of the cross-reference *is* specified using the href or
      keyref attributes." (Emphasis mine). That is, the use of one of @href or
      @keyref is not optional by the prose of the standard.

      So given all that, I think that option (1) is probably your best short-term
      option, with option (2) something to be considered for additional inclusion
      in DITA for Publishers. I would probably want to define two element types:

      <bibleref> (<ph> specialization) and <biblexref> (<xref> specialization) to
      provide the option of implicit and explicit Bible verse references.

      Cheers,

      E.


      On 3/31/13 8:54 PM, "Carl Cerecke" <carl@...> wrote:

      > Responses inline...
      >
      > On 1 April 2013 04:11, Eliot Kimber <ekimber@...> wrote:
      >>
      >>
      >>
      >>
      >>
      >> I can help with the implementation--some of the publishers I work with are
      >> religious publishers (e.g., The Upper Room) and therefore a general solution
      >> for linking to the Bible in particular, and religious works in general, is
      >> of immediate interest to me. If we can define general-purpose markup and
      >> processing I'd be happy to add it to the DITA for Publishers project.
      >>
      > Great. Thanks for your help.
      >> A couple of things I will mention:
      >>
      > [snip]
      >> 3. You can't legally add new attributes to specific elements via
      >> specialization--you can only add global attributes. So in your example, the
      >> @location attribute could only be a valid DITA specialization if it is
      >> declared as a global attribute. But even in that case, it must specializ
      >> @base or @props. So you must find a different way to capture the value of
      >> your @location attribute. The general implementation solution is to use
      >> <data> or specializations of <data> as subelements of the element you would
      >> otherwise want to put an attribute on.
      >>
      > The OT didn't complain when processing the @location attribute, so I figured
      > it was valid. I didn't choose <data> because, by default, it doesn't show
      > output.
      >
      >> 4. The name "bibref" confused as "bibliographic ref" rather than "Bible
      >> ref", which is what I think you mean. Would suggest using <bibleref> to
      >> avoid ambiguity.
      >>
      > Yes, <bibleref> is better.
      >> Given that, I see the following possible solutions:
      >>
      >> 1. Make <bibref> specialize from <xref> and use @keyref where the key
      >> definition then connects to the specific location, either directly or
      >> indirectly:
      >>
      >> <bibref keyref="bible-john-3:16">verse 16</bibref>
      >>
      >> The keydef could be:
      >>
      >> <keydef keys="bible-john-3:16"
      >> href="http://www.biblestudytools.com/john/3-16.html"
      >> format="html"
      >> scope="external"
      >> />
      >>
      >> Here I've chosen the key name to include "bible-" just to make it clearer to
      >> a human that this is a bible reference--a naming convention that makes the
      >> mapping from the generic verse reference to the key clear and consistent. If
      >> you needed to indicate the Bible version, could include that in the key as
      >> well, e.g. "bible-kjv-john-3:16" for a reference to the King James version.
      >>
      >> Or you could use a URN that serves as a query that your custom code will
      >> resolve dynamically, as you are trying to do now for your current <bibref>
      >> element:
      >>
      >> <keydef keys="bible-john-3:16"
      >> href="urn:free.org.nz:bibref?location=john%203:16"
      >> format="html"
      >> scope="external"
      >> />
      >>
      >> By definition, a URN cannot be directly resolved--it has to go through some
      >> sort of resolver, which in this case would be your custom output generation
      >> code or code running in the browser itself.
      >>
      >> Which of these key-to-resource approaches you use depends on the degree of
      >> dynamism you require. With the first approach you could have different sets
      >> of key definitions that bind to different Bible versions or sources. In the
      >> second approach, you could do that binding dynamically at publication time
      >> or in the browser at reading time given some custom Javascript code.
      >>
      > This could work. But the keydefs would have to be automatically generated from
      > the keyrefs.
      > A bible reference can refer to a range of verses (John 3:16-18), not just a
      > single verse, so while it might be practical to enumerate all 31k verses, it's
      > not practical to enumerate all possible ranges.
      > What would be ideal is the ability for the process of resolving keyrefs to be
      > handled by a program, instead of (or as well as) a static list of keydefs.
      > Also, most of the time I wouldn't want to manually specify the keyref, because
      > the text *is* the reference.
      > Unfortunately, I'd also like to have bible references in <title>s, but xref is
      > not allowed in title.
      >
      >> 2. To (1) add a subelement specialized from <data> that holds the value of
      >> your current @location attribute:
      >>
      >> <bibref keyref="bible-john-3:16">
      >> <bible-location>John 3:16</bible-location>version 16</bibref>
      >>
      >> Note that the default behavior for <data> is to be suppressed in the output,
      >> so you would not see the "John 3:16" text in most renderings by default--but
      >> you could, for example, extend the HTML processing to set it as a tool tip
      >> for the resulting link or add it as parenthetical text or whatever you want.
      >>
      >> 3. Don't use <xref> at all, but a specialization of <ph> plus the
      >> <bible-location> from (2). This is the functional equivalent of what you
      >> have now, meaning all the linking semantics are provided by your custom
      >> code:
      >>
      >> <bibref><bible-location>John 3:16</bible-location>verse 16</bible-location>.
      >>
      > I don't like these two options much. To me it feels like unnecessary
      > repetition. Most of the time the text of the reference is the reference
      > itself; the remaining times the text is something like "verse 16", where the
      > context provides the book and chapter. Ideally these would look something
      > like:
      > <bibleref>John 3:16</bibleref> and <bibleref location="John 3:16">verse
      > 16</bibleref>
      >
      >> I would be interested to know if there are any standards or quasi-standards
      >> for computer-encoding of Bible references--seems like there should be and
      >> taking advantage of that in the content would be important.
      >>
      > Not really.
      > There's http://semanticbible.com/bibleref/bibleref-specification.html but I
      > don't know how widely it's used. Also, because it allows multiple ranges, it's
      > not really suitable for hyperlinking.
      > I use the simple:
      > Book<space>Chapter:Verse[-[Chapter:]Verse]
      > If the text of the document has a complicated sequence of references such as
      > 2 Corinthians 5:14-15, 18, 1 John 2:6, 4:10
      > This would get represented in DITA as four biblerefs: "2 Corinthians 5:14-15",
      > "2 Corinthians 5:18", "1 John 2:6", "1 John 4:10". (Also note that there is
      > an ambiguity around 1 John - should the 1 be a verse reference of 2
      > Corinthians, and then the next two refer to the book of John, or should it be
      > the book "1 John" - but that's a problem for the author )
      >
      > So, I guess my choices are between:
      > a. Use the built-in linking mechanism of DITA with the <xref> tag: I get
      > linking in different outputs "for free", but I can't put links in titles, and
      > the keyref must be explicit.
      > b. Use a specialization of <ph>: I have to write a transform for each output
      > format, I can put links in titles, and the bible reference can be inferred
      > from the text if not explicitly supplied
      > c. Some combination of 1 and 2, but without the combined benefits of both.
      >
      > Cheers,
      > Carl.
      >> Cheers,
      >>
      >> Eliot
      >>
      >>
      >>
      >> On 3/30/13 11:50 PM, "Carl Cerecke" <carl@...
      >> <mailto:carl%40free.org.nz> > wrote:
      >>
      >>>>
      >>>>
      >>>> I have a specialization of ph which I use for bible verse references -
      >>> either
      >>>> a single verse, or a range of verses. I use it like:
      >>>> <bibref location="John 3:16">verse 16</bibref>, or <bibref>John
      >>> 3:16</bibref>.
      >>>>
      >>>> Now I want to add a hyperlink in the output (pdf/xhtml/whatever) to an
      >>> online
      >>>> bible, but I'm just not sure how to go about doing this in DITA. (I'm using
      >>>> the OT, version 1.7.4). I'm not sure even where to start. I know I'll need
      >>>> some way of transforming the reference to a URL. I can do that easy enough
      >>>> using python (it's slightly complicated by the fact that I want to be able
      >>>> >> to
      >>>> target different websites, which are likely to have different verse
      >>> reference
      >>>> APIs). I don't know XSLT (but will learn it if I really have to).
      >>>>
      >>>> Originally bibref was a specialization of cite, but cite isn't allowed in
      >>>> titles.
      >>>>
      >>>> I'm pretty sure questions similar to this must have already been asked and
      >>>> answered, but I couldn't find anything. Sorry if there's an obvious website
      >>>> explaining what I want to do that I missed.
      >>>>
      >>>> This question would be a good one for dita.stackexchange when it gets up >>
      >>>> and
      >>>> running (I've got my 200 points on another stackexchange site. I'm waiting
      >>>> >> for
      >>>> the rest of you... C'mon; It'll be great!)
      >>>>
      >>>> Any help appreciated,
      >>>> Thanks,
      >>>> Carl
      >>>>
      >>>>
      >>>>
      >>
      >> --
      >> Eliot Kimber
      >> Senior Solutions Architect, RSI Content Solutions
      >> "Bringing Strategy, Content, and Technology Together"
      >> Main: 512.554.9368
      >> www.rsicms.com <http://www.rsicms.com>
      >> www.rsuitecms.com <http://www.rsuitecms.com>
      >> Book: DITA For Practitioners, from XML Press,
      >> http://xmlpress.net/publications/dita/practitioners-1/
      >>
      >>
      >>
      >>
      >>
      >
      >
      >
      >

      --
      Eliot Kimber
      Senior Solutions Architect, RSI Content Solutions
      "Bringing Strategy, Content, and Technology Together"
      Main: 512.554.9368
      www.rsicms.com
      www.rsuitecms.com
      Book: DITA For Practitioners, from XML Press,
      http://xmlpress.net/publications/dita/practitioners-1/
    Your message has been successfully submitted and would be delivered to recipients shortly.