aboutsummaryrefslogtreecommitdiff
path: root/doc/todo/Make_example_setup_file_consistent.mdwn
blob: 54cc34af6a3fe9a2fe91849ff8506cacd425aa59 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
The current example ikiwiki.setup file has a number of options included, but commented out.  This is standard.  Unfortunately there are two standards for the settings of those commented out options:

  - Have the commented out options showing the default setting, or
  - Have the commented out options showing the most common alternate setting.

Each of these has its advantages.  The first makes it clear what the default setting is.  The second makes it easy to switch the option on -- you just uncomment the option.

My issue with ikiwiki's example setup file is that it doesn't appear to be consistent.  Looking at the 'svn' entries (the first set of rcs entries), we see that

    svnpath => "trunk",

is an example of the first type, but 

    rcs => "svn",

is an example of the second type.

I think things could be improved if a clear decision was made here.  Most of the settings seem to be of the second type.  Perhaps all that is needed is for settings of the first type to grow a comment:

    svnpath => "trunk",        #default

What do others think?

> I agree, and I'll take a patch.
> 
> I may not work on it myself, since I have some
> [[interesting_ideas|online_configuration]] that would let ikiwiki
> generate a setup file for you, rather than having to keep maintain the
> current example. 
> 
> And.. [[done]].. setup files are now generated with `--dumpsetup`, based on
> the built-in defaults, and commented options show an example
> setting, not a default. --[[Joey]]