doc/forum/refresh_and_setup.mdwn

   1 I found the handling of options and terms regarding both actions highly confusing from the very beginning some weeks ago. so i created a bash function used as *iki $wikiname* that called *ikiwiki* with the needed parameters and the complete pathname of the apropriate configuration file. Only now that shell is gone and the function lost. So I had to find that command again (remember, I didn't used it for weeks).
   2
   3     ikiwiki --setup $setupfile
   4
   5 Didn't work as expected, rebuilt the whole wiki.
   6
   7     ikiwiki -setup -refresh $setupfile
   8
   9 Output was:
  10
  11     cannot read -refresh: No such file or directory
  12     usage: ikiwiki [options] source dest
  13            ikiwiki --setup configfile
  14
  15 So it was clear: *first* refresh, *then* setup -- and so
  16
  17     ikiwiki -refresh -setup $setupfile
  18
  19 finally did what I wanted.
  20
  21 ## situation
  22
  23 1.) The manpage says:
  24
  25        --refresh
  26               Refresh the wiki, updating any changed pages. This is the
  27               default behavior so you don't normally need to specify it.
  28        --setup setupfile
  29               The default action when --setup is specified is to automatically
  30               generate wrappers for a wiki based on data in a setup file, and
  31               rebuild the wiki.  If you only want to build any changed pages,
  32               you can use --refresh with --setup.
  33
  34 Only, both *ikiwiki* and *ikiwiki $setupfile* spit out an error. So it seems i **MUST** use *--refresh* to do a refresh. but I also have to use *--setup $setupfile* because ikiwiki **NEEDS** a config file, but only one of those two options take one.
  35
  36 2.) after building the wiki with the list of directories the install script says:
  37
  38     To modify settings, edit ~/ikiwiki/$wikiname.setup and then run:
  39             ikiwiki -setup ~/ikiwiki/$wikiname.setup
  40
  41 2.a) It is the only place where *-setup* is used. the error output and the manpage use *--setup*
  42 2.b) It should also say how to rebuild the wiki by creating *only* the new and changed pages.
  43
  44 3.) The file with the basic settings for the installation procedure is referred to as "setup" file. And so are the files with the settings for a particular wiki. Only the manpage uses the term "configuration" more than just a few times.
  45
  46 And maybe it would be possible to update a wiki if the program is called with only a config file as parameter. the mass-rebuild aproach doesn't work for me, a wiki in a user directory is not part of system stucture and so i don't use my root account for anything besides basic installation.
  47
  48 ## conclusion
  49
  50 1.) The text for *--refresh* should be updated.
  51 2.) Short and long options should be clearly distinguishable (and also if 1 or 2 hyphens may be used). So the line *--refresh* in the man page could e.g. read *-r --refresh*
  52 3.) I'd suggest using "setup" for the file(s) shipped with the software thatare used to create (then so to be called) configuration files with the settings for particular wiki instances.
  53
  54 I also adapted the install script so it doen's clutter my home directory. As for now it still creates *~/.ikiwiki* (useless for me, maybe there could be a setup option not to do it?) but all the rest goes into the same directory (setup file, and the config file and the directory for each instance).
  55
  56 *P.S.: HOWTO sign?*
  57
  58 --[[EdePopede]]