Project

General

Profile

Bug #4131

osmo-gsm-manuals: Use leveloffset attribute on common documents

Added by pespin 3 months ago. Updated 2 months ago.

Status:
In Progress
Priority:
Low
Assignee:
Target version:
-
Start date:
07/26/2019
Due date:
% Done:

0%

Spec Reference:

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

Related to Cellular Network Infrastructure - Bug #4140: osmo-gsm-manuals: asciidoc warnings fail the build in OBSResolved08/02/2019

History

#1 Updated by pespin 3 months 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

#2 Updated by osmith 3 months 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?!):

https://build.opensuse.org/package/live_build_log/network:osmocom:nightly/osmo-gsm-manuals-debian8-jessie/xUbuntu_16.04/i586

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:

https://build.opensuse.org/package/live_build_log/network:osmocom:nightly/osmo-gsm-manuals/Debian_Testing/x86_64

[  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).

#3 Updated by osmith 3 months 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

https://git.osmocom.org/osmo-gsm-manuals/tree/build/Makefile.asciidoc.inc?id=abadcd5f8a663695b6c8d0d249806e81116570e7#n100

#4 Updated by osmith 3 months 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.

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?

#5 Updated by pespin 3 months 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.

#6 Updated by osmith 2 months ago

  • Priority changed from Low to High

This is happening again. I've changed the priority to high and will work on this.

#7 Updated by osmith 2 months ago

  • Subject changed from osmo-gsm-manuals: Use leveoffset attribute on common documents to osmo-gsm-manuals: Use leveloffset attribute on common documents

#8 Updated by osmith 2 months ago

  • Related to Bug #4140: osmo-gsm-manuals: asciidoc warnings fail the build in OBS added

#9 Updated by osmith 2 months 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

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)