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).

    ikiwiki --setup $setupfile

Didn't work as expected, rebuilt the whole wiki.

    ikiwiki -setup -refresh $setupfile

Output was:

    cannot read -refresh: No such file or directory
    usage: ikiwiki [options] source dest
           ikiwiki --setup configfile

So it was clear: *first* refresh, *then* setup -- and so

    ikiwiki -refresh -setup $setupfile

finally did what I wanted.

## situation

1.) The manpage says:

       --refresh
              Refresh the wiki, updating any changed pages. This is the
              default behavior so you don't normally need to specify it.
       --setup setupfile
              The default action when --setup is specified is to automatically
              generate wrappers for a wiki based on data in a setup file, and
              rebuild the wiki.  If you only want to build any changed pages,
              you can use --refresh with --setup.

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.

2.) after building the wiki with the list of directories the install script says:

    To modify settings, edit ~/ikiwiki/$wikiname.setup and then run:
            ikiwiki -setup ~/ikiwiki/$wikiname.setup

2.a) It is the only place where *-setup* is used. the error output and the manpage use *--setup*  
2.b) It should also say how to rebuild the wiki by creating *only* the new and changed pages.

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. 

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.

## conclusion

1.) The text for *--refresh* should be updated.  
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*  
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.

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).

*P.S.: HOWTO sign?*

--[[EdePopede]]