OASIS DocBook TC2

[docbook-tc] xref style proposal

  • 1.  [docbook-tc] xref style proposal

    Posted 09-02-2002 18:18
     MHonArc v2.5.2 -->
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

    docbook-tc message

    [Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


    Subject: [docbook-tc] xref style proposal


    This is for one of my action items.
    
    
    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="&#8220;%t&#8221;"/>
    </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