document aggregateinternal

diff --git a/doc/ikiwiki-transition.mdwn b/doc/ikiwiki-transition.mdwn
index 693c1db832472f85d3fc6823197b6970082dec2a..624268d23b6c49c9a5fea73baefb5962c826f295 100644 (file)
--- a/doc/ikiwiki-transition.mdwn
+++ b/doc/ikiwiki-transition.mdwn
@@ -25,6 +25,11 @@ Note that if the page contains wiki links with spaces, which some
 older versions of ikiwiki accepted, the prefix_directives transition will
 treat these as preprocessor directives and convert them.
 
 older versions of ikiwiki accepted, the prefix_directives transition will
 treat these as preprocessor directives and convert them.
 

+# aggregateinternal
+
+The `aggregateinternal` mode moves pages aggregated by the aggregate plugin
+so that the `aggregateinternal` option can be endabled 
+

 # indexdb
 
 The `indexdb` mode handles converting a plain text `.ikiwiki/index` file to
 # indexdb
 
 The `indexdb` mode handles converting a plain text `.ikiwiki/index` file to

diff --git a/doc/ikiwiki.setup b/doc/ikiwiki.setup
index 6d327fd9861d298cda18b5aaefa74d6a35854922..140216c19d0be549d488e70ff6301efa51ee82a3 100644 (file)
--- a/doc/ikiwiki.setup
+++ b/doc/ikiwiki.setup
@@ -174,8 +174,11 @@ use IkiWiki::Setup::Standard {
        # pages anonymous users can edit
        #anonok_pagespec => "*",
        
        # pages anonymous users can edit
        #anonok_pagespec => "*",
        

-       # For use with the aggregate plugin, to allow aggregation to be
-       # triggered via the web.
+       # For use with the aggregate plugin.
+       # Enable aggregation to internal pages. Read aggregate plugin docs
+       # before enabling.
+       #aggregateinternal => 1,
+       # Allow aggregation to be triggered via the web.

        #aggregate_webtrigger => 1,
        
        # For use with the pinger plugin, how many seconds to wait before
        #aggregate_webtrigger => 1,
        
        # For use with the pinger plugin, how many seconds to wait before

diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn
index 574c8b125e9486e3433a89711eddd4ebbab03fb0..21a8105d06308958c68a02719965198d11796aa2 100644 (file)
--- a/doc/plugins/aggregate.mdwn
+++ b/doc/plugins/aggregate.mdwn
@@ -2,9 +2,9 @@
 [[tag type/useful]]
 
 This plugin allows content from other feeds to be aggregated into the wiki.
 [[tag type/useful]]
 
 This plugin allows content from other feeds to be aggregated into the wiki.

-Aggregate a feed as follows
+Aggregate a feed as follows:

 
 

-       \[[aggregate name="example blog"
+       \[[aggregate name="example blog" dir="example"

        feedurl="http://example.com/index.rss"
        url="http://example.com/" updateinterval="15"]]
 
        feedurl="http://example.com/index.rss"
        url="http://example.com/" updateinterval="15"]]
 


@@ -13,7 +13,9 @@ more frequently than once every 15 minutes, and puts a page per post under
 the example/ directory in the wiki.
 
 You can then use ikiwiki's [[ikiwiki/blog]] support to create a blog of one or
 the example/ directory in the wiki.
 
 You can then use ikiwiki's [[ikiwiki/blog]] support to create a blog of one or

-more aggregated feeds.
+more aggregated feeds. For example:
+
+       \[[inline pages="internal(example/*)"]]

 
 ## setup
 
 
 ## setup
 


@@ -31,7 +33,7 @@ crontab entry:
 Alternatively, you can allow `ikiwiki.cgi` to trigger the aggregation. You
 should only need this if for some reason you cannot use cron, and instead
 want to use a service such as [WebCron](http://webcron.org). To enable
 Alternatively, you can allow `ikiwiki.cgi` to trigger the aggregation. You
 should only need this if for some reason you cannot use cron, and instead
 want to use a service such as [WebCron](http://webcron.org). To enable

-this, enable on `aggregate_webtrigger` in your setup file. The url to
+this, turn on `aggregate_webtrigger` in your setup file. The url to

 visit is `http://whatever/ikiwiki.cgi?do=aggregate_webtrigger`. Anyone
 can visit the url to trigger an aggregation run, but it will only check
 each feed if its `updateinterval` has passed.
 visit is `http://whatever/ikiwiki.cgi?do=aggregate_webtrigger`. Anyone
 can visit the url to trigger an aggregation run, but it will only check
 each feed if its `updateinterval` has passed.


@@ -59,9 +61,40 @@ directive:
 * `tag` - A tag to tag each post from the feed with. A good tag to use is
   the name of the feed. Can be repeated multiple times. The [[tag]] plugin
   must be enabled for this to work.
 * `tag` - A tag to tag each post from the feed with. A good tag to use is
   the name of the feed. Can be repeated multiple times. The [[tag]] plugin
   must be enabled for this to work.

-* `template` - Template to use for creating the html pages. Defaults to
+* `template` - Template to use for creating the aggregated pages. Defaults to

   aggregatepost.
 
 Note that even if you are using subversion or another revision control
 system, pages created by aggregation will *not* be checked into revision
 control.
   aggregatepost.
 
 Note that even if you are using subversion or another revision control
 system, pages created by aggregation will *not* be checked into revision
 control.

+
+## internal pages
+
+This plugin creates a page for each aggregated item. 
+
+Currently, by default, these pages have the ".html" extension, and are
+first-class wiki pages -- which allows them to be inlined into blogs
+and even edited.
+
+That turns out to not be ideal for aggregated content, because publishing
+files for each of those pages is a waste of disk space and CPU, and you probably
+don't want to allow them to be edited. So, there is an alternate method
+that can be used, turned on by the `aggregateinternal` option in the setup
+file.
+
+If `aggregateinternal` is enabled, aggregated pages are stored in the source
+directory with a "._aggregate" extension. These pages cannot be edited by
+web users, and do not generate first-class wiki pages. They can only be
+inlined into a blog.
+
+If you are already using aggregate and want to enable `aggregateinternal`,
+you should follow this process:
+
+1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated
+   pages -- such as those in inlines. Put "internal()" around globs 
+   in those PageSpecs. For example, if the PageSpec was "foo/*", it should
+   be changed to "internal(foo/*)". This has to be done because internal
+   pages are not matched by regular globs.
+2. Use [[ikiwiki-transition]] to move all existing aggregated `.html`
+   files. The command to run is `ikiwiki-transition aggregateinternal $srcdir`
+3. Turn on `aggregateinternal` in the setup file and rebuild the wiki.

diff --git a/doc/roadmap.mdwn b/doc/roadmap.mdwn
index af46e162be7f89ab3efb33dc5dc96f1c0b3343ce..32752715d8fe4b1f2c50219227ff396c50884080 100644 (file)
--- a/doc/roadmap.mdwn
+++ b/doc/roadmap.mdwn
@@ -42,7 +42,8 @@ backwards compatability.
 Still in the early planning stages, version 3.0 will be an opportunity to
 make significant transitions.
 
 Still in the early planning stages, version 3.0 will be an opportunity to
 make significant transitions.
 

-* Default to using prefix_directives.
+* Default to using `prefix_directives`.
+* Default to using `aggregateinternal`.

 
 ----
 
 
 ----