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

I can't quite work out why the usage/man page is incorrect. It looks like it has been incorrect since it was added in this commit ffc0be87d7eca4de4dbc91d740d36b7b40bfa911.
Comment by cbaines Sat Feb 28 15:15:18 2015
ikiwiki --setup $setupfile

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

The default action is to rebuild if --setup is used, or refresh otherwise.

ikiwiki -setup -refresh $setupfile

Output was:

cannot read -refresh: No such file or directory

Well, no, you told ikiwiki to use a setup file named -refresh. That's not going to work, unless you happen to have such a file. The man page does say

   --setup setupfile

implying that an argument is expected and required. Either of these would be OK, for instance:

ikiwiki -refresh -setup setupfile
ikiwiki --setup setupfile --refresh

2.a) It is the only place where -setup is used. the error output and the manpage use --setup

Perl's command-line parser accepts either.

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.

That's because the one used for the auto-installation (which is not mandatory: you can write the entire setup file yourself if you prefer, like ikiwiki-hosting does) is a special case of the one used for a configured wiki./

And maybe it would be possible to update a wiki if the program is called with only a config file as parameter.

ikiwiki needs either:

  • two non-option arguments, a srcdir and a destdir (and probably lots of other options in practice); or

  • a setup file (which can specify most things supported by the command line) and no non-option arguments

Both ways are meant to work; the srcdir/destdir syntax is for very simple cases (e.g. building static documentation) and the setup file is for more complicated cases (entire websites).

Treating two non-option arguments as srcdir/destdir, but a single non-option argument as a setup file, seems more confusing to me than the current situation.

Comment by smcv Sun Mar 1 11:13:08 2015