Merge pull request #237068 from pennae/manual-normalization

3 files changed, 28 insertions, 78 deletions

diff --git a/doc/languages-frameworks/bower.section.md b/doc/languages-frameworks/bower.section.md
index f39539059c04..fceb6aaccb6d 100644
--- a/doc/languages-frameworks/bower.section.md
+++ b/doc/languages-frameworks/bower.section.md
@@ -41,32 +41,18 @@ The function is implemented in [pkgs/development/bower-modules/generic/default.n
 
 ### Example buildBowerComponents {#ex-buildBowerComponents}
 
-```{=docbook}
-<programlisting language="nix">
+```nix
 bowerComponents = buildBowerComponents {
   name = "my-web-app";
-  generated = ./bower-packages.nix; <co xml:id="ex-buildBowerComponents-1" />
-  src = myWebApp; <co xml:id="ex-buildBowerComponents-2" />
+  generated = ./bower-packages.nix; # note 1
+  src = myWebApp; # note 2
 };
-</programlisting>
 ```
 
 In ["buildBowerComponents" example](#ex-buildBowerComponents) the following arguments are of special significance to the function:
 
-```{=docbook}
-<calloutlist>
-  <callout arearefs="ex-buildBowerComponents-1">
-    <para>
-      <varname>generated</varname> specifies the file which was created by <command>bower2nix</command>.
-    </para>
-    </callout>
-      <callout arearefs="ex-buildBowerComponents-2">
-    <para>
-      <varname>src</varname> is your project's sources. It needs to contain a <filename>bower.json</filename> file.
-    </para>
-  </callout>
-</calloutlist>
-```
+1. `generated` specifies the file which was created by {command}`bower2nix`.
+2. `src` is your project's sources. It needs to contain a {file}`bower.json` file.
 
 `buildBowerComponents` will run Bower to link together the output of `bower2nix`, resulting in a `bower_components` directory which can be used.
 
@@ -91,10 +77,9 @@ gulp.task('build', [], function () {
 
 ### Example Full example — default.nix {#ex-buildBowerComponentsDefaultNix}
 
-```{=docbook}
-<programlisting language="nix">
+```nix
 { myWebApp ? { outPath = ./.; name = "myWebApp"; }
-, pkgs ? import &lt;nixpkgs&gt; {}
+, pkgs ? import <nixpkgs> {}
 }:
 
 pkgs.stdenv.mkDerivation {
@@ -103,49 +88,29 @@ pkgs.stdenv.mkDerivation {
 
   buildInputs = [ pkgs.nodePackages.gulp ];
 
-  bowerComponents = pkgs.buildBowerComponents { <co xml:id="ex-buildBowerComponentsDefault-1" />
+  bowerComponents = pkgs.buildBowerComponents { # note 1
     name = "my-web-app";
     generated = ./bower-packages.nix;
     src = myWebApp;
   };
 
   buildPhase = ''
-    cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . <co xml:id="ex-buildBowerComponentsDefault-2" />
-    export HOME=$PWD <co xml:id="ex-buildBowerComponentsDefault-3" />
-    ${pkgs.nodePackages.gulp}/bin/gulp build <co xml:id="ex-buildBowerComponentsDefault-4" />
+    cp --reflink=auto --no-preserve=mode -R $bowerComponents/bower_components . # note 2
+    export HOME=$PWD # note 3
+    ${pkgs.nodePackages.gulp}/bin/gulp build # note 4
   '';
 
   installPhase = "mv gulpdist $out";
 }
-</programlisting>
 ```
 
 A few notes about [Full example — `default.nix`](#ex-buildBowerComponentsDefaultNix):
 
-```{=docbook}
-<calloutlist>
-  <callout arearefs="ex-buildBowerComponentsDefault-1">
-    <para>
-      The result of <varname>buildBowerComponents</varname> is an input to the frontend build.
-    </para>
-  </callout>
-  <callout arearefs="ex-buildBowerComponentsDefault-2">
-    <para>
-      Whether to symlink or copy the <filename>bower_components</filename> directory depends on the build tool in use. In this case a copy is used to avoid <command>gulp</command> silliness with permissions.
-    </para>
-  </callout>
-  <callout arearefs="ex-buildBowerComponentsDefault-3">
-    <para>
-      <command>gulp</command> requires <varname>HOME</varname> to refer to a writeable directory.
-    </para>
-  </callout>
-  <callout arearefs="ex-buildBowerComponentsDefault-4">
-    <para>
-      The actual build command. Other tools could be used.
-    </para>
-  </callout>
-</calloutlist>
-```
+1. The result of `buildBowerComponents` is an input to the frontend build.
+2. Whether to symlink or copy the {file}`bower_components` directory depends on the build tool in use.
+   In this case a copy is used to avoid {command}`gulp` silliness with permissions.
+3. {command}`gulp` requires `HOME` to refer to a writeable directory.
+4. The actual build command in this example is {command}`gulp`. Other tools could be used instead.
 
 ## Troubleshooting {#ssec-bower2nix-troubleshooting}
 
diff --git a/doc/languages-frameworks/gnome.section.md b/doc/languages-frameworks/gnome.section.md
index 897ebd7861fa..5208f1013cbd 100644
--- a/doc/languages-frameworks/gnome.section.md
+++ b/doc/languages-frameworks/gnome.section.md
@@ -137,15 +137,15 @@ Most GNOME package offer [`updateScript`](#var-passthru-updateScript), it is the
 
 ## Frequently encountered issues {#ssec-gnome-common-issues}
 
-#### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas}
+### `GLib-GIO-ERROR **: 06:04:50.903: No GSettings schemas are installed on the system` {#ssec-gnome-common-issues-no-schemas}
 
 There are no schemas available in `XDG_DATA_DIRS`. Temporarily add a random package containing schemas like `gsettings-desktop-schemas` to `buildInputs`. [`glib`](#ssec-gnome-hooks-glib) and [`wrapGAppsHook`](#ssec-gnome-hooks-wrapgappshook) setup hooks will take care of making the schemas available to application and you will see the actual missing schemas with the [next error](#ssec-gnome-common-issues-missing-schema). Or you can try looking through the source code for the actual schemas used.
 
-#### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema ‘org.gnome.foo’ is not installed` {#ssec-gnome-common-issues-missing-schema}
+### `GLib-GIO-ERROR **: 06:04:50.903: Settings schema ‘org.gnome.foo’ is not installed` {#ssec-gnome-common-issues-missing-schema}
 
 Package is missing some GSettings schemas. You can find out the package containing the schema with `nix-locate org.gnome.foo.gschema.xml` and let the hooks handle the wrapping as [above](#ssec-gnome-common-issues-no-schemas).
 
-#### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped}
+### When using `wrapGAppsHook` with special derivers you can end up with double wrapped binaries. {#ssec-gnome-common-issues-double-wrapped}
 
 This is because derivers like `python.pkgs.buildPythonApplication` or `qt5.mkDerivation` have setup-hooks automatically added that produce wrappers with makeWrapper. The simplest way to workaround that is to disable the `wrapGAppsHook` automatic wrapping with `dontWrapGApps = true;` and pass the arguments it intended to pass to makeWrapper to another.
 
@@ -193,7 +193,7 @@ mkDerivation {
 }
 ```
 
-#### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package}
+### I am packaging a project that cannot be wrapped, like a library or GNOME Shell extension. {#ssec-gnome-common-issues-unwrappable-package}
 
 You can rely on applications depending on the library setting the necessary environment variables but that is often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
 
@@ -209,6 +209,6 @@ You can rely on applications depending on the library setting the necessary envi
 
   []{#ssec-gnome-common-issues-unwrappable-package-gsettings-c} [Hard-coding GSettings schema path in C library](https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34) – nothing special other than using [Coccinelle patch](https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467) to generate the patch itself.
 
-#### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location}
+### I need to wrap a binary outside `bin` and `libexec` directories. {#ssec-gnome-common-issues-weird-location}
 
 You can manually trigger the wrapping with `wrapGApp` in `preFixup` phase. It takes a path to a program as a first argument; the remaining arguments are passed directly to [`wrapProgram`](#fun-wrapProgram) function.
diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md
index e09194e391e1..2300c5f60ede 100644
--- a/doc/languages-frameworks/qt.section.md
+++ b/doc/languages-frameworks/qt.section.md
@@ -10,37 +10,22 @@ pure and explicit at build-time, at the cost of introducing an extra indirection
 
 ## Nix expression for a Qt package (default.nix) {#qt-default-nix}
 
-```{=docbook}
-<programlisting>
-{ stdenv, lib, qtbase, wrapQtAppsHook }: <co xml:id='qt-default-nix-co-1' />
+```nix
+{ stdenv, lib, qtbase, wrapQtAppsHook }:
 
 stdenv.mkDerivation {
   pname = "myapp";
   version = "1.0";
 
   buildInputs = [ qtbase ];
-  nativeBuildInputs = [ wrapQtAppsHook ]; <co xml:id='qt-default-nix-co-2' />
+  nativeBuildInputs = [ wrapQtAppsHook ];
 }
-</programlisting>
-
- <calloutlist>
-  <callout arearefs='qt-default-nix-co-1'>
-   <para>
-    Import Qt modules directly, that is: <literal>qtbase</literal>, <literal>qtdeclarative</literal>, etc.
-    <emphasis>Do not</emphasis> import Qt package sets such as <literal>qt5</literal>
-    because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
-   </para>
-  </callout>
-  <callout arearefs='qt-default-nix-co-2'>
-    <para>
-      All Qt packages must include <literal>wrapQtAppsHook</literal> in
-      <literal>nativeBuildInputs</literal>, or you must explicitly set
-      <literal>dontWrapQtApps</literal>.
-    </para>
-  </callout>
- </calloutlist>
 ```
 
+It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
+
+Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`.
+
 ## Locating runtime dependencies {#qt-runtime-dependencies}
 
 Qt applications must be wrapped to find runtime dependencies.