From fdc63c54e42f317865d3d7b17dc16325a97821fc Mon Sep 17 00:00:00 2001
From: Marc Weber <marco-oweber@gmx.de>
Date: Thu, 7 Jan 2010 09:01:40 +0000
Subject: [PATCH] enhance phpIni documentation

readd r19267 (the issue should be fixed now)

Eelco Dolstra and Nicolas Pierron both kept asking me to pay attention
to the rendered manual. There is one catch: example settings such as
pkgs.kernelPackages_2_6_25 are correct however they don't render
properly. Moreover you don't want those examples to be evaluated (maybe
compiling a kernel ?) when building the manual only.
So use Strings and add a copy & paste note.
This is still a hacky. Maybe a kind of typed "verbatim" expression
should be added (?)

svn path=/nixos/trunk/; revision=19281
---
 .../web-servers/apache-httpd/default.nix      | 58 +++++++++++++++++--
 modules/system/boot/kernel.nix                |  6 +-
 2 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/modules/services/web-servers/apache-httpd/default.nix b/modules/services/web-servers/apache-httpd/default.nix
index 91fce4f8dff..878e1c1f371 100644
--- a/modules/services/web-servers/apache-httpd/default.nix
+++ b/modules/services/web-servers/apache-httpd/default.nix
@@ -464,6 +464,56 @@ in
         '';
       };
 
+      phpIni = mkOption {
+        default = pkgs.writeText "php.ini" ''
+           ; Needed for PHP's mail() function.
+           sendmail_path = sendmail -t -i
+         '';
+
+        example = ''
+        Example code (copy & paste):
+
+         most simple:
+         phpIni pkgs.writeText "php.ini" '''
+           ; Needed for PHP's mail() function.
+           sendmail_path = sendmail -t -i
+         ''';
+
+         using recommended settings and enabling Xdebug:
+         phpIni =  pkgs.phpIniBuilder.override {
+            appendLines = '''
+             sendmail_path = sendmail -t -i
+             zend_extension="''\${pkgs.phpXdebug}/lib/xdebug.so"
+             zend_extension_ts="''\${pkgs.phpXdebug}/lib/xdebug.so"
+             zend_extension_debug="''\${pkgs.phpXdebug}/lib/xdebug.so"
+             xdebug.remote_enable=true
+             xdebug.remote_host=127.0.0.1
+             xdebug.remote_port=9000
+             xdebug.remote_handler=dbgp
+             xdebug.profiler_enable=0
+             xdebug.profiler_output_dir="/tmp/xdebug"
+             xdebug.remote_mode=req
+            ''';
+          };
+        '';
+
+
+        description = ''
+          The contents of this option are used as global php.ini file by the
+          PHP interpreter used by Apache. You have to enable PHP explicitly.
+          See extraModules options.
+
+          This file defaults to defining sendmail_path only.
+
+          Note: Depending on your configuration you can set PHP ini values using .htaccess files and the
+          php_value option.
+
+          The example shows how to enable Xdebug and use the recommended
+          php.ini values which are contained in the PHP distribution.
+          I don't know whether they are equal to defaults
+        '';
+      };
+
     }
 
     # Include the options shared between the main server and virtual hosts.
@@ -520,12 +570,8 @@ in
                 optional config.networking.defaultMailServer.directDelivery "${pkgs.ssmtp}/sbin"
              ++ (concatMap (svc: svc.extraServerPath) allSubservices) );
 
-           PHPRC = pkgs.writeText "php.ini"
-             ''
-               ; Needed for PHP's mail() function.
-               sendmail_path = sendmail -t -i
-             '';
-           
+           PHPRC = mainCfg.phpIni;
+
           } // (listToAttrs (concatMap (svc: svc.globalEnvVars) allSubservices));
 
         preStart =
diff --git a/modules/system/boot/kernel.nix b/modules/system/boot/kernel.nix
index 60bc47cdc65..ea93f86e321 100644
--- a/modules/system/boot/kernel.nix
+++ b/modules/system/boot/kernel.nix
@@ -12,7 +12,11 @@ let kernel = config.boot.kernelPackages.kernel; in
   
     boot.kernelPackages = mkOption {
       default = pkgs.kernelPackages;
-      example = pkgs.kernelPackages_2_6_25;
+      example = ''
+        Example code (copy & paste):
+        pkgs.kernelPackages_2_6_25
+      '';
+
       description = ''
         This option allows you to override the Linux kernel used by
         NixOS.  Since things like external kernel module packages are