Thoughts on example setup file
[ikiwiki.git] / doc / todo / Make_example_setup_file_consistent.mdwn
1 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:
2
3   - Have the commented out options showing the default setting, or
4   - Have the commented out options showing the most common alternate setting.
5
6 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.
7
8 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
9
10     svnpath => "trunk",
11
12 is an example of the first type, but 
13
14     rcs => "svn",
15
16 is an example of the second type.
17
18 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:
19
20     svnpath => "trunk",        #default
21
22 What do others think?