You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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.
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.
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:
ifdefPROFOSASSEMBLYSTRINGS := $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
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.
$ 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.
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.
Check if the module is contained in the result file:
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:
This is something the author needs to do
assemble.xsl
stylesheet.This is where daps comes into play.
Something that I (Toms) need to do.Already integrated in OBS SR#1126556Filter 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"
):Exclude a module only, when a specific attribute is set (here
os="windows"
):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.
Likewise with other profiling attributes. Make sure to separate each of them with semicolon.
Parameters to be passed to the
assemble.xsl
stylesheetThe new
assemble.xsl
stylesheet provides the XSLT parametereffectivity.PROFILE_ATTRIBUTE
whereasPROFILE_ATTRIBUTE
can be any of the usual profiling attributes likearch
,os
etc.To filter the assembly for those with
os="linux"
, pass the following parameter to the XSLT processor:Probably somewhere in
make/assembly2db.mk
you need to add: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:
docbook5-xsl-stylesheets
package from one of the snapshot release?docbook5-xsl-stylesheets
package and integrate only this change?assemble.xsl
andeffectivity.xsl
) in daps?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
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.
Clone
https://github.com/docbook/xslt10-stylesheets.git
.Call the stylesheet with
effectivity.os=linux
:Call the stylesheet with
effectivity.os=macos
:Check if the module is contained in the result file:
The text was updated successfully, but these errors were encountered: