[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK-APPS: xref style proposal
This is a proposal for enabling individual xref elements to be presented differently from the default. It is under consideration by the DocBook Technical Committee, and I thought it would be good to get feedback from the docbook-apps mailing list. 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" rather than "See Figure 3.2, Figure 3.5, and Figure 3.6". Xref style choices could be put into processing instructions, but PIs are subject to being lost in multiple transformations. An attribute to the xref element seems the best choice for this additional information, similar to hints provided in attributes for presentation of graphics. 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: xrefstyle - 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 of this mail there is an alternative suggestion of combining these two functions into a single attribute. The 'xrefstyle' attribute ------------------------ The 'xrefstyle' 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" xrefstyle="ChapterTitle" text="“%t”"/> </l:context> Such a style is used as follows: <xref linkend="UsingMouse" xrefstyle="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 xrefstyle name. This would produce the chapter title in quotes in the output. If the xrefstyle 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 xrefstyle attribute is similar to the feature of named cross reference styles in FrameMaker. Norm has a sample implementation starting in the DocBook XSL 1.53.0 stylesheets. The 'select' attribute ------------------------ An alternative approach 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. In this proposal, each assembled text string could 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 'xrefstyle' attribute can provide any additional variations in a customization layer. The 'select' attribute is less flexible than the 'xrefstyle' attribute, which can be customized to any form. But the 'select' attribute has one advantage: it does not require any customization of the stylesheets to be used. The algorithm is built in. In general, either the 'xrefstyle' 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 'xrefstyle' 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: xrefstyle="ChapterTitle" xrefstyle="select: quotedtitle pageabbrev" In this alternative, the minimal change to the DocBook DTD is to add a single 'xrefstyle' attribute of type CDATA to xref and olink. 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. So I don't think the DTD should prescribe values for the attribute. Comments? -- Bob Stayton 400 Encinal Street Publications Architect Santa Cruz, CA 95060 Technical Publications voice: (831) 427-7796 The SCO Group fax: (831) 429-1887 email: bobs@sco.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC