[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: [docbook-tc] DocBook Technical Committee Meeting Agenda: 15 Oct2002
Item #7 on the agenda is instance-based cross reference text. I posted this proposal last month but missed the meeting, so I thought I'd provide it again for your reading pleasure. Bob Stayton 400 Encinal Street Publications Architect Santa Cruz, CA 95060 Technical Publications voice: (831) 427-7796 Caldera International, Inc. fax: (831) 429-1887 email: bobs@caldera.com Date: Mon, 02 Sep 2002 15:17:45 -0700 From: Bob Stayton <bobs@caldera.com> Subject: [docbook-tc] xref style proposal Proposed xref style attributes ================================ When generating cross reference text for xref and olink elements, the DocBook XSL stylesheets use gentext templates that are defined in the locale files in the 'common' subdirectory of the distribution (see 'en.xml' for example). Although the gentext templates can be customized, there is still only one template defined per target element. That means there is only one style of generated text for each element. Authors sometimes need to present a given cross reference differently, depending on the context. For example, a section title might need to be quoted when it appears in the middle of a sentence, but unquoted when standing alone as a list item. Or you may want to make several references using abbreviated syntax such as "See Figures 3.2, 3.5, and 3.6". One could use the xref 'role' attribute to specify a different style for a given xref, but role might be needed for other purposes. This proposal suggests two new attributes for the xref and olink elements that provide some control over generated xref text: style - the name of a prefdefined style template. select - one or more keywords to select components of xref text. Both of these attributes are of type CDATA with no defaults. At the end there is an alternative suggestion of combining these two functions into a single attribute. The 'style' attribute ------------------------ The 'style' attribute is used to select one of a set of predefined style names. For each name there must be a cross reference gentext template defined as part of the stylesheet customization layer. For example: <l:context name="xref"> <l:template name="chapter" style="ChapterTitle" text="“%t”"/> </l:context> Such a style is used as follows: <xref linkend="UsingMouse" style="ChapterTitle"/> If 'UsingMouse' is the id of a chapter element, then the customized template is used since it matches on the element name and the style name. This would produce the chapter title in quotes in the output. If the style name is not defined for the element type that is the target of the cross reference, then the stylesheet falls back to the regular xref template for that element. The style attribute is similar to the feature of named cross reference styles in FrameMaker. Norm has a sample implementation in the DocBook XSL 1.53.0 stylesheets. The 'select' attribute ------------------------ An alternative approach that gives greater control uses the 'select' attribute. It is used to specify one or more components of the cross reference text. The stylesheet algorithm then assembles the cross reference text using those components. The components are selected from a set of keywords that the stylesheet recognizes. [Note: this part of the proposal is derived from suggestions and the sample implmentation in the SourceForge Feature Request #451011 submitted by Erik Hennum.] A simple example might be: <xref linkend="UsingMouse" select="quotedtitle"/> This produces the element's title in quotes. A more complex example might be: <xref linkend="UsingMouse" select="label title"/> This produces chapter number (the label) and the title without quotes. Each assembled text string can have three parts: label, title, and page. The parts always appear in this order if they are included. The page portion can be turned off for output forms like HTML that don't have page numbers. For print output, you can specify that page numbering be turned on globally, and then use the 'nopage' keyword to turn off specific references. These are the proposed 'select' keywords for the three parts: label - label name and number, such as "Figure 3.2" labelname - label name only, such as "Figure" labelnumber - label number only, such as "3.2" title - text of element title quoted title - title text enclosed in quotes page - lowercase page reference, such as "on page 32" Page - Uppercase page reference, such as "Page 32" pageabbrev - Abbreviated page reference, such as "p. 32" pagenumber - Page number only, such as "32" nopage - no page number reference at all The text generated by each of these keywords comes from gentext templates, sometimes directly, sometimes using existing DocBook named XSL templates: labelname - from <l:gentext key="elementname" text="..." /> labelnumber - from the element processed in 'label.markup' mode label - combination of the preceding two, separated by a non-breaking space title - from the element processed in 'title.markup' mode quoted title - same, preceded by <l:dingbat key="startquote" text="..."/> and followed by <l:dingbat key="endquote" text="..."/> page - from new gentext template in xref context. Example: <l:template name="page" text="on page %p" /> Page - from new gentext template in xref context. Example: <l:template name="Page" text="Page %p" /> pageabbrev - from new gentext template in xref contest: Example: <l:template name="pageabbrev" text="(p. %p)" /> pagenumber - just the %p gentext markup Several stylesheet parameters are used to define joining text to "glue" the parts together. The parameters are: xref.label-title.separator - inserted between label and title xref.label-page.separator - inserted between label and page xref.title-page.separator - inserted between title and page A given separator is used only if both of its parts are included in the xref string. Since the order of parts is fixed, only three separators are needed. Once the set of gentext templates and stylesheet parameters are established, a given xref or empty olink can use a 'select' attribute to specify any combination of the three parts as keywords. This design covers the most common variations needed for cross references. It cannot cover all possible styles without becoming overly complex. It also may not work in all languages. In those cases, the 'style' attribute can provide any additional variations in a customization layer. In general, either the 'style' or the 'select' attribute is used. If both are used, the stylesheet policy decides which has precedence. Also, if two keywords are used for the same part (e.g. title and quotedtitle), then the stylesheet determines their precedence. Single attribute alternative ------------------------------- Since the two functions are mutually exclusive, it might be worthwhile combining the two attributes into one 'style' attribute. In that case, the stylesheet needs to specify the syntax it uses to tell whether a given value is a named style or a 'select' string. For example: style="ChapterTitle" style="select: quotedtitle pageabbrev" In this alternative, the minimal change to the DocBook DTD is to add a single 'style' attribute of type CDATA. Another issue is whether the DocBook documentation should prescribe the 'select' syntax, even if it is not part of the DTD itself. The advantage is that interchange of documents is easier if there is a standard syntax. However, there is no way to validate the syntax, so it would just be a convention. -- Bob Stayton 400 Encinal Street Publications Architect Santa Cruz, CA 95060 Technical Publications voice: (831) 427-7796 Caldera International, Inc. fax: (831) 429-1887 email: bobs@caldera.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC