bitbake: user-manual-metadata: Replace screen tags with literallayout tags

(Bitbake rev: be3967f9f088e414c679e72a947817b60bab82d7)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 142 insertions, 178 deletions

diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index c693e1e6ec..6ee8971562 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -31,9 +31,9 @@
             <title>Basic variable setting</title>
 
             <para>
-                <screen><varname>VARIABLE</varname> = "value"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     VARIABLE = "value"
+                </literallayout>
                 In this example, <varname>VARIABLE</varname> is <literal>value</literal>.
             </para>
         </section>
@@ -48,10 +48,10 @@
             </para>
 
             <para>
-                <screen><varname>A</varname> = "aval"
-<varname>B</varname> = "pre${A}post"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     A = "aval"
+     B = "pre${A}post"
+                </literallayout>
                 This results in <varname>A</varname> containing
                 <literal>aval</literal> and <varname>B</varname> containing
                 <literal>preavalpost</literal>.
@@ -62,9 +62,9 @@
             <title>Setting a default value (?=)</title>
 
             <para>
-                <screen><varname>A</varname> ?= "aval"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     A ?= "aval"
+                </literallayout>
                 If <varname>A</varname> is set before the above is called,
                 it will retain its previous value.
                 If <varname>A</varname> is unset prior to the above call,
@@ -78,10 +78,10 @@
             <title>Setting a weak default value (??=)</title>
 
             <para>
-                <screen><varname>A</varname> ??= "somevalue"
-<varname>A</varname> ??= "someothervalue"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     A ??= "somevalue"
+     A ??= "someothervalue"
+                </literallayout>
                 If <varname>A</varname> is set before the above,
                 it will retain that value.
                 If <varname>A</varname> is unset prior to the above,
@@ -99,17 +99,14 @@
 
             <para>
                 := results in a variable's contents being expanded immediately, rather than when the variable is actually used.
-            </para>
-            <para>
-                <screen><varname>T</varname> = "123"
-<varname>A</varname> := "${B} ${A} test ${T}"
-<varname>T</varname> = "456"
-<varname>B</varname> = "${T} bval"
-
-<varname>C</varname> = "cval"
-<varname>C</varname> := "${C}append"</screen>
-            </para>
-            <para>
+            <literallayout class='monospaced'>
+     T = "123"
+     A := "${B} ${A} test ${T}"
+     T = "456"
+     B = "${T} bval"
+     C = "cval"
+     C := "${C}append"
+                </literallayout>
                 In that example, <varname>A</varname> would contain <literal> test 123</literal>, <varname>B</varname> would contain <literal>456 bval</literal>, and <varname>C</varname> would be <literal>cvalappend</literal>.
             </para>
         </section>
@@ -118,12 +115,12 @@
             <title>Appending (+=) and prepending (=+)</title>
 
             <para>
-                <screen><varname>B</varname> = "bval"
-<varname>B</varname> += "additionaldata"
-<varname>C</varname> = "cval"
-<varname>C</varname> =+ "test"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     B = "bval"
+     B += "additionaldata"
+     C = "cval"
+     C =+ "test"
+                </literallayout>
                 In this example, <varname>B</varname> is now <literal>bval additionaldata</literal> and <varname>C</varname> is <literal>test cval</literal>.
             </para>
         </section>
@@ -132,12 +129,12 @@
             <title>Appending (.=) and prepending (=.) without spaces</title>
 
             <para>
-                <screen><varname>B</varname> = "bval"
-<varname>B</varname> .= "additionaldata"
-<varname>C</varname> = "cval"
-<varname>C</varname> =. "test"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     B = "bval"
+     B .= "additionaldata"
+     C = "cval"
+     C =. "test"
+                </literallayout>
                 In this example, <varname>B</varname> is now
                 <literal>bvaladditionaldata</literal> and
                 <varname>C</varname> is <literal>testcval</literal>.
@@ -150,12 +147,12 @@
             <title>Appending and Prepending (override style syntax)</title>
 
             <para>
-                <screen><varname>B</varname> = "bval"
-<varname>B_append</varname> = " additional data"
-<varname>C</varname> = "cval"
-<varname>C_prepend</varname> = "additional data "</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     B = "bval"
+     B_append = " additional data"
+     C = "cval"
+     C_prepend = "additional data "
+                </literallayout>
                 This example results in <varname>B</varname>
                 becoming <literal>bval additional data</literal>
                 and <varname>C</varname> becoming
@@ -170,11 +167,11 @@ yourself.
         <section id='removing-override-style-syntax'>
             <title>Removing (override style syntax)</title>
             <para>
-                <screen><varname>FOO</varname> = "123 456 789 123456 123 456 123 456"
-<varname>FOO_remove</varname> = "123"
-<varname>FOO_remove</varname> = "456"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     FOO = "123 456 789 123456 123 456 123 456"
+     FOO_remove = "123"
+     FOO_remove = "456"
+                </literallayout>
                 In this example, <varname>FOO</varname> is now <literal>789 123456</literal>.
             </para>
         </section>
@@ -186,11 +183,9 @@ yourself.
                 Variables can have associated flags which provide a way of tagging extra information onto a variable.
                 Several flags are used internally by BitBake but they can be used externally too if needed.
                 The standard operations mentioned above also work on flags.
-            </para>
-            <para>
-                <screen><varname>VARIABLE</varname>[<varname>SOMEFLAG</varname>] = "value"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     VARIABLE[SOMEFLAG] = "value"
+                </literallayout>
                 In this example, <varname>VARIABLE</varname> has a flag,
                 <varname>SOMEFLAG</varname> which is set to <literal>value</literal>.
             </para>
@@ -200,9 +195,9 @@ yourself.
             <title>Python variable expansion</title>
 
             <para>
-                <screen><varname>DATE</varname> = "${@time.strftime('%Y%m%d',time.gmtime())}"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
+                </literallayout>
                 This would result in the <varname>DATE</varname>
                 variable containing today's date.
             </para>
@@ -219,14 +214,12 @@ yourself.
                 version of the variable is used rather than the non-conditional
                 version.
                 Example:
-            </para>
-            <para>
-                <screen><varname>OVERRIDES</varname> = "architecture:os:machine"
-<varname>TEST</varname> = "defaultvalue"
-<varname>TEST_os</varname> = "osspecificvalue"
-<varname>TEST_condnotinoverrides</varname> = "othercondvalue"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     OVERRIDES = "architecture:os:machine"
+     TEST = "defaultvalue"
+     TEST_os = "osspecificvalue"
+     TEST_condnotinoverrides = "othercondvalue"
+                </literallayout>
                 In this example, <varname>TEST</varname> would be
                 <literal>osspecificvalue</literal>, due to the condition
                 <quote>os</quote> being in <varname>OVERRIDES</varname>.
@@ -239,13 +232,11 @@ yourself.
             <para>
                 BitBake also supports appending and prepending to variables based
                 on whether something is in OVERRIDES.  Example:
-            </para>
-            <para>
-                <screen><varname>DEPENDS</varname> = "glibc ncurses"
-<varname>OVERRIDES</varname> = "machine:local"
-<varname>DEPENDS_append_machine</varname> = " libmad"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     DEPENDS = "glibc ncurses"
+     OVERRIDES = "machine:local"
+     DEPENDS_append_machine = "libmad"
+                </literallayout>
                 In this example, <varname>DEPENDS</varname> is set to
                 <literal>glibc ncurses libmad</literal>.
             </para>
@@ -268,43 +259,38 @@ yourself.
             </para>
 
             <para>
-                <screen><varname>OVERRIDES</varname> = "foo"
-<varname>A_foo_append</varname> = "X"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     OVERRIDES = "foo"
+     A_foo_append = "X"
+                </literallayout>
                 In this case, X is unconditionally appended
                 to the variable <varname>A_foo</varname>.
                 Since foo is an override, A_foo would then replace
                 <varname>A</varname>.
-            </para>
-            <para>
-                <screen><varname>OVERRIDES</varname> = "foo"
-<varname>A</varname> = "X"
-<varname>A_append_foo</varname> = "Y"</screen></para>
-                <para>
+                <literallayout class='monospaced'>
+     OVERRIDES = "foo"
+     A = "X"
+     A_append_foo = "Y"
+                </literallayout>
                 In this case, only when foo is in
                 OVERRIDES, Y
                 is appended to the variable <varname>A</varname>
                 so the value of <varname>A</varname> would
                 become XY (NB: no spaces are appended).
-            </para>
-            <para>
-                <screen><varname>OVERRIDES</varname> = "foo"
-<varname>A_foo_append</varname> = "X"
-<varname>A_foo_append</varname> += "Y"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     OVERRIDES = "foo"
+     A_foo_append = "X"
+     A_foo_append += "Y"
+                </literallayout>
                 This behaves as per the first case above, but the value of
                 <varname>A</varname> would be "X Y" instead of just "X".
-            </para>
-            <para>
-                <screen><varname>A</varname> = "1"
-<varname>A_append</varname> = "2"
-<varname>A_append</varname> = "3"
-<varname>A</varname> += "4"
-<varname>A</varname> .= "5"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     A = "1"
+     A_append = "2"
+     A_append = "3"
+     A += "4"
+     A .= "5"
+                </literallayout>
                 Would ultimately result in <varname>A</varname> taking the value
                 "1 4523" since the _append operator executes at the
                 same time as the expansion of other overrides.
@@ -317,13 +303,11 @@ yourself.
             <para>
                 Key expansion happens at the data store finalisation
                 time just before overrides are expanded.
-            </para>
-            <para>
-                <screen><varname>A${B}</varname> = "X"
-<varname>B</varname> = "2"
-<varname>A2</varname> = "Y"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     A${B} = "X"
+     B = "2"
+     A2 = "Y"
+                </literallayout>
                 So in this case <varname>A2</varname> would take the value of "X".
             </para>
         </section>
@@ -378,18 +362,15 @@ raise an
         <title>Defining Python functions into the global Python namespace</title>
 
         <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files
-                </para>
-                <para>
-                    <screen>def get_depends(bb, d):
-    if d.getVar('SOMECONDITION', True):
-        return "dependencywithcond"
-    else:
-        return "dependency"
-
-<varname>SOMECONDITION</varname> = "1"
-<varname>DEPENDS</varname> = "${@get_depends(bb, d)}"</screen>
-                </para>
-                <para>
+                <literallayout class='monospaced'>
+     def get_depends(d):
+         if d.getVar('SOMECONDITION', True):
+             return "dependencywithcond"
+         else:
+             return "dependency"
+     SOMECONDITION = "1"
+     DEPENDS = "${@get_depends(d)}"
+                </literallayout>
                 This would result in <varname>DEPENDS</varname> containing <literal>dependencywithcond</literal>.
             </para>
     </section>
@@ -397,22 +378,18 @@ raise an
     <section>
         <title>Defining executable metadata</title>
             <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.
-            </para>
-            <para>
-                <screen>do_mytask () {
+            <literallayout class='monospaced'>
+do_mytask () {
     echo "Hello, world!"
-}</screen>
-            </para>
-            <para>
+}
+            </literallayout>
             This is essentially identical to setting a variable, except that this variable happens to be executable shell code.
-            </para>
-            <para>
-                <screen>python do_printdate () {
+            <literallayout class='monospaced'>
+python do_printdate () {
     import time
     print time.strftime('%Y%m%d', time.gmtime())
-}</screen>
-            </para>
-            <para>
+}
+            </literallayout>
             This is the similar to the previous, but flags it as Python so that BitBake knows it is Python code.
         </para>
     </section>
@@ -421,16 +398,13 @@ raise an
         <title>Tasks</title>
         <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para>
         <para>In BitBake, each step that needs to be run for a given .bb is known as a task.  There is a command <literal>addtask</literal> to add new tasks (must be a defined Python executable metadata and must start with <quote>do_</quote>) and describe intertask dependencies.
-        </para>
-        <para>
-            <screen>python do_printdate () {
-    import time
-    print time.strftime('%Y%m%d', time.gmtime())
-}
-
-addtask printdate before do_build</screen>
-        </para>
-        <para>
+            <literallayout class='monospaced'>
+     python do_printdate () {
+         import time print
+         time.strftime('%Y%m%d', time.gmtime())
+     }
+     addtask printdate after do_fetch before do_build
+            </literallayout>
             This defines the necessary Python function and adds it as a task which is now a dependency of do_build, the default task.  If anyone executes the do_build task, that will result in do_printdate being run first.
         </para>
     </section>
@@ -529,19 +503,15 @@ addtask printdate before do_build</screen>
             task failure, task success, et cetera.
             The intent is to make it easy to do things like email
             notification on build failure.
-            </para>
-            <para>
-                <screen>addhandler myclass_eventhandler
-python myclass_eventhandler() {
-    from bb.event import getName
-    from bb import data
-
-    print("The name of the Event is %s" % getName(e))
-    print("The file we run for is %s" % data.getVar('FILE', e.data, True))
-}
-</screen>
-        </para>
-        <para>
+            <literallayout class='monospaced'>
+     addhandler myclass_eventhandler
+     python myclass_eventhandler() {
+         from bb.event import getName
+         from bb import data
+         print("The name of the Event is %s" % getName(e))
+         print("The file we run for is %s" % data.getVar('FILE', e.data, True))
+     }
+            </literallayout>
             This event handler gets called every time an event is
             triggered.
             A global variable <varname>e</varname> is defined.
@@ -569,7 +539,10 @@ python myclass_eventhandler() {
             The first is <varname>BBCLASSEXTEND</varname>.
             This variable is a space separated list of classes used to "extend" the
             recipe for each variant.
-            As an example, setting <screen>BBCLASSEXTEND = "native"</screen>
+            As an example, setting
+            <literallayout class='monospaced'>
+     BBCLASSEXTEND = "native"
+            </literallayout>
             results in a second incarnation of the current
             recipe being available.
             This second incarnation will have the "native" class inherited.
@@ -580,17 +553,14 @@ python myclass_eventhandler() {
             project from a single recipe file, and allows you to specify
             conditional metadata (using the <varname>OVERRIDES</varname>
             mechanism) for a single version, or an optionally named range of versions:
-        </para>
-        <para>
-            <screen>BBVERSIONS = "1.0 2.0 git"
-SRC_URI_git = "git://someurl/somepath.git"</screen>
-        </para>
-        <para>
-            <screen>BBVERSIONS = "1.0.[0-6]:1.0.0+ \
-              1.0.[7-9]:1.0.7+"
-SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"</screen>
-        </para>
-        <para>
+            <literallayout class='monospaced'>
+     BBVERSIONS = "1.0 2.0 git"
+     SRC_URI_git = "git://someurl/somepath.git"
+            </literallayout>
+            <literallayout class='monospaced'>
+     BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
+     SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
+            </literallayout>
             Note that the name of the range will default to the original version of the
             recipe, so given OE, a recipe file of foo_1.0.0+.bb
             will default the name of its versions to 1.0.0+.
@@ -629,11 +599,9 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
                 The 'deptask' flag for tasks is used to signify the task of each
                 item listed in DEPENDS which must have
                 completed before that task can be executed.
-            </para>
-            <para>
-                <screen>do_configure[deptask] = "do_populate_staging"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     do_configure[deptask] = "do_populate_staging"
+                </literallayout>
                 means the do_populate_staging
                 task of each item in DEPENDS must have completed before
                 do_configure can execute.
@@ -650,11 +618,9 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
                 The 'rdeptask' flag for tasks is used to signify the task of each
                 item runtime dependency which must have completed before that
                 task can be executed.
-            </para>
-            <para>
-                <screen>do_package_write[rdeptask] = "do_package"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     do_package_write[rdeptask] = "do_package"
+                </literallayout>
                 means the do_package
                 task of each item in RDEPENDS must have
                 completed before do_package_write can execute.
@@ -694,11 +660,9 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
                 The 'depends' flag for tasks is a more generic form of which
                 allows an interdependency on specific tasks rather than specifying
                 the data in DEPENDS.
-            </para>
-            <para>
-                <screen>do_patch[depends] = "quilt-native:do_populate_staging"</screen>
-            </para>
-            <para>
+                <literallayout class='monospaced'>
+     do_patch[depends] = "quilt-native:do_populate_staging"
+                </literallayout>
                 means the do_populate_staging
                 task of the target quilt-native must have completed before the
                 do_patch can execute.