sync (with build script), update and fix build configuration chapter

[adrianschroeter]

No description provided.

[smithfarm]

in the build configuration.
?

[smithfarm]

in the build configuration
?

[smithfarm]

in the build configuration
?

[adrianschroeter]

did we clarify your questions earlier this week?

[smithfarm]

@adrianschroeter This PR is not getting rid of the term "project config", so I guess it's OK that "project config" is being changed to "build config" only in certain places. But I'm missing an explanation of how the OBS determines which individual project configurations get merged to form the final build configuration?

On a somewhat unrelated note: is there an osc command to list the full expanded path for a given repo? That might help folks understand where certain lines from their build config are coming from.

[adrianschroeter]

I tried to adress the difference between the editable hunks and the effective build configuration at build time now.

[smithfarm]

spelling: separated

[smithfarm]

The "macros" section ("Macro Definitions in the Build Configuration") is unfortunately still not clear. What I was able to figure out was:

1. there are two types of macros: "%define macros" and "Macros: macros"
2. %define macros are only expanded in the build configuration
3. Macros: macros are only expanded in the build root

This necessarily implies that if you want to define a macro universally, so it expands in both places, you have to define it twice. And I can see this is being done "in real life", e.g. (direct quote from a prjconf):

%define sle_version 150600
Macros:
%sle_version 150600
:Macros

What is not clear:

1. what happens if someone uses %global, instead of %define, in the build configuration? Is it effectively the same as %define, or different?
2. I understand that Macros: macro definitions can be placed anywhere in the prjconf as long as they are terminated with a :Macros line. It is also possible to put them at the end of the prjconf, in which case the terminating :Macros line is optional. But is the beginning Macros: line also optional? For example, what happens if I have prjconf file consisting of only one line, e.g.:

%_with_foo 1
<EOF>

I tried it and the OBS accepts it, but I don't know what the effect is. Is it the same as:

Macros:
%_with_foo 1
<EOF>

and also the same as

Macros:
%_with_foo 1
:Macros
<EOF>

?

Oh, and another question: when I save my prjconf, does the OBS do any validation on it at all? For example, I tried the following prjconf, which in my understanding is invalid:

%_with_lowmem_builder 1
FileProvides: /usr/bin/dbus-run-session dbus-1

but the OBS accepts it. Is the first line (which is not a valid Macros: macro definition, nor a valid %defines macro defintion) simply ignored?

[adrianschroeter]

@smithfarm I tried to address your questions in my last commit.

[smithfarm]

LGTM

[smithfarm]

@tomschr Here's where the error got introduced. Merged on March 22.

[tomschr]

Just for the record and for the others: the default validation in our doc CI changed from DocBook to GeekoDoc. The latter is a subset of the former. It's basically a more simplified version of DocBook. The elements are the still the same, the set of elements are reduced and some content models are more restrictive.

In this particular case, GeekoDoc doesn't allow other block elements like <screen> inside a paragraph. You have two options to solve that:

1. Going back and validating with DocBook.
   In that case, add in your DC files the following line:

   DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rng"
   

2. Migrate your docs to validate with GeekoDoc.
   In most cases, validation errors with GeekoDoc falls into one of the following categories:

   • Wrong xml:id values
     Dots aren't allowed, only digits, lowercase and uppercase A-Z letters, and dashes.

   • Unknown elements
     Some elements like <footnote> or <footnoteref> were disabled. In this case, you can replace <footnoteref> with <xref/>. For footnotes, you need to find a substitution and need to restructure the content.

   • Block elements inside paragraphs
     DocBook distinguishes between division, block, and inline elements. Division elements contain block elements, and block elements inline elements. Sometimes you can nest block elements inside other block elements. GeekoDoc made that simpler and forbid this. You need to clearly separate them.

Which of the approach is the better solution depends on what features you need. GeekoDoc is a bit simpler, but could confuse people if they are used to DocBook or only know that.