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?
  23
  24 > I agree, and I'll take a patch.
  25 >
  26 > I may not work on it myself, since I have some
  27 > [[interesting_ideas|online_configuration]] that would let ikiwiki
  28 > generate a setup file for you, rather than having to keep maintain the
  29 > current example.
  30 >
  31 > And.. [[done]].. setup files are now generated with `--dumpsetup`, based on
  32 > the built-in defaults, and commented options show an example
  33 > setting, not a default. --[[Joey]]