Commit 2f76a3df authored by pennae's avatar pennae
Browse files

doc: don't use docbook program listings/callouts 

nixos-render-docs does not support this, and since the examples are
small there isn't that much value in callouts here. change them to
simple MD code blocks and lists instead.
parent 2ecc93d6

doc/languages-frameworks/bower.section.md

+16 −51
Original line number Diff line number Diff line
@@ -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}

doc/languages-frameworks/qt.section.md

+7 −22
Original line number Diff line number Diff line
@@ -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.