Support profiling/filtering of modules in assembly files

[tomschr]

Problem description

At the moment, our assembly files are "simple": they contain one structure and there is not much variety (except the one assembly file from Tomas about ALP).

I expect this will not be the case forever. Soon we will face the use case that two or more deliverables share a lot of modules, but deviate in smaller parts. Similar what we do for SLE.

We could create either a) different assembly files or b) one assembly file with two or more structures. Both solution duplicate the content. As we know from the "don't repeat yourself" mantra, this is error-prone and a waste of space.

At the moment, this is not possible to cover such use case.

@fsundermeyer: Maybe something to be discussed in our tools meeting.

Expected behavior

A much better way would be to write one structure in an assembly file, mark up the differences and delegate the rest to the stylesheet. Same as we do with SLE and our different variants.

When the prerequisites are fullfiled, daps would pass the necessary parameters to the assemble.xsl stylesheet which does the filter procedure.

If we want to support that, these are the tasks we need:

• [x] Filter element for a module that needs to be included or excluded. This is something the author needs to do
• [ ] Parameters to be passed to the assemble.xsl stylesheet. This is where daps comes into play.
• [x] Package modification ~Something that I (Toms) need to do.~ Already integrated in OBS SR#1126556

Filter elements

The assembly schema allows two additional elements in <module> which we haven't used yet:

• <filterin/>: Elements with effectivity attributes matching this element are allowed.
• <filterout/>: Elements with effectivity attributes matching this element are suppressed.

"Effectivity attributes" are just a different name what we call "profiling attributes".

With these two elements, let's consider different scenarios with the os attribute:

• Include a module only, when a specific attribute is set (here os="linux"):

  <module resourceref="..." renderas="...">
    <filterin os="linux"/>
  </module>
  

• Exclude a module only, when a specific attribute is set (here os="windows"):

  <module resourceref="..." renderas="...">
    <filterout os="windows"/>
  </module>
  

• Both (order is unimportant). This one is a bit tricky and I'm not sure if this is useful for us. I'd say, this should be avoided.

  <module resourceref="..." renderas="...">
    <filterin os="linux;mac"/>
    <filterout os="windows"/>
  </module>
  

Likewise with other profiling attributes. Make sure to separate each of them with semicolon.

Parameters to be passed to the assemble.xsl stylesheet

The new assemble.xsl stylesheet provides the XSLT parameter effectivity.PROFILE_ATTRIBUTE whereas PROFILE_ATTRIBUTE can be any of the usual profiling attributes like arch, os etc.

To filter the assembly for those with os="linux", pass the following parameter to the XSLT processor:

$ xsltproc --stringparam effectivity.os linux ...

Probably somewhere in make/assembly2db.mk you need to add:

ifdef PROFOS
  ASSEMBLYSTRINGS := $ASSEMBLYSTRINGS --stringparam "effectivity.os=$(PROFOS)"
endif
# similar with other profiling attributes that we support

Package modification

Currently, there is no new docbook5-xsl-stylesheets release in sight. There are "snapshot" releases available, but I'm not sure how much we can trust them.

At the moment, this feature is currently only available in the GH repo. I see the following solutions:

• Create a new release for the docbook5-xsl-stylesheets package from one of the snapshot release?
• Patch the docbook5-xsl-stylesheets package and integrate only this change?
• Integrate the two stylesheets (assemble.xsl and effectivity.xsl) in daps?
• Something else?

Maybe something for the tools meeting to discuss?

Benefits and risks

Used wisely, this can help to reduce the number of assembly files in the articles/ directory for some deliverables. The benefits of this filtering feature is the same as we do when profiling SLE structures.

On the other side, it makes assembly files more complex. Writers have to choose carefully when to use this feature and when not. As with SLE, it's always a trade-off.

Steps to reproduce problem

1. In an assembly file, select a module: a. Add xml:id="foo" in the <module> element. This is used to identify it in the result file. b. Add a <filterin os="linux"/>. c. Save the file.

2. Clone https://github.com/docbook/xslt10-stylesheets.git.

3. Call the stylesheet with effectivity.os=linux:

   $ xsltproc --stringparam effectivity.os linux --output /tmp/result-linux.xml \
       xsl/assembly/assemble.xsl ASSEMBLY_FILE
   INFO: including a module or structure because the os attribute is set to linux.
   

4. Call the stylesheet with effectivity.os=macos:

   $ xsltproc --stringparam effectivity.os macos --output /tmp/result-macos.xml \
       xsl/assembly/assemble.xsl ASSEMBLY_FILE
   INFO: No modules or structures matched attributes for inclusion.
   

5. Check if the module is contained in the result file:

   $ grep foo /tmp/result-linux.xml && echo "yes" || echo "no"
   yes
   $ grep foo /tmp/result-macos.xml && echo "yes" || echo "no"
   no