I'm working on an asciidoc plugin and having a problem figuring out how to deal with usedirs.
One of the key reasons I use asciidoc is for the ability to do inline includes of scripts with syntax-highlighting. I also want the script to be linked from the page for easy downloading.
Formerly, I would have had the asciidoc and the script in the same directory, and all was well (and I have my asciidoc plugin working just fine for this). With usedirs, the script needs to be in the same dir as the asciidoc source at render time, but in the newly created subdir for download. The problem is that the page effectively moves down by one directory level when it is rendered from the source to the html tree.
As far as my needs are concerned, there is no problem - I can just run without usedirs - but it would be nice to find a solution that would work either way. Just a clean solution to usedirs would be fine (even if it doesn't work without usedirs), since usedirs is now the default.
OK, now that I've written this out, I see a solution. The include for the syntax-highlighting and the link to the script are not tightly coupled (in fact they're not coupled at all, except by the person writing the page). So, the solution under usedirs is to specify a current-dir link to the script for the syntax-highlighter, and a parent-dir link for the script. This could even be made conditional on usedirs being enabled, if one felt so inclined.
I'll leave this ramble here in case anyone has anything to say about it. Thank you for listening 
-- KarlMW
This may serve only to highlight my naivete, but what are the advantages of the usedirs approach? I'm not passionately against the option, and I'm confident that there must be benefits for it to have become the default in ikiwiki - I just don't understand why.
It seems to me that the only advantage is slightly tidier URLs, but with the disadvantage that source files change dir level and relative links need to change too.
-- KarlMW
The cleaner urls seem worth it to me. The urlto() function makes it easy
for ikiwiki code to deal with the path changes. --Joey
when migrating to usedirs, the following apache config sniplet might be useful (use inside the Directory section that manages your wiki):
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.+)\.html$ /my_base_path/$1/ [R]
that sniplet causes redirects from any non-existing .html file to the respective usedirs directory. (when serving from the host root url, drop the my_base_path part, otherwise adapt it to your needs).
i recommend using this or a similar mechanism to keep your old urls reachable.
--chrysn