DITA Bootstrap Specialization - How to document it?

[jason-fox]

I have a pending pull request which allows for specialization of the bootstrap elements, and therefore simplifies the resultant dita - for example a card:

<bodydiv outputclass="row">
  <bodydiv outputclass="col">
    <section outputclass="card w-50">
      <title outputclass="h5">Card Title</title>
      <image outputclass="card-img-top" href="..." />
      <p>Some quick example text to build on the card title and make up the bulk of the card’s content.</p>
      <xref outputclass="btn-primary" href="#">Go Somewhere</xref>
    </section>
  </bodydiv>
</bodydiv>

Becomes

<grid-row>
  <grid-col>
    <card>
      <title>Card Title</title>
      <image href="..."/>
      <p>Some quick example text to build on the card title and make up the bulk of the card’s content.</p>
      <button href="#" color="primary">Go Somewhere</button>
    </card>
  </grid-col>
</grid-row>

Now this change is only possible if the correct DOCTYPE is set

- <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
+ <!DOCTYPE topic PUBLIC "-//Infotexture//DTD DITA Bootstrap Topic//EN" "bootstrap-topic.dtd">

You can see fully updated examples here for the following specializations:

<!ENTITY % accordion "accordion">
<!ENTITY % accordion-item "accordion-item">
<!ENTITY % badge "badge">
<!ENTITY % button "button">
<!ENTITY % button-group "button-group">
<!ENTITY % card "card">
<!ENTITY % carousel "carousel">
<!ENTITY % carousel-item "carousel-item">
<!ENTITY % collapse "collapse">
<!ENTITY % grid-row "grid-row">
<!ENTITY % grid-col "grid-col">
<!ENTITY % icon "icon">
<!ENTITY % list-group "list-group">
<!ENTITY % offcanvas "offcanvas">
<!ENTITY % pagination "pagination">
<!ENTITY % popover "popover">
<!ENTITY % picture "picture">
<!ENTITY % tabbed-dialog "tabbed-dialog">
<!ENTITY % thumbnail "thumbnail">
<!ENTITY % tooltip "tooltip">

Now the question is how to best integrate this - the existing mechanism using outputclass remains fully supported

In your experience, should specialization be part of the current plugin or split into a separate plugin? e.g. dita-bootstrap.specialization - I can't see the downside of including the catalog unless someone is likely to be defining specializations of their own.

How ideally should this be documented? The new syntax is semantic and is much simpler, but how should compatibility with outputclass be shown as well?

Better to discuss this before raising the PR.

[jason-fox]

I have also updated the dita-bootstrap.extension in the same fashion, both specializations are compatible.

[infotexture]

should specialization be part of the current plugin or split into a separate plugin?

That's a very good question. 🤔

I'm leaning toward the latter, as it could be confusing and hard to maintain if we have to show 2 examples (for output class & specializations) for every custom component.

But I see you've since submitted #292, so we can continue the conversation there (and in #293).

[jason-fox]

Now we have the following set-up:

• https://infotexture.github.io/dita-bootstrap/ - uses @outputclass

• https://dita-bootstrap.github.io/dita-bootstrap.specialization/ - uses specialiization, but displays both.

• https://infotexture.github.io/dita-bootstrap.extension/ - uses @outputclass

• https://dita-bootstrap.github.io/dita-bootstrap.extension.specialization/ - uses specialiization, but displays both.

This means that the current infotexture location is still documenting the current release.