From 7f87a23bf3139ff15d92d9b9fcd29c6e84e66726 Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Sun, 20 Jul 2008 18:02:10 -0400 Subject: --- doc/forum/perl5lib_and_wrappers.mdwn | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/forum/perl5lib_and_wrappers.mdwn b/doc/forum/perl5lib_and_wrappers.mdwn index 01570963c..cf14848f2 100644 --- a/doc/forum/perl5lib_and_wrappers.mdwn +++ b/doc/forum/perl5lib_and_wrappers.mdwn @@ -7,3 +7,5 @@ I don't know if I'm doing this right... I'm using a server provider that doesn' > > The [[tips/nearlyfreespeech]] tip has an example of doing this. > --[[Joey]] + +>> Thanks! I found that page, but didn't recognise the importance of INSTALL_BASE. -- cgit v1.2.3 From a90b80a679669c16f3ed444c8462e53fbd237b0e Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Sun, 20 Jul 2008 18:04:41 -0400 Subject: close --- doc/bugs/git_stderr_output_causes_problems.mdwn | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/bugs/git_stderr_output_causes_problems.mdwn b/doc/bugs/git_stderr_output_causes_problems.mdwn index 884f31154..4146a5869 100644 --- a/doc/bugs/git_stderr_output_causes_problems.mdwn +++ b/doc/bugs/git_stderr_output_causes_problems.mdwn @@ -37,3 +37,6 @@ Ikiwiki's git handling is sending a bunch of output to stderr. The following pa > It's unfortunate that git [abuses atderr](http://bugs.debian.org/447395), > outputting non-errors to it. That doesn't mean that git might not also > output actual error messages there. --[[Joey]] + +>> I'm happy with the wrapper script solution, so this is [[done]]. +>> And this report is now here to point others to that solution. -- cgit v1.2.3 From a29b111afb09668098cf441aecf92306fb3f4b83 Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Sun, 20 Jul 2008 18:17:20 -0400 Subject: reply --- doc/forum/Allow_overriding_of_symlink_restriction.mdwn | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/doc/forum/Allow_overriding_of_symlink_restriction.mdwn b/doc/forum/Allow_overriding_of_symlink_restriction.mdwn index eb86ef30f..f658f0cb3 100644 --- a/doc/forum/Allow_overriding_of_symlink_restriction.mdwn +++ b/doc/forum/Allow_overriding_of_symlink_restriction.mdwn @@ -15,6 +15,8 @@ The first appears to me to be less of a security issue. If there is a way for a > controlled directories could go down arbitrarily deep, down to the root of > the filesystem. --[[Joey]] +>> Fair point. + The current code seems to check this constraint at the top of IkiWiki/Render.pm at the start of refresh(). It seems to only check the source dir itself, not the subdirs. Then it uses File::Find to recuse which doesn't follow symlinks. Now my problem: I have a hosted server where I cannot avoid having a symlink in the source path. I've made a patch to optionally turn off the symlink checking in the source path itself. The patch would still not follow symlinks inside the source dir. This would seem to be ok security-wise for me as I know that path is ok and it isn't going to change on me. @@ -22,6 +24,8 @@ Now my problem: I have a hosted server where I cannot avoid having a symlink in > BTW, if you have a problem, please file it in [[todo]] or [[bugs]] in the > future. Especially if you also have a patch. :-) --[[Joey]] +>> Well, I was unsure I wasn't missing something. I wanted to discuss the concept of the patch as much as submit the patch. But, ok :) + Is there a huge objection to this patch? (note: patch inline - look at the source to get it. And I didn't re-indent the code when I added the if...) @@ -52,6 +56,8 @@ Is there a huge objection to this patch? > the `srcdir`. > --[[Joey]] +>> Ok, I'll try to get it cleaned up and documented. + There is a second location where this can be an issue. That is in the front of the wrapper. There the issue is that the path to the source dir as seen on the cgi server and on the git server are different - each has @@ -84,11 +90,17 @@ like this being accepted before I bothered. > ikiwiki uses absolute paths for `srcdir`, `destdir` and `this` because > the wrapper could be run from any location, and if any of them happen to > be a relative path, it would crash and burn. -> + +>> Which makes perfect sense. It is annoying that abs_path() is also +>> expanding symlinks. + > I think the thing to do might be to make it check if `srcdir` and > `destdir` look like an absolute path (ie, start with "/"). If so, it can > skip running `abs_path` on them. -> + +>> I'll do that. I assume something like File::Spec->file_name_is_absolute( $path ); would have more cross-platformy goodness. +>> hrm. I might see if File::Spec->rel2abs( $path ) ; will give absolute an path without expanding symlinks. + > I suppose you could do the same thing with `$this`, but it does not sound > like it has caused you problems anyway. > --[[Joey]] -- cgit v1.2.3 From d8d994b07c616e6f4891289aef0abcc4a8a6015e Mon Sep 17 00:00:00 2001 From: "http://www.openidfrance.fr/beaufils" Date: Sun, 20 Jul 2008 19:44:34 -0400 Subject: --- doc/todo/cas_authentication.mdwn | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 doc/todo/cas_authentication.mdwn diff --git a/doc/todo/cas_authentication.mdwn b/doc/todo/cas_authentication.mdwn new file mode 100644 index 000000000..73c0965ca --- /dev/null +++ b/doc/todo/cas_authentication.mdwn @@ -0,0 +1,7 @@ +ikiwiki should support [Central Authentication Service](http://www.ja-sig.org/products/cas/) authentication in order to use this SSO mechanism very popular in universities web services. + +I have already written a first draft plugin supporting that authentication mechanism. + +What is the best way to submit it to you ? + +--[[/users/bbb]] -- cgit v1.2.3 From 1a9ae3b241cfca845d238730e992fe02216cbac5 Mon Sep 17 00:00:00 2001 From: "http://www.openidfrance.fr/beaufils" Date: Sun, 20 Jul 2008 20:25:37 -0400 Subject: --- doc/todo/cas_authentication.mdwn | 142 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 139 insertions(+), 3 deletions(-) diff --git a/doc/todo/cas_authentication.mdwn b/doc/todo/cas_authentication.mdwn index 73c0965ca..5adbe1c39 100644 --- a/doc/todo/cas_authentication.mdwn +++ b/doc/todo/cas_authentication.mdwn @@ -1,7 +1,143 @@ -ikiwiki should support [Central Authentication Service](http://www.ja-sig.org/products/cas/) authentication in order to use this SSO mechanism very popular in universities web services. +[[!tag patch]] -I have already written a first draft plugin supporting that authentication mechanism. +ikiwiki should support [Central Authentication +Service](http://www.ja-sig.org/products/cas/) authentication in order to use +this SSO mechanism very popular in +universities web services. -What is the best way to submit it to you ? +I have already written a first draft plugin supporting that authentication +mechanism. It works for me with my university CAS service. I did not try it +with other CAS server but it do not see any reason why it should not work. + +What is the best way to submit it to you (just in case it can help my patch +follows) ? --[[/users/bbb]] + +------------------------------------------------------------------------------ + diff --git a/IkiWiki/Plugin/cas.pm b/IkiWiki/Plugin/cas.pm + new file mode 100644 + index 0000000..ea189df + --- /dev/null + +++ b/IkiWiki/Plugin/cas.pm + @@ -0,0 +1,94 @@ + +#!/usr/bin/perl + +# JaSIG CAS support by Bruno Beaufils + +package IkiWiki::Plugin::cas; + + + +use warnings; + +use strict; + +use IkiWiki 2.00; + +use AuthCAS; # http://search.cpan.org/~osalaun/AuthCAS-1.3.1/ + + + +sub import { #{{{ + + hook(type => "getopt", id => "cas", call => \&getopt); + + hook(type => "auth", id => "cas", call => \&auth); + + hook(type => "formbuilder_setup", id => "cas", call => \&formbuilder_setup); + +} # }}} + + + +# FIXME: We should check_config to ensure that : + +# * cas_url and ca_file are present + +# * no other auth plugin are present (at least passwordauth and openid) + + + +sub getopt () { #{{{ + + eval q{use Getopt::Long}; + + error($@) if $@; + + Getopt::Long::Configure('pass_through'); + + GetOptions("cas_url=s" => \$config{cas_url}); + + GetOptions("ca_file=s" => \$config{ca_file}); + +} #}}} + + + +sub auth ($$) { #{{{ + + my $q=shift; + + my $session=shift; + + + + my $cas = new AuthCAS(casUrl => $config{'cas'}{'cas_url'}, + + CAFile => $config{'cas'}{'ca_file'}); + + + + my $service = $config{'cgiurl'}; + + my $ticket = $q->param('ticket'); + + + + unless (defined($ticket)) { + + $service .= "?$ENV{QUERY_STRING}"; + + my $login_url = $cas->getServerLoginURL($service); + + debug("CAS: asking a Service Ticket for service $service"); + + IkiWiki::redirect($q, $login_url); + + exit 0; + + } else { + + $service = $service . "?$ENV{QUERY_STRING}"; + + $service =~ s/\&ticket=$ticket//; + + my $user = $cas->validateST($service, $ticket); + + if (defined $user) { + + debug("CAS: validating a Service Ticket ($ticket) for service $service"); + + $session->param(name=>$user); + + $session->param(CASservice=>$service); + + IkiWiki::cgi_savesession($session); + + } else { + + error("CAS failure: ".&AuthCAS::get_errors()); + + } + + } + +} #}}} + + + +# I use formbuilder_setup and not formbuilder type in order to bypass the + +# Logout processing done in IkiWiki::CGI::cgi_prefs() + +sub formbuilder_setup (@) { #{{{ + + my %params=@_; + + + + my $form=$params{form}; + + my $session=$params{session}; + + my $cgi=$params{cgi}; + + my $buttons=$params{buttons}; + + + + my $cas = new AuthCAS(casUrl => $config{'cas'}{'cas_url'}, + + CAFile => $config{'cas'}{'ca_file'}); + + + + if ($form->title eq "preferences") { + + # Show the login + + if (! defined $form->field(name => "name")) { + + $form->field(name => "CAS ID", + + disabled => 1, + + value => $session->param("name"), + + size => 50, + + force => 1, + + fieldset => "login"); + + } + + + + # Force a logout if asked + + if ($form->submitted && $form->submitted eq 'Logout') + + { + + debug("CAS: asking to remove the Ticket Grant Cookie"); + + IkiWiki::redirect($cgi, $cas->getServerLogoutURL($config{'url'})); + + $session->delete(); + + exit 0; + + } + + } + +} + + + +1 + diff --git a/doc/plugins/cas.mdwn b/doc/plugins/cas.mdwn + new file mode 100644 + index 0000000..2f2f53e + --- /dev/null + +++ b/doc/plugins/cas.mdwn + @@ -0,0 +1,18 @@ + +[[!template id=plugin name=cas core=0 author="[[bbb]]"]] + +[[!tag type/auth]] + + + +This plugin allows users to use authentication offered by a + +[JaSIG](http://www.ja-sig.org) [CAS](http://www.ja-sig.org/products/cas/) server to log + +into the wiki. + + + +The plugin needs the [[!cpan AuthCAS-1.3.1]] perl module. + + + +This plugin has two mandatory configuration option. You **must** set `--cas_url` + +to the url of a server offering CAS 2.0 authentication. You must also set the + +`--ca_file` to an absolute path to the file containing CA certificates used by + +the server (generally, aka under Debian, fixing that value to + +`/etc/ssl/certs/ca-certificates.crt` is sufficient). + + + +This plugin is not enabled by default. It can not be used with other + +authentication plugin, such as [[passwordauth]] or [[openid]]. + +------------------------------------------------------------------------------ -- cgit v1.2.3 From 359af8c197ae440ed4a979ab8486d3155f82e54e Mon Sep 17 00:00:00 2001 From: "http://www.openidfrance.fr/beaufils" Date: Sun, 20 Jul 2008 20:29:29 -0400 Subject: --- doc/todo/cas_authentication.mdwn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/todo/cas_authentication.mdwn b/doc/todo/cas_authentication.mdwn index 5adbe1c39..7e84b67e9 100644 --- a/doc/todo/cas_authentication.mdwn +++ b/doc/todo/cas_authentication.mdwn @@ -1,4 +1,4 @@ -[[!tag patch]] +[[!tag type/patch]] ikiwiki should support [Central Authentication Service](http://www.ja-sig.org/products/cas/) authentication in order to use -- cgit v1.2.3 From 45388ed356a3e7b88632bbf0f245527f36c43710 Mon Sep 17 00:00:00 2001 From: "http://www.openidfrance.fr/beaufils" Date: Sun, 20 Jul 2008 20:32:28 -0400 Subject: --- doc/todo/cas_authentication.mdwn | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/todo/cas_authentication.mdwn b/doc/todo/cas_authentication.mdwn index 7e84b67e9..1129b06ce 100644 --- a/doc/todo/cas_authentication.mdwn +++ b/doc/todo/cas_authentication.mdwn @@ -1,4 +1,4 @@ -[[!tag type/patch]] +[[!tag patch type/auth]] ikiwiki should support [Central Authentication Service](http://www.ja-sig.org/products/cas/) authentication in order to use @@ -121,8 +121,8 @@ follows) ? --- /dev/null +++ b/doc/plugins/cas.mdwn @@ -0,0 +1,18 @@ - +[[!template id=plugin name=cas core=0 author="[[bbb]]"]] - +[[!tag type/auth]] + +[[ template id=plugin name=cas core=0 author="[[bbb]]"]] + +[[ tag type/auth]] + +This plugin allows users to use authentication offered by a +[JaSIG](http://www.ja-sig.org) [>> be necessary to insert some sort of placeholder, perhaps by outputting +>>> the text in monospace form w/ a lighter font to denote that it won't +>>> directly be shown in the page... -- cgit v1.2.3 From 375f7e53513fcd3bd37e58243f5a1eda3705b435 Mon Sep 17 00:00:00 2001 From: "http://harningt.eharning.us/" Date: Mon, 21 Jul 2008 01:56:07 -0400 Subject: -- fix attr --- doc/todo/Add_showdown_GUI_input__47__edit.mdwn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/todo/Add_showdown_GUI_input__47__edit.mdwn b/doc/todo/Add_showdown_GUI_input__47__edit.mdwn index 56797696e..e864f5351 100644 --- a/doc/todo/Add_showdown_GUI_input__47__edit.mdwn +++ b/doc/todo/Add_showdown_GUI_input__47__edit.mdwn @@ -26,4 +26,4 @@ A demo is at >>> applying a 'real' preview would probably be difficult, so it'd probably >>> be necessary to insert some sort of placeholder, perhaps by outputting >>> the text in monospace form w/ a lighter font to denote that it won't ->>> directly be shown in the page... +>>> directly be shown in the page... -- [[harningt]] -- cgit v1.2.3 From 2cf143e6beb62add190beb4761b3591822820efa Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Mon, 21 Jul 2008 03:19:35 -0400 Subject: Change to new preprocessor syntax --- doc/plugins/map.mdwn | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/plugins/map.mdwn b/doc/plugins/map.mdwn index df34d77cd..472f62461 100644 --- a/doc/plugins/map.mdwn +++ b/doc/plugins/map.mdwn @@ -5,7 +5,7 @@ This plugin generates a hierarchical page map for the wiki. Example usage: - \[[map pages="* and !blog/* and !*/Discussion"]] + \[[!map pages="* and !blog/* and !*/Discussion"]] If the pages to include are not specified, all pages (and other files) in the wiki are mapped. @@ -14,7 +14,7 @@ By default, the names of pages are shown in the map. The `show` parameter can be used to show the titles or descriptions of pages instead (as set by the [[meta]] plugin). For example: - \[[map pages="* and !blog/* and !*/Discussion" show=title]] + \[[!map pages="* and !blog/* and !*/Discussion" show=title]] Hint: To limit the map to displaying pages less than a certain level deep, use a [[ikiwiki/PageSpec]] like this: `pages="* and !*/*/*"` @@ -22,5 +22,5 @@ use a [[ikiwiki/PageSpec]] like this: `pages="* and !*/*/*"` [[if test="enabled(map)" then=""" Here's an example map, for the plugins section of this wiki: -[[map pages="(plugins or plugins/*) and !*/*/*"]] +[[!map pages="(plugins or plugins/*) and !*/*/*"]] """]] -- cgit v1.2.3 From 7337b86d13b9cbf73c745712a1f98f695afa45e6 Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Mon, 21 Jul 2008 04:52:34 -0400 Subject: Update --- doc/forum/perl5lib_and_wrappers.mdwn | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/forum/perl5lib_and_wrappers.mdwn b/doc/forum/perl5lib_and_wrappers.mdwn index cf14848f2..83efc7cb5 100644 --- a/doc/forum/perl5lib_and_wrappers.mdwn +++ b/doc/forum/perl5lib_and_wrappers.mdwn @@ -9,3 +9,5 @@ I don't know if I'm doing this right... I'm using a server provider that doesn' > --[[Joey]] >> Thanks! I found that page, but didn't recognise the importance of INSTALL_BASE. + +>> It looks like INSTALL_BASE only appeared in version 6.31 of the Perl MakeMaker. My provider is still running version 6.30. Looks like I'll be keeping my patches for the moment... sigh. -- cgit v1.2.3 From fb24242bb4868396211bd502e2f753294ec57947 Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Mon, 21 Jul 2008 05:14:10 -0400 Subject: Updated patch --- .../Allow_overriding_of_symlink_restriction.mdwn | 43 +++++++++++++--------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/doc/forum/Allow_overriding_of_symlink_restriction.mdwn b/doc/forum/Allow_overriding_of_symlink_restriction.mdwn index f658f0cb3..0d93a28c1 100644 --- a/doc/forum/Allow_overriding_of_symlink_restriction.mdwn +++ b/doc/forum/Allow_overriding_of_symlink_restriction.mdwn @@ -68,24 +68,30 @@ patch fixes things. Again, patch inline. Again, this patch could be cleaned up :). I just wanted to see if there was any chance of a patch like this being accepted before I bothered. - diff --git a/IkiWiki/Wrapper.pm b/IkiWiki/Wrapper.pm - index 79b9eb3..e88118b 100644 - --- a/IkiWiki/Wrapper.pm - +++ b/IkiWiki/Wrapper.pm - @@ -9,9 +9,13 @@ use Data::Dumper; - use IkiWiki; - - sub gen_wrapper () { #{{{ - + my $this = $0; - + if ($config{allowsrcdirlinks}) { - + } else { - $config{srcdir}=abs_path($config{srcdir}); - $config{destdir}=abs_path($config{destdir}); - my $this=abs_path($0); - + } - if (! -x $this) { - error(sprintf(gettext("%s doesn't seem to be executable"), $this - } +>>> Patch updated: + + index 79b9eb3..ce1c395 100644 + --- a/IkiWiki/Wrapper.pm + +++ b/IkiWiki/Wrapper.pm + @@ -4,14 +4,14 @@ package IkiWiki; + + use warnings; + use strict; + -use Cwd q{abs_path}; + use Data::Dumper; + use IkiWiki; + +use File::Spec; + + sub gen_wrapper () { #{{{ + - $config{srcdir}=abs_path($config{srcdir}); + - $config{destdir}=abs_path($config{destdir}); + - my $this=abs_path($0); + + $config{srcdir}=File::Spec->rel2abs($config{srcdir}); + + $config{destdir}=File::Spec->rel2abs($config{destdir}); + + my $this=File::Spec->rel2abs($0); + if (! -x $this) { + error(sprintf(gettext("%s doesn't seem to be executable"), $this + } > ikiwiki uses absolute paths for `srcdir`, `destdir` and `this` because > the wrapper could be run from any location, and if any of them happen to @@ -100,6 +106,7 @@ like this being accepted before I bothered. >> I'll do that. I assume something like File::Spec->file_name_is_absolute( $path ); would have more cross-platformy goodness. >> hrm. I might see if File::Spec->rel2abs( $path ) ; will give absolute an path without expanding symlinks. +>>> Patch using rel2abs() works well - it no longer expands symlinks. > I suppose you could do the same thing with `$this`, but it does not sound > like it has caused you problems anyway. -- cgit v1.2.3 From 19d29f457639d045aa0a6f4e4766b9e96e9904d5 Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Mon, 21 Jul 2008 06:05:46 -0400 Subject: Update patch --- .../Allow_overriding_of_symlink_restriction.mdwn | 64 +++++++++++++++------- 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/doc/forum/Allow_overriding_of_symlink_restriction.mdwn b/doc/forum/Allow_overriding_of_symlink_restriction.mdwn index 0d93a28c1..bd94811df 100644 --- a/doc/forum/Allow_overriding_of_symlink_restriction.mdwn +++ b/doc/forum/Allow_overriding_of_symlink_restriction.mdwn @@ -28,26 +28,50 @@ Now my problem: I have a hosted server where I cannot avoid having a symlink in Is there a huge objection to this patch? -(note: patch inline - look at the source to get it. And I didn't re-indent the code when I added the if...) - - index 990fcaa..d7cb37e 100644 - --- a/IkiWiki/Render.pm - +++ b/IkiWiki/Render.pm - @@ -260,6 +260,7 @@ sub prune ($) { #{{{ - - sub refresh () { #{{{ - # security check, avoid following symlinks in the srcdir path - + if (! $config{allowsrcdirlinks}) { - my $test=$config{srcdir}; - while (length $test) { - if (-l $test) { - @@ -269,6 +270,7 @@ sub refresh () { #{{{ - $test=dirname($test); - } - } - + } - - run_hooks(refresh => sub { shift->() }); +>>> [[patch]] updated. + + diff --git a/IkiWiki/Render.pm b/IkiWiki/Render.pm + index 990fcaa..0fb78ba 100644 + --- a/IkiWiki/Render.pm + +++ b/IkiWiki/Render.pm + @@ -260,13 +260,15 @@ sub prune ($) { #{{{ + + sub refresh () { #{{{ + # security check, avoid following symlinks in the srcdir path + - my $test=$config{srcdir}; + - while (length $test) { + - if (-l $test) { + - error("symlink found in srcdir path ($test)"); + - } + - unless ($test=~s/\/+$//) { + - $test=dirname($test); + + if (! $config{allow_insecure_symlinks_in_path_to_srcdir}) { + + my $test=$config{srcdir}; + + while (length $test) { + + if (-l $test) { + + error("symlink found in srcdir path ($test)"); + + } + + unless ($test=~s/\/+$//) { + + $test=dirname($test); + + } + } + } + + diff --git a/doc/ikiwiki.setup b/doc/ikiwiki.setup + index 10cb3da..eb86e49 100644 + --- a/doc/ikiwiki.setup + +++ b/doc/ikiwiki.setup + @@ -203,4 +203,10 @@ use IkiWiki::Setup::Standard { + # For use with the attachment plugin, a program that returns + # nonzero if its standard input contains an virus. + #virus_checker => "clamdscan -", + + + + # The following setting allows symlinks in the path to your + + # srcdir. Symlinks are still not followed within srcdir. + + # Allowing symlinks to be followed, even in the path to srcdir, + + # will make some setups insecure. + + #allow_insecure_symlinks_in_path_to_srcdir => 0, + } > No, I don't have a big objection to such an option, as long as it's > extremely well documented that it will make many setups insecure. -- cgit v1.2.3 From 6153fd6d88fd41ee12a850652a6903a17ae9edda Mon Sep 17 00:00:00 2001 From: "http://www.cse.unsw.edu.au/~willu/" Date: Mon, 21 Jul 2008 06:26:20 -0400 Subject: Thoughts on example setup file --- doc/todo/Make_example_setup_file_consistent.mdwn | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 doc/todo/Make_example_setup_file_consistent.mdwn diff --git a/doc/todo/Make_example_setup_file_consistent.mdwn b/doc/todo/Make_example_setup_file_consistent.mdwn new file mode 100644 index 000000000..c4157816e --- /dev/null +++ b/doc/todo/Make_example_setup_file_consistent.mdwn @@ -0,0 +1,22 @@ +The current example [[ikiwiki.setup]] file has a number of options included, but commented out. This is standard. Unfortunately there are two standards for the settings of those commented out options: + + - Have the commented out options showing the default setting, or + - Have the commented out options showing the most common alternate setting. + +Each of these has its advantages. The first makes it clear what the default setting is. The second makes it easy to switch the option on -- you just uncomment the option. + +My issue with ikiwiki's example setup file is that it doesn't appear to be consistent. Looking at the 'svn' entries (the first set of rcs entries), we see that + + svnpath => "trunk", + +is an example of the first type, but + + rcs => "svn", + +is an example of the second type. + +I think things could be improved if a clear decision was made here. Most of the settings seem to be of the second type. Perhaps all that is needed is for settings of the first type to grow a comment: + + svnpath => "trunk", #default + +What do others think? -- cgit v1.2.3