OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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


Subject: RE: [dita] Updated: Stage 2 proposal - bookmap update.


Ok. Thanks.  I’ll replace the term placeholder to a container.

 

Éric Sirois

DITA Toolsmith

 

IXIASOFT 

825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1

tel  + 1 514 279-4942  /  toll free + 1 877 279-4942

mobile + 1 647 462-3620

eric.sirois@ixiasoft.com / www.ixiasoft.com 

 

http://captmondo.com/IXIASOFT/ixiasoft-logo-small.png

 

From: Eliot Kimber <ekimber@contrext.com>
Sent: March 26, 2018 1:49 PM
To: Éric Sirois <eric.sirois@ixiasoft.com>; dita@lists.oasis-open.org
Subject: Re: [dita] Updated: Stage 2 proposal - bookmap update.

 

The proposal says “mapresources” is a “placeholder” but it doesn’t seem to be a placeholder, rather it’s just a container for resource-only topicrefs that is perfectly usable as is.

 

“Placeholder” implies it’s expected to be replaced with something else, but I don’t see a reason to need anything other than “mapresources” itself.

 

I like to define the topicref type “keydefs” in my map specializations and I could easily use “mapresources” as the specialization base but I don’t see that that would be required by this proposal. Given the existence of “mapresources” as a TC-provided domain I would probably just use that as is.

 

Cheers,

 

E.

--

Eliot Kimber

 

 

From: <dita@lists.oasis-open.org> on behalf of Eric Sirois <eric.sirois@ixiasoft.com>
Date: Monday, March 26, 2018 at 12:32 PM
To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: [dita] Updated: Stage 2 proposal - bookmap update.

 

Here is the updated bookmap proposal based on the discussion with the TC.

 

DITA 2.0 proposed feature #29

The goal of the redesign is to remediate problems but avoid breaking backward compatibility.

Modify bookmap design

Proposal version

1.1

Completion date

TBD

Champion of the proposal

Eric Sirois

Initial Suggestion

https://lists.oasis-open.org/archives/dita/201703/msg00019.html

Links to minutes where this proposal was discussed at stage 1 and moved to stage 2

https://lists.oasis-open.org/archives/dita/201705/msg00091.html

GitHub Issue

https://github.com/oasis-tcs/dita/issues/29

Original requirement or use case

Overall the bookmap DTD has not been updated as part general DITA releases for a couple releases. It is missing some convenient key features that were added as part of DITA 1.2 and 1.3. The proposal will make it easier to make use of <ditavalref> at the root level and make it easier to create and maintain keydefs.

Use cases

  1. A writer wants to create a keydefs for a map in a convenient location in the map.

The current version of the DITA Bookmap does allow keydefs to be created, but you need to do it inside one of the main top level elements. like <frontmatter>. But it's not convenient because it's buried in an unrelated element.

  1. A writer wants to specify a ditaval used for the whole map via a <ditavalref>.

The current version of the DITA Bookmap does not allow <ditavalref> as an immediate child of <bookmap>. Creating them inside one of the children of <bookmap>, then the <ditavalref> only applies to the children of that element.

Proposed solution

The purpose of the proposal is to add some enhancements to bookmap, with a minimal amount of impact at the processing end of the pipeline but will make things a bit easier for the end user.

  • Add <ditavalref> before <frontmatter>
  • Create a <mapresources> as an element that will allow users to reference elements that are specializations of <topicref>.
  • Create a domain specialization to group <keydefs> prior to <frontmatter>.

Benefits

  • Authors will benefit from the more intuitive use of keydefs.
  • Information architects/developers will benefit being able to add a specialization for custom processing of bookmaps.
  • Information architects will be able to use the same bookmap for multiple outputs using a different set of conditions

Technical requirements

This change is adding two elements, that already supported in DITA 1.3, to the root content model of the bookmap DTD and as such, will have essentially no technical impact.

Provide a detailed description of how the solution will work. Be sure to include the following details:

DTD and Schema modifications.

New domain

·         Map resources

o    Add a domain specializations that will allow the definition of a wrapper element to define <keydefs> in a <bookmap> or other strictly constrained publication maps. This domain is based on <mapresources>

New element

·         <mapresources>

o    This element is a placeholder that would allow specializations of <topicref> to be available in a bookmap. The element is defined a s resource-only element.

o    The element is optional after the <ditavalref>.

·         <ditavalref>

o    This is an existing element that is available in the base <map>. We are simply making it available in the top level portion of <bookmap>

o    The element is optional after the <bookmeta>.

Processing impact

None. <ditavalref> is already supported features of DITA 1.3. And <mapresources> is a specialization of topicref as a resource-only element.

Overall usability

Current DITA users and current document type shells will be unaffected. Usability of authoring will ultimately be improved due to better management of keydefs and use of ditavalrefs in the bookmap.

Costs

  • The main bookmap files need to be updated with the addition of new domain files to support the solution for this proposal.
  • A new topic for documenting the domain and the placeholder element. As well as an update to the bookmap topic.
  • Since we are adding elements that are already supported in DITA 1.3, there is no impact to processors and XML tools.

Examples

Sample usage in a bookmap:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA 2.0 BookMap//EN" "bookmap.dtd">
<bookmap>
    <booktitle>
        <mainbooktitle>Test</mainbooktitle>
    </booktitle>
    <ditavalref href="">
    <mapresources>
        <keydef keys="test" href="">
    </mapresources>
</bookmap>

Element definition in the bookmap DTD:

 
     
     <!ENTITY % bookmap.content
     "((%title; | %booktitle;)?,
     (%bookmeta;)?,
     (%ditavalref;)*,
     (%mapresources;)?,
     (%frontmatter;)?,
     (%chapter;)*,
     (%part;)*,
     ((%appendices;)? |
     (%appendix;)*),
     (%backmatter;)?,
     (%reltable;)*)"
     >
    
    

Element override in the bookmap shell:

<!ENTITY % mapresources  "%mapresources-d-mapresources;
 ">

Domain definition:

<!ENTITY % mapresources
                       "mapresources"                               >
 
 
<!-- ============================================================= -->
<!--                    ELEMENT DECLARATIONS                       -->
<!-- ============================================================= -->
 
 
<!ENTITY % mapresources.content
                       "(%topicref;)*"                         
 
<!ENTITY % mapresources.attributes
              "outputclass
                          CDATA
                                    #IMPLIED
               processing-role
                          CDATA
                                    'resource-only'
               %univ-atts;"
 
<!ELEMENT  mapresources %bookmapkeydefs.content;>
<!ATTLIST  mapresources %bookmapkeydefs.attributes;>
 
<!ATTLIST  mapresources %global-atts;  class CDATA "+ map/topicref  mapresources-d/bookmapkeydefs ">

Domain entity definition:

 
    <!ENTITY % mapresources-d-mapresources
    "mapresources"
    >
        
    <!ENTITY mapresources-d-att
    "(map mapresources-d)"
    >

 

 

Éric Sirois

DITA Toolsmith

 

IXIASOFT 

825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1

tel  + 1 514 279-4942  /  toll free + 1 877 279-4942

mobile + 1 647 462-3620

eric.sirois@ixiasoft.com / www.ixiasoft.com 

 

http://captmondo.com/IXIASOFT/ixiasoft-logo-small.png

 



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