analysis of how autofile and autoindex differ

[git.ikiwiki.info.git] / doc / todo / transient_pages.mdwn

diff --git a/doc/todo/transient_pages.mdwn b/doc/todo/transient_pages.mdwn
index 642114d974ad5601b6c6a2d5fa50705b5d36ecde..e1f84969e0afd1508521e2bae9f363cbad9089aa 100644 (file)
--- a/doc/todo/transient_pages.mdwn
+++ b/doc/todo/transient_pages.mdwn
@@ -15,46 +15,171 @@ This would also be useful for autoindex, as suggested on
 [[plugins/autoindex/discussion]]. I'd also like to use it for
 [[plugins/contrib/album]].
 
 [[plugins/autoindex/discussion]]. I'd also like to use it for
 [[plugins/contrib/album]].
 

-One refinement I'd suggest is that if the transient page is edited,
-its transient contents are evaluated and used as the initial
-content for the edit box; after that, it'd become a static page. --[[smcv]]
+It could also be used for an [[todo/alias_directive]].
+
+--[[smcv]]

 
 --------------------------
 
 
 --------------------------
 

-[[!template id=gitbranch branch=smcv/ready/transient author="[[smcv]]"]]
+[[!template id=gitbranch branch=smcv/transient-only author="[[smcv]]"]]
+[[!template id=gitbranch branch=smcv/transient-recentchanges author="[[smcv]]"]]

 [[!tag patch]]
 
 I think this branch is now enough to be useful. It adds the following:
 
 If the `transient` plugin is loaded, `$srcdir/.ikiwiki/transient` is added
 [[!tag patch]]
 
 I think this branch is now enough to be useful. It adds the following:
 
 If the `transient` plugin is loaded, `$srcdir/.ikiwiki/transient` is added

-as an underlay.
+as an underlay. I'm not sure whether this should be a plugin or core, so
+I erred on the side of more plugins; I think it's "on the edge of the core",
+like goto.

 
 Pages with the default extension in the transient underlay are automatically
 deleted if a page of the same name is created in the srcdir (or an underlay
 closer to the srcdir in stacking order).
 
 
 Pages with the default extension in the transient underlay are automatically
 deleted if a page of the same name is created in the srcdir (or an underlay
 closer to the srcdir in stacking order).
 

+With the additional `transient-tag` branch,

 `tag` enables `transient`, and if `tag_autocreate_commit` is set to 0
 (default 1), autocreated tags are written to the transient underlay.
 `tag` enables `transient`, and if `tag_autocreate_commit` is set to 0
 (default 1), autocreated tags are written to the transient underlay.

+There is a regression test.

 
 

+With the additional `transient-autoindex` branch,

 `autoindex` uses autofiles. It also enables `transient`, and if
 `autoindex_commit` is set to 0 (default 1), autoindexes are written to
 `autoindex` uses autofiles. It also enables `transient`, and if
 `autoindex_commit` is set to 0 (default 1), autoindexes are written to

-the transient underlay.
+the transient underlay. There is a regression test.
+
+> I wonder why this needs to be configurable? I suppose that gets back to
+> whether it makes sense to check these files in or not. The benefits of 
+> checking them in:
+> 
+> * You can edit them from the VCS, don't have to go into the web
+>   interface. Of course, files from the underlays have a similar issue,
+>   but does it make sense to make that wart larger?
+> * You can know you can build the same site with nothing missing
+>   even if you don't there enable autoindex or whatever. (Edge case.)
+
+>> I'm not sure that that's a huge wart; you can always "edit by
+>> overwriting". If you're running a local clone of the wiki on your laptop
+>> or whatever, you have the underlays already, and can copy from there.
+>> Tag and autoindex pages have rather simple source code anyway. --s
+
+> The benefit of using transient pages seems to just be avoiding commit
+> clutter? For files that are never committed, transient pages are a clear
+> win, but I wonder if adding configuration clutter just to avoid some 
+> commit clutter is really worth it.
+
+>> According to the last section of
+>> [[todo/auto-create_tag_pages_according_to_a_template]], chrysn and
+>> Eric both feel rather strongly that it should be possible to
+>> not commit any tags. I made it configurable because, as you point out,
+>> there are also reasons why it makes sense to check these
+>> automatically-created files in. I'm neutral on this, personally.
+>>
+>> If this is a point of contention, would you accept a branch that
+>> just adds `transient` and uses it for [[plugins/recentchanges]],
+>> which aren't checked in and never have been? I've split the
+>> branch up in the hope that *some* of it can get merged.
+>>
+>> One potentially relevant point is that configuration clutter only
+>> affects the site admin whereas commit clutter is part of the whole
+>> wiki's history. --[[smcv]]
+
+> Anyway, the configurability
+> appears subtly broken; the default is only 1 if a new setup file is
+> generated. With an existing setup file, the 'default' values in
+> `getsetup` don't take effect, so it will default to undef, which
+> is treated the same as 0. --[[Joey]]
+
+>> Fixed in the branches, hopefully. (How disruptive would it be to have
+>> defaults take effect whenever the setup file doesn't set a value, btw?
+>> It seems pretty astonishing to have them work as they do at the moment.) --s

 
 autoindex ignores pages in the transient underlay when deciding whether
 to generate an index.
 
 
 autoindex ignores pages in the transient underlay when deciding whether
 to generate an index.
 

-Not done yet:
+With the additional `transient-recentchanges` branch, new recent changes
+go in the transient underlay; I tested this manually.
+
+Not done yet (in that branch, at least):
+
+* `remove` can't remove transient pages: this turns out to be harder than
+  I'd hoped, because I don't want to introduce a vulnerability in the
+  non-regular-file detection, so I'd rather defer that.
+
+  > Hmm, I'd at least want that to be dealt with before this was used
+  > by default for autoindex or tag. --[[Joey]]
+
+  >> I'll try to work out which of the checks are required for security
+  >> and which are just nice-to-have, but I'd appreciate any pointers
+  >> you could give. Note that my branch wasn't meant to enable either
+  >> by default, and now hopefully doesn't. --[[smcv]]
+
+* Transient tags that don't match any pages aren't deleted: I'm not sure
+  that that's a good idea anyway, though. Similarly, transient autoindexes
+  of directories that become empty aren't deleted.
+
+  > Doesn't seem necessary, or really desirable to do that. --[[Joey]]
+
+  >> Good, that was my inclination too. --s

 
 

-`remove` can't remove transient pages: this turns out to be harder than
-I'd hoped, because I don't want to introduce a vulnerability in the
-non-regular-file detection...
+* In my `untested/transient` branch, new aggregated files go in the
+  transient underlay too (they'll naturally migrate over time). I haven't
+  tested this yet, it's just a proof-of-concept.

 
 

-Transient tags that don't match any pages aren't deleted: I'm not sure
-that that's a good idea anyway, though. Similarly, transient autoindexes
-of directories that become empty aren't deleted.
+> I can confirm that the behavior of autoindex, at least, is excellent.
+> Haven't tried tag. Joey, can you merge transient and autoindex? --JoeRayhawk

 
 

-Recent changes and aggregated files could conceivably go in the transient
-underlay too.
+>> Here are some other things I'd like to think about first: --[[Joey]] 
+>>
+>> * There's a FIXME in autoindex.
+
+>>> Right, the extra logic for preventing autoindex pages from being
+>>> re-created. This is taking a while, so I'm going to leave out the
+>>>> autoindex part for the moment. The FIXME is only relevant
+>>>> because I tried to solve
+>>>> [[todo/autoindex should use add__95__autofile]] first, but
+>>>> strictly speaking, that's an orthogonal change. --s
+
+>> * Suggest making recentchanges unlink the transient page
+>>   first, and only unlink from the old location if it wasn't
+>>   in the transient location. Ok, it only saves 1 syscall :)
+
+>>> Is an unlink() really that expensive? But, OK, fixed in the
+>>> `transient-recentchanges` branch. --s
+
+>> * Similarly it's a bit worrying for performance that it
+>>   needs to pull in and use `Cwd` on every ikiwiki startup now.
+>>   I really don't see the need; `wikistatedir` should
+>>   mostly be absolute, and ikiwiki should not chdir in ways
+>>   that break it anyway.
+
+>>> The reason to make it absolute is that relative underlays
+>>> are interpreted as relative to the base underlay directory,
+>>> not the cwd.
+>>>
+>>> The updated `transient-only` branch only loads `Cwd` if
+>>> the path is relative; an extra commit on branch
+>>> `smcv/transient-relative` goes behind `add_underlay`'s
+>>> back to allow use of a cwd-relative underlay. Which direction
+>>> would you prefer?
+>>>
+>>> I note in passing that [[plugins/autoindex]] and `IkiWiki::Render`
+>>> both need to use `Cwd` and `File::Find` on every refresh, so
+>>> there's only any point in avoiding `Cwd` for runs that don't
+>>> actually refresh, like simple uses of the CGI. --s
+
+>> * Unsure about the use of `default_pageext` in the `change`
+>>   hook. Is everything in the transientdir really going
+>>   to use that pageext? Would it be better to look up the
+>>   complete source filename?
+
+>>> At the moment everything in the transientdir will either
+>>> have the `default_pageext` or be internal, although I
+>>> did wonder whether to make [[plugins/contrib/album]]
+>>> viewer pages optionally be `html`, for better performance
+>>> when there's a very large number of photos.
+>>>
+>>> A more thorough garbage-collection mechanism would be to
+>>> use File::Find on the transient directory; I'll get there
+>>> eventually. --s

 
 --------------------------
 
 
 --------------------------