Aligning Documentation - Thoughts on how to proceed?

[jason-fox]

There are currently five different variations of the sample document text and look-and-feel used throughout the dita-bootstrap repositories:

Name	Header Color	Custom CSS overrides.	Notes	Build
dita-bootstrap.html local	sample header is primary blue	None. codeph color is a calculated pink	@outputclass first	initiated on terminal by user
dita-bootstrap.html CI	CI header is primary blue	Overrides codeph color to fixed grey	@outputclass first	action on changes to develop branch
dita-bootstrap.specialization local	None defined	None. codeph color is a calculated pink	dita specialization first	initiated on terminal by user
dita-bootstrap.specialization CI	CI header is secondary grey	None. codeph color is a calculated pink	dita specialization first	action on changes to develop branch
dita-bootstrap.github.io CI	CI header is primary blue	Overrides codeph color to fixed grey	TBD	action on manual trigger

Note

• codeph defaults to pink with a shading based on a combination of bootstrap red, green and blue

• cmdname and parmname default to prussian blue with a shading based on bootstrap primary

• xmlatt, xmlelement, xmlnsname, xmlpi default to violet

• syntaxdiagram default to maroon

For the Bootswatch themes with a dark background these elements are given fixed high contrast colors.
The high contrast colors are local generation only and do are not displayed on gh-pages since the theme picker
doesn't load the additional fixed color CSS file.

Questions

dita-bootstrap.github.io is to be the promoted website URL.

1. should dita-bootstrap.specialization and dita-bootstrap.html both share the same "secondary" header style to keep dita-bootstrap.github.io unique as the default color scheme?
2. should codeph color on dita-bootstrap.specialization and dita-bootstrap.html both use the standard codeph Bootstrap color?
3. Should dita-bootstrap.github.io build from dita-bootstrap.html sample or dita-bootstrap.specialization sample?
4. Should dita-bootstrap.github.io trigger a build on upstream changes in its source *.dita ?
5. Should there be a divergence in the texts of dita-bootstrap.html and dita-bootstrap.specialization such as making specialization a mandatory plugin?

At the moment the differences between dita-bootstrap.html or dita-bootstrap.specialization texts is the order of the tabs - obviously one is using vanilla DITA syntax for the scaffolding and the other is using DITA specialization and the text on index.dita which mentions the install of specialization and PDF plugins.

[jason-fox]

My opinion here is that CI dita-bootstrap.html and dita-bootstrap.specialization are canary builds and should always show bleeding edge development, therefore both of the rendered gh-pages should use the "experimental" secondary header. The rest of the output should display default bootstrap colors and the codeph override should be removed

CI dita-bootstrap.github.io should display a stable build, use the default primary header and can continue to override codeph if desired.

[jason-fox]

On text divergence, I guess dita-bootstrap.html needs a new entry under Additional Plug‑ins and an alteration in index.dita to link to the new page.

An open question for dita-bootstrap.github.io is whether to place @outputclass or specialization as the first open tab.

Personally I would go with displaying the specialization since the syntax is simpler.

A counter argument is that raw *.dita has been the default throughout 5.3.x. Maybe stick with raw *.dita for 5.3.x for now and switch to specialization first as part of a later 6.3.x release? Bootstrap 6 is available in early alpha.