Resolved the following conflicts (by carefully applying patches from the both
branches since the fork point):
pkgs/development/libraries/epoxy/default.nix
pkgs/development/libraries/gtk+/3.x.nix
pkgs/development/python-modules/asgiref/default.nix
pkgs/development/python-modules/daphne/default.nix
pkgs/os-specific/linux/systemd/default.nix
`nixos-generate-config` detects the `cpuFreqGovernor` suited best for my
machine, e.g. `powerManagement.cpuFreqGovernor = lib.mkDefault "powersave";`.
However the `powerManagement` module sets a sensitive default for
`cpuFreqGovernor` using `mkDefault` to avoid breackage with older
setups. Since 140ac2f1 the `hardware-configuration.nix` sets the
gorvernor with `mkDefault` as well which causes evaluation errors if the
powermanagement module is enabled:
```
error: The unique option `powerManagement.cpuFreqGovernor' is defined multiple times, in `/home/ma27/Projects/nixos-config/hardware-configuration.nix' and `/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/config/power-management.nix'.
```
Using `mkOptionDefault` rather than `mkDefault` in the powermanagement
module fixes this issue as it decreases the priority of the module and
prefers the value set in `hardware-configuration.nix`.
I have confirmed the change using the following VM declaration:
```
{
cpuFreq = { lib, ... }: {
powerManagement.cpuFreqGovernor = lib.mkDefault "powersave";
powerManagement.enable = true;
};
}
```
- /var/run -> /run as the former is deprecated
- configure openal to use pulseaudio if pulseaudio is enabled
- configure libao to use pulseaudio if pulseaudio is enabled
Commit 987aac7 and issue #18183 were intended to fix support for other
things, but in the process, changed mdns_minimal to use the wrong return
setting, resulting in permanent failures in early boot, affecting things
like issue #30459.
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
This reverts commit 670b4e29adc16e0a29aa5b4c126703dcca56aeb6. The change
added in this commit was controversial when it was originally suggested
in https://github.com/NixOS/nixpkgs/pull/29205. Then that PR was closed
and a new one opened, https://github.com/NixOS/nixpkgs/pull/29503,
effectively circumventing the review process. I don't agree with this
modification. Adding an option 'resolveLocalQueries' to tell the locally
running name server that it should resolve local DNS queries feels
outright nuts. I agree that the current state is unsatisfactory and that
it should be improved, but this is not the right way.
(cherry picked from commit 23a021d12e8f939cd0bfddb1c7adeb125028c1e3)
When the user specifies the networking.nameservers setting in the
configuration file, it must take precedence over automatically
derived settings.
The culprit was services.bind that made the resolver set to
127.0.0.1 and ignore the nameserver setting.
This patch adds a flag to services.bind to override the nameserver
to localhost. It defaults to true. Setting this to false prevents the
service.bind and dnsmasq.resolveLocalQueries settings from
overriding the users' settings.
Also, when the user specifies a domain to search, it must be set in
the resolver configuration, even if the user does not specify any
nameservers.
(cherry picked from commit 670b4e29adc16e0a29aa5b4c126703dcca56aeb6)
This commit was accidentally merged to 17.09 but was intended for
master. This is the cherry-pick to master.
In order for DynamicUser = true to work in services, we need the
nss-systemd module to be able to resolve the user and group names
generated dynamically.
Evaluation error introduced in a0d464033c.
If the value for timeZone is null it shouldn't be even tried to coerce
it into a string.
Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Cc: @lheckemann, @joachifm
Creating and then erasing the key relies on the disk erasing data
correctly, and otherwise allows attackers to simply decrypt swap just
using "secretkey". We don't actually need a LUKS header, so we can save
ourselves some pointless disk writes and identifiability.
In addition, I wouldn't have made the awful mistake of backing up my swap partition's LUKS header instead of my zpool's. May my data rest in peace.
While systemd suggests using the pre-defined graphical-session user
target, I found that this interface is difficult to use. Additionally,
no other major distribution, even in their unstable versions, currently
use this mechanism.
The window or desktop manager is supposed to run in a systemd user service
which activates graphical-session.target and the user services that are
binding to this target. The issue is that we can't elegantly pass the
xsession environment to the window manager session, in particular
whereas the PassEnvironment option does work for DISPLAY, it for some
mysterious reason won't for PATH.
This commit implements a new graphical user target that works just like
default.target. Services which should be run in a graphical session just
need to declare wantedBy graphical.target. The graphical target will be
activated in the xsession before executing the window or display manager.
Fixes#17858.
gyre-fonts provides high-quality TrueType substitutes for standard PostScript
fonts. Unlike most other distributions, NixOS does not install Ghostscript and
its Type 1 fonts by default, so we must get the standard fonts elsewhere.
When a user or group is revived, this allows it to be allocated the
UID/GID it had before.
A consequence is that UIDs and GIDs are no longer reused.
Fixes#24010.
The inability to run strace or gdb is the kind of
developer-unfriendliness that we're used to from OS X, let's not do it
on NixOS.
This restriction can be re-enabled by setting
boot.kernel.sysctl."kernel.yama.ptrace_scope" = 1;
It might be nice to have a NixOS module for enabling hardened defaults.
Xref #14392.
Thanks @abbradar.
The Infinality bytecode interpreter is removed in favor of the new v40 TrueType
interpreter. In the past, the Infinality interpreter provided support for
ClearType-style hinting instructions while the default interpreter (then v35)
provided support only for original TrueType-style instructions. The v40
interpreter corrects this deficiency, so the Infinality interpreter is no longer
necessary.
To understand why the Infinality interpreter is no longer necessary, we should
understand how ClearType differs from TrueType and how the v40 interpreter
works. The following is a summary of information available on the FreeType
website [1] mixed with my own editorializing.
TrueType instructions use horizontal and vertical hints to improve glyph
rendering. Before TrueType, fonts were only vertically hinted; horizontal hints
improved rendering by snapping stems to pixel boundaries. Horizontal hinting is
a risk because it can significantly distort glyph shapes and kerning. Extensive
testing at different resolutions is needed to perfect the TrueType
hints. Microsoft invested significant effort to do this with its "Core fonts for
the Web" project, but few other typefaces have seen this level of attention.
With the advent of subpixel rendering, the effective horizontal resolution of
most displays increased significantly. ClearType eschews horizontal hinting in
favor of horizontal supersampling. Most fonts are designed for the Microsoft
bytecode interpreter, which implements a compatibility mode with
TrueType-style (horizontal and vertical) instructions. However, applying the
full horizontal hints to subpixel-rendered fonts leads to color fringes and
inconsistent stem widths. The Infinality interpreter implements several
techniques to mitigate these problems, going so far as to embed font- and
glyph-specific hacks in the interpreter. On the other hand, the v40 interpreter
ignores the horizontal hinting instructions so that glyphs render as they are
intended to on the Microsoft interpreter. Without the horizontal hints, the
problems of glyph and kerning distortion, color fringes, and inconsistent stem
widths--the problems the Infinality interpreter was created to solve--simply
don't occur in the first place.
There are also security concerns which motivate removing the Infinality patches.
Although there is an updated version of the Infinality interpreter for FreeType
2.7, the lack of a consistent upstream maintainer is a security concern. The
interpreter is a Turing-complete virtual machine which has had security
vulnerabilities in the past. While the default interpreter is used in billions
of devices and is maintained by an active developer, the Infinality interpreter
is neither scrutinized nor maintained. We will probably never know if there are
defects in the Infinality interpreter, and if they were discovered they would
likely never be fixed. I do not think that is an acceptable situtation for a
core library like FreeType.
Dropping the Infinality patches means that font rendering will be less
customizable. I think this is an acceptable trade-off. The Infinality
interpreter made many compromises to mitigate the problems with horizontal
hinting; the main purpose of customization is to tailor these compromises to the
user's preferences. The new interpreter does not have to make these compromises
because it renders fonts as their designers intended, so this level of
customization is not necessary.
The Infinality-associated patches are also removed from cairo. These patches
only set the default rendering options in case they aren't set though
Fontconfig. On NixOS, the rendering options are always set in Fontconfig, so
these patches never actually did anything for us!
The Fontconfig test suite is patched to account for a quirk in the way PCF fonts
are named.
The fontconfig option `hintstyle` is no longer configurable in NixOS. This
option selects the TrueType interpreter; the v40 interpreter is `hintslight` and
the older v35 interpreter is `hintmedium` or `hintfull` (which have actually
always been the same thing). The setting may still be changed through the
`localConf` option or by creating a user Fontconfig file.
Users with HiDPI displays should probably disable hinting and antialiasing: at
best they have no visible effect.
The fontconfig-ultimate settings are still available in NixOS, but they are no
longer the default. They still work, but their main purpose is to set rendering
quirks which are no longer necessary and may actually be
detrimental (e.g. setting `hintfull` for some fonts). Also, the vast array of
font substitutions provided is not an appropriate default; the default setting
should be to give the user the font they asked for.
[1]. https://www.freetype.org/freetype2/docs/subpixel-hinting.html
Overriding ``glibcLocales`` via nixpkgs.overlays not works,
so I added i18n.glibcLocales parameter, defaulted with
old override, using i18n.supportedLocales.
This adds pulseaudio.daemon.config, which is a set of keys to values
which are directly translated to keys and values of pulseaudio's
daemon.conf, e. g.
hardware.pulseaudio.daemon.config = { flat-volumes = "no"; }
becomes
flat-volumes=no
in pulse/daemon.conf.
I have left in 2 NixOS custom config directives, so the configuration
should be the same with the only change in behaviour being that the
service is not eagerly loaded but in fact only socket activated, which
it should be.
perlPackages.TextWrapI18N: init at 0.06
perlPackages.Po4a: init at 0.47
jade: init at 1.2.1
ding-libs: init at 0.6.0
Switch nscd to no-caching mode if SSSD is enabled.
abbradar: disable jade parallel building.
Closes#21150
* cpu-freq: Try powersave if ondemand is not available
* Revert "cpu-freq: Try powersave if ondemand is not available"
This reverts commit 4dc56db37e32dcfecd667ebbf88263e47b296097.
Consult available scaling governors; for freshly generated configs, this provides a better experience than relying on a default that might not work everywhere.
- most nixos user only require time synchronisation,
while ntpd implements a battery-included ntp server (1,215 LOCs of C-Code vs 64,302)
- timesyncd support ntp server per interface (if configured through dhcp for instance)
- timesyncd is already included in the systemd package, switching to it would
save a little disk space (1,5M)
Using "tmpfs" as a script part for system.activationScripts is a bit
misleading since 6efcfe03ae.
We no longer solely mount tmpfs within this script, so using "specialfs"
fits more nicely in terms of naming.
Tested against the "simple" NixOS installer test.
Signed-off-by: aszlig <aszlig@redmoonstudios.org>
Systemd upstream provides targets for networking. This also includes a target network-online.target.
In this PR I remove / replace most occurrences since some of them were even wrong and could delay startup.
We were pulling in 44 MiB of fonts in the default configuration, which
is a bit excessive for headless configurations like EC2
instances. Note that dejavu_minimal ensures that remote X11-forwarded
applications still have a basic font regardless.
This reverts commit 582313bafe.
Removing rsync is actually pointless because nixos-install depends on
it. So if it's part of the system closure, we may as well provide it
to users.
Probably with the next Nix release we can drop the use of rsync and
use "nix copy" instead.
This one was already merged into release-16.09, so let's not have the
stable branch is ahead of master and confuse things. In addition to
that, currently we have an odd situation that master has less things
actually finished building than in staging.
Conflicts:
pkgs/data/documentation/man-pages/default.nix
Verified that following nixos configuration:
users.users.foo = {
uid = 1000;
name = "foo";
};
users.users.bar = {
name = "bar";
};
Before this commit both users will get uid of 1000, after it's applied
bar will correctly get 1001.
The fontconfig-ultimate patches are unmaintained. Since they were
not updated for newer FreeType versions, this removes them and
disables fontconfig-ultimate by default.
This removes our hardcoded presets which weren't updated for quite some time.
Infinality now has new hardcoded presets in freetype, which can be overriden if
desired with environment variables (as before). Accordingly, updated NixOS
module to set the hardcoded preset.
Additionally used a more "right" type for substitutions.
Adds options for tcp streaming and avahi zeroconf support (so that the
server can be easily found by clients).
There is also an option to allow anonymous clients to stream to the
server (by default pulseaudio uses a cookie mechanism, see manpage).
Currently NixOS creates the swapfile (with the specified size) only if
it doesn't already exist. Changing the swapfile size afterwards will not
have any effect.
This commit changes that so the swapfile will be recreated whenever
swapDevices.*.size is changed (or more precisely, whenever the actual
file size differs from the configured one), allowing both growing and
shrinking the swapfile.
The service unit has "restartIfChanged = false", so we don't have to
worry about the swapfile being in use at the time this code is run (you
have to reboot for swapfile changes).
fallocate doesn't shrink files, use truncate for that. truncate can also
be used to grow files, but it creates "holes" in the file which doesn't
work with swapfiles.
Instead of showing this output from "nixos-rebuild switch":
warning: not applying GID change of group ‘munin’
warning: not applying UID change of user ‘ntp’
print this:
warning: not applying GID change of group ‘munin’ (95 -> 102)
warning: not applying UID change of user ‘ntp’ (3 -> 179)
This makes it possible for users to take action and fixup the UIDs/GIDs
that NixOS won't touch.
This GID was used to exempt users from Grsecurity's
`/proc` restrictions; we now prefer to rely on
`security.hideProcessInformation`, which uses the `proc` group
for this purpose. That leaves no use for the grsecurity GID.
More generally, having only a single GID to, presumably, serve as the
default for all of grsecurity's GID based exemption/resriction schemes
would be problematic in any event, so if we decide to enable those
grsecurity features in the future, more specific GIDs should be added.
The primary motivation here is to get rid of builderDefs, but now the
resulting font directory is also linked into /run/current-system/sw,
which fixes#15194.
This properly implements revert in
0729f60697.
We used to have which='type -P' alias, but really it's best to just
rely on which package, only 88K in size.
cc @edolstra
Most of the desktop environments will spawn pulseaudio, but we can instead simply run it as a systemd service instead.
This patch also makes the system wide service run in foreground as recommended by the systemd projects and allows it to use sd_notify to signal ready instead of reading a pid written to a file. It is now also restarted on failure.
The user version has been tested with KDE and works fine there.
The system-wide version runs, but I haven't actually used it and upstream does not recommend running in this mode.
GnuPG 2.1.x changed the way the gpg-agent works, and that new approach no
longer requires (or even supports) the "start everything as a child of the
agent" scheme we've implemented in NixOS for older versions.
To configure the gpg-agent for your X session, add the following code to
~/.xsession or some other appropriate place that's sourced at start-up:
gpg-connect-agent /bye
GPG_TTY=$(tty)
export GPG_TTY
If you want to use gpg-agent for SSH, too, also add the settings
unset SSH_AGENT_PID
export SSH_AUTH_SOCK="${HOME}/.gnupg/S.gpg-agent.ssh"
and make sure that
enable-ssh-support
is included in your ~/.gnupg/gpg-agent.conf.
The gpg-agent(1) man page has more details about this subject, i.e. in the
"EXAMPLES" section.
- Enforce that an option declaration has a "defaultText" if and only if the
type of the option derives from "package", "packageSet" or "nixpkgsConfig"
and if a "default" attribute is defined.
- Enforce that the value of the "example" attribute is wrapped with "literalExample"
if the type of the option derives from "package", "packageSet" or "nixpkgsConfig".
- Warn if a "defaultText" is defined in an option declaration if the type of
the option does not derive from "package", "packageSet" or "nixpkgsConfig".
- Warn if no "type" is defined in an option declaration.
Both Qt and GTK load plugins from the active profiles
automatically, so it is sufficient to install input methods
system-wide. Overriding the plugin paths may interfere with correct
operation of other plugins.
- Now `pkg.outputUnspecified = true` but this attribute is missing in
every output, so we can recognize whether the user chose or not.
If (s)he didn't choose, we put `pkg.bin or pkg.out or pkg` into
`systemPackages`.
- `outputsToLink` is replaced by `extraOutputsToLink`.
We add extra outputs *regardless* of whether the user chose anything.
It's mainly meant for outputs with docs and debug symbols.
- Note that as a result, some libraries will disappear from system path.
Set this option to 'true' (default: 'false') to enable extension mechanisms for
DNS (EDNS) in your local glibc resolver. This is required for supporting
DNSSEC, for example.
Implementation detail: the patch changes assignments to "resolv_conf_options"
to use "+=" instead of "=" to ensure that multiple users of that variable don't
overwrite each other. The generated config file is a shell script, after all,
so this should work fine.
Closes https://github.com/NixOS/nixpkgs/issues/12470.
- add missing types in module definitions
- add missing 'defaultText' in module definitions
- wrap example with 'literalExample' where necessary in module definitions
Sadly, we can't instruct systemd to properly restart device-name.swap when this service restarts (or I haven't found the way to do so). As of now blindly restarting it would only get you a bunch of errors about device already used -- let's avoid it.
The kernel default for `link_power_management_policy` is `"max_performance"`.
This commit:
f169f60575
set the NixOS default to `"min_performance"`.
This issue (https://github.com/NixOS/nixpkgs/issues/11276) details my long
journey to discover this after several file system failures incorrectly
attributed to `TRIM` and `NCQ` settings.
I think we should use the kernel default of `"max_performance"` to assure
the best experience for new users with SSDs and to conform to the defaults of
the kernel and other distros.
The most complex problems were from dealing with switches reverted in
the meantime (gcc5, gmp6, ncurses6).
It's likely that darwin is (still) broken nontrivially.
Option aliases/deprecations can now be declared in any NixOS module,
not just in nixos/modules/rename.nix. This is more modular (since it
allows for example grub-related aliases to be declared in the grub
module), and allows aliases outside of NixOS (e.g. in NixOps modules).
The syntax is a bit funky. Ideally we'd have something like:
options = {
foo.bar.newOption = mkOption { ... };
foo.bar.oldOption = mkAliasOption [ "foo" "bar" "newOption" ];
};
but that's not possible because options cannot define values in
*other* options - you need to have a "config" for that. So instead we
have functions that return a *module*: mkRemovedOptionModule,
mkRenamedOptionModule and mkAliasOptionModule. These can be used via
"imports", e.g.
imports = [
(mkAliasOptionModule [ "foo" "bar" "oldOption" ] [ "foo" "bar" "newOption" ]);
];
As an added bonus, deprecation warnings now show the file name of the
offending module.
Fixes#10385.
Trigger a restart of the post-resume.target on resume.
That allows other systemd services to receive the restart signal
after resume by becoming 'partOf' the post-resume.target.
This fixes#10077 because after some debugging it turns out that by
default we don't have a font which is able to display Chinese symbols.
Thanks to @anderspapitto, @kmicu and hyper_ch on IRC to help debugging
this issue, see log at:
http://nixos.org/irc/logs/log.20150926 starting at 19:46
With unifont we have a reasonable fallback font to ensure that every
written language is rendered correctly and thus less surprise for new
users who keep their font settings at the default.
Reported-by: Anders Papitto <anderspapitto@gmail.com>
Signed-off-by: aszlig <aszlig@redmoonstudios.org>
The previous default was $out/lib/debug, which wasn't very useful.
This ensures that you can do
environment.systemPackages = [ pkgs.hello.debug ];
to install debug info.
`man 1 info` says:
The first non-option argument, if present, is the menu entry to
start from; it is searched for in all `dir' files along INFOPATH.
If it is not present, info merges all `dir' files and shows the
result. Any remaining arguments are treated as the names of menu
items relative to the initial node visited.
Which means that this does what previous programs/info did and #8519
(on-the-fly infodir generation for Emacs) wanted to do, but for both
programs.
This improves error messages when a set or a list is used where a path
was expected. For an example, if you used a package set (as opposed to a
single package) in systemPackages before this commit, the error was:
```
cannot coerce a list to a string, at "/home/nixpkgs/lib/types.nix":103:37
```
Now, the error message reads:
```
The option value `environment.systemPackages' in `/etc/nixos/configuration.nix' is not a list of paths.
```
Fixes#9110. Fontconfig recommends different precedence for rendering
settings and generic alias settings. To comply with the recommendations,
`98-nixos.conf` has been separated into `10-nixos-rendering.conf` and
`60-nixos-generic-alias.conf`.
Fixes the useless collisions in the system path.
The 64bit and 32bit variants have the same files, hence
it's pointless to put the 32bit pulseaudio in systemPackages.
With the new evaluation of arguments, pkgs is now defined by the
configuration, which implies that option declaration with pkgs.lib
will cause an infinite loop.
The default configuration installed the Bitstream Vera fonts, but DejaVu
is a superior replacement, and the default Fontconfig settings need it
now for the generic faces monospace, sans-serif, and serif.
Details:
* The option `fonts.fontconfig.ultimate.enable` can be used to disable
the fontconfig-ultimate configuration.
* The user-configurable options provided by fontconfig-ultimate are
exposed in the NixOS module: `allowBitmaps` (default: true),
`allowType1` (default: false), `useEmbeddedBitmaps` (default: false),
`forceAutohint` (default: false), `renderMonoTTFAsBitmap` (default:
false).
* Upstream provides three substitution modes for substituting TrueType
fonts for Type 1 fonts (which do not render well). The default,
"free", substitutes free fonts for Type 1 fonts. The option "ms"
substitutions Microsoft fonts for Type 1 fonts. The option "combi"
uses a combination of Microsoft and free fonts. Substitutions can also
be disabled.
* All 21 of the Infinality rendering modes supported by fontconfig-ultimate
or by the original Infinality distribution can be selected through
`fonts.fontconfig.ultimate.rendering`. The default is the medium style
provided by fontconfig-ultimate. Any of the modes may be customized,
or Infinality rendering can be disabled entirely.
Details:
* The option `fonts.enableFontConfig` has (finally) been renamed
`fonts.fontconfig.enable`.
* Configurations are loaded in this order: first the Fontconfig-upstream
configuration is loaded, then the NixOS-specific font directories are
set, the system-wide default configuration is loaded, and finally the
user configuration is loaded (if enabled).
* The NixOS options `fonts.fontconfig.defaultFonts.monospace`,
`fonts.fontconfig.defaultFonts.sansSerif` and
`fonts.fontconfig.defaultFonts.serif` are added to allow setting the
default system-wide font used for these generic faces. The defaults
are the appropriate faces from the DejaVu collection because of their
comprehensive Unicode coverage, clean rendering, and excellent
legibility.
* The NixOS option `fonts.fontconfig.antialias` can be used to disable
antialiasing (it is enabled by default).
* The options `fonts.fontconfig.subpixel.rgba` and
`fonts.fontconfig.subpixel.lcdfilter` control the system-wide default
settings for subpixel order and LCD filtering algorithm,
respectively.
* `fonts.fontconfig.hinting.enable` can be used to disable TrueType font
hinting (it is enabled by default).
`fonts.fontconfig.hinting.autohint` controls the FreeType autohinter.
`fonts.fontconfig.hinting.style` controls the hint style; it is "full"
by default.
* User configurations can be disabled system-wide by setting
`fonts.fontconfig.includeUserConf = false`. They are enabled by
default so users can set Fontconfig options in the desktop environment
of their choice.
Following the discussion NixOS#5021:
- obsolete the nix.proxy option
- add the networking.proxy option
- open a default no_proxy environment variable
- add a rsync option
- Manual tests ok.
- Automatic tests ok.
Amended by lethalman to simplify the option descriptions.
This is needed when /etc/resolv.conf is being overriden by networkd
and other configurations. If the file is destroyed by an environment
activation then it must be rebuilt so that applications which interface
with /etc/resolv.conf directly don't break.
Perl seems to write the file in latin1 independent of the actual input
encoding. This can corrupt the "description" field of /etc/passwd. By
setting "binmode" to ":utf8" Perl can be forced to write UTF-8. Ideally
the program would simply read/write the fields by value without any
changes in encoding. However, assuming/enforcing UTF-8 is a lot better
than using an obsolete coding like latin1.
In this case, they're equivalent to setting ‘password’ and
‘hashedPassword’ (since there is no distinction between an initial and
non-initial user account state).
I.e. don't call "passwd" to update /etc/shadow from the "password"
option. This has the side-effect of not updating the password if
mutableUsers = true (since the code path for "hashedPassword" has a
check for mutableUsers).
Fixes#4747.
Any reasonably new version of fontconfig does search that path by default,
and setting this globally causes problems, as 2.10 and 2.11 need
incompatible configs.
Tested: slim+xfce desktop, chrootenv-ed steam.
I have no idea why we were setting the global variable;
e.g., neither Fedora nor Ubuntu does that.
Option defaults should not refer to store paths, because they cause
the manual to be rebuilt gratuitously. It's especially bad to refer to
a highly variable path like a computed configuration file.
