Bug #4131
openosmo-gsm-manuals: Use leveloffset attribute on common documents
0%
Description
Right now, all documents under osmo-gsm-manuals.git/commons/ start with title level 1 (==). However, if one wishes to add a document with level 2 (===) so it can also be included in other repository document, it will make osmo-gsm-manuals.git "make check" fail due to osmo-gsm-manuals/tests/Makefile.am:22:
echo "include::$${chapter}[]" >> $@; \
Which includes stuff under a test document with level 0 (=). If a document with level different than 1 (==) is added, then it will fail on some versions (like jenkins):
"asciidoc: WARNING: mgcp_extension_osmux.adoc: line 2: section title out of sequence: expected level 1, got level 2"
See for instance commit osmo-gsm-manuals.git 061cca4d7345bc4f496324d0b4d30bc51e1f8d23, which had to be fixed up later.
The solution here is to use "leveloffset" attribute. To make our life easier in the future, we need to move all documents under common/ to start with level 0 (=), and then use "leveloffset" on all includes in all other repositories using them. This way same document can easily be added on different levels on different documents.
Important! It seems this syntax doesn't work for me:
include::chapter2.adoc[leveloffset=+1]
However, this does and it's basically the same:
:leveloffset: 1 include::chapter1.adoc[] :leveloffset: 0
Related information:
https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/include-directive.adoc
https://mrhaki.blogspot.com/2016/09/awesome-asciidoctor-change-level-offset.html
http://asciidoc.org/userguide.txt
Related issues
Updated by pespin over 4 years ago
Submitted a quick workaround for commit 061cca4d7345bc4f496324d0b4d30bc51e1f8d23 for now:
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/14967 mgcp_extension_osmux.adoc: Workaround make check failures
Updated by osmith over 4 years ago
- Status changed from New to In Progress
- Assignee set to osmith
In IRC you wrote on Friday:
I don't get the error in https://build.opensuse.org/package/live_build_log/network:osmocom:nightly/osmo-gsm-manuals/Debian_9.0/aarch64
"asciidoc: WARNING: mgcp_extension_osmux.adoc: line 2: section title out of sequence: expected level 1, got level 2"
As I understood, the package was building fine for all other arches, except for aarch64 on Friday. Clicking on the link again, it shows that the build goes through for aarch64 now.
Strangely, the error you reported shows up here now (i586 only, works for x86_64?!):
The only other failure for osmo-gsm-manuals is on Debian_Testing x86_64, and it seems to be a completely unrelated error. I can't really find the exact cause of the error, all it says is, that a2x fails:
[ 318s] ERROR: a2x failed! Running asciidoc to get verbose errors... ... [ 342s] asciidoc: cell-broadcast.adoc: line 46: reading: /usr/src/packages/BUILD/common/chapters/osmocom-cbs.msc [ 342s] asciidoc: cell-broadcast.adoc: line 45: evaluating: {counter2:target-number} [ 342s] asciidoc: cell-broadcast.adoc: line 45: evaluating: {set2:target:test-usermanual__53.png} [ 342s] asciidoc: osmocom-cbs.msc: line 12: filtering: "/usr/bin/python2" "./build/filter-wrapper.py" mscgen -o "/usr/src/packages/BUILD/tests/test-usermanual__53.png" -Tpng - [ 343s] asciidoc: include: /usr/src/packages/BUILD/common/chapters/port_numbers.adoc [ 343s] asciidoc: test-usermanual.adoc: line 31: reading: /usr/src/packages/BUILD/common/chapters/port_numbers.adoc [ 343s] asciidoc: port_numbers.adoc: line 50: evaluating: {counter:table-number} [ 343s] asciidoc: include: /usr/src/packages/BUILD/common/chapters/bts.adoc [ 343s] asciidoc: test-usermanual.adoc: line 32: reading: /usr/src/packages/BUILD/common/chapters/bts.adoc [ 343s] asciidoc: bts.adoc: line 305: evaluating: {counter:table-number} [ 343s] make[3]: *** [../build/Makefile.asciidoc.inc:69: test-usermanual.pdf] Error 1 [ 343s] make[3]: Leaving directory '/usr/src/packages/BUILD/tests' [ 343s] make[2]: *** [Makefile:438: all-recursive] Error 1
So all in all, it seems that specific architectures in the distributions offered by OBS have or had a different version of asciidoc, and therefore behave differently (debian 9.0 aarch64, ubuntu 16.04 i586). I'm assigning this to myself and investigating further (starting with a new trigger of the job to see if all distributions are behaving the same again).
Updated by osmith over 4 years ago
For the record, the workaround for not making the builds fail when asciidoc prints a warning, would be commenting out this line:
@grep WARNING $(notdir $@) && exit 1 || exit 0
Updated by osmith over 4 years ago
So all in all, it seems that specific architectures in the distributions offered by OBS have or had a different version of asciidoc, and therefore behave differently (debian 9.0 aarch64, ubuntu 16.04 i586). I'm assigning this to myself and investigating further (starting with a new trigger of the job to see if all distributions are behaving the same again).
osmo-gsm-manuals and osmo-gsm-manuals-debian8-jessie are building again, for all supported distributions and architectures.
- https://build.opensuse.org/package/show/network:osmocom:nightly/osmo-gsm-manuals
- https://build.opensuse.org/package/show/network:osmocom:nightly/osmo-gsm-manuals-debian8-jessie
I suggest we close this in order to work on more important things, and only re-open it if it happens again.
pespin, is this fine for you?
Updated by pespin over 4 years ago
- Priority changed from Normal to Low
So after discussing with osmith, we agreed that for now we drop the workaround patch I submitted, but still leave this ticket open since working on the leveloffset stuff for all files in common/ still makes sense. Not urgent though, so changing priority to Low.
Updated by osmith over 4 years ago
- Priority changed from Low to High
This is happening again. I've changed the priority to high and will work on this.
Updated by osmith over 4 years ago
- Subject changed from osmo-gsm-manuals: Use leveoffset attribute on common documents to osmo-gsm-manuals: Use leveloffset attribute on common documents
Updated by osmith over 4 years ago
- Related to Bug #4140: osmo-gsm-manuals: asciidoc warnings fail the build in OBS added
Updated by osmith over 4 years ago
- Priority changed from High to Low
As long as this specific issue does not appear in jenkins and can not be reproduced by us locally, it seems more important to not fail on warnings in OBS: #4140