Re: Where to change comments to configuration files

[Ferdinand Soethe <sa...@soethe.net>]

Ross Gardler wrote:

RG> Best to change it in all occurances of the file as people could look at
RG> any of the official Apache docs for guidance.

Added info to files in fresh-site and site author. I'd rather not
do this in the future but instead prefer for us to agree that we will
maintain the 'nice' documented version of files in fresh site since
doing everything twice seems such a waste of time.

RG> As I mentioned on the user list - be sure to add info abot how to change
RG> this behaviour too. This is not a limitation that is rigid. in design.

Have not added this to the comment for now because there seems to be
no easy answer to the point where it is in fact rigid. I'll attach
more info on that to the relevant thread.

--
Ferdinand Soethe

Re: Comment on index.html (Re: Where to change comments to configuration files)

[Thorsten Scherler <th...@apache.org>]

On Tue, 2005-05-03 at 09:49 +0100, Ross Gardler wrote:
> Ferdinand Soethe wrote:
> >...
> > I disagree here. It might have been ok to just leave it before we knew
> > about the inconsistencies it will create if you don't use index.html.
> 
> As far as I am aware the only inconsistency is that the index page 
> credits will no longer work. Thorsten has already said this is fixed in 
> views and I have said it is easy to fix in skins if my existing 
> suggestions are tested and prove to be correct.

Yeah it is *very easy*:
1 have a look at pelts site2xhtml.xsl and search for $filename =
'index.html'
2 at into the fresh site skinconf something like <credit
filename="some.html"/> (and extend the dtd!)
3 change all results from 1 to $filename=$config/credits/@filename

That's it. ;-) 

HTH
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: To change or not to changing threads ( Re: Comment on index.html (Re: Where to change comments to configuration files))

[Ross Gardler <rg...@apache.org>]

Nicola Ken Barozzi wrote:
> Ferdinand Soethe wrote:

...

> Believe me, as I have already suffered consequences from my bad habit of 
> sending quick mails ;-)

Absolutely, we have all been there (and I still go there unfortunately).

One of my blog entries describes how I *try* and manage the horrible 
flourish of email that Open Source often brings.

http://www.jroller.com/page/rgardler/20050328#ten_tips_for_increasing_your

(its more than 10 now - if you have any favourite tips I'd love to hear 
them)

Ross

Re: To change or not to changing threads ( Re: Comment on index.html (Re: Where to change comments to configuration files))

[Nicola Ken Barozzi <ni...@apache.org>]

Ferdinand Soethe wrote:
...
> My problem is not different threads but the temptation of sending instant
> replies. I just needed to take the time, read all new stuff and then
> respond to avoid this.

Instant replies also tend to lower the signal2noise ratio, can create 
tensions in case of important discussions, make it easy to mistakenly 
send a private letter to public, and make mails less polished and 
difficult to understand. As a general case, waiting some time will 
always help, and also ease the personal tension. Updating mail once a 
day or at most hourly also helps.

Believe me, as I have already suffered consequences from my bad habit of 
sending quick mails ;-)

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------

To change or not to changing threads ( Re: Comment on index.html (Re: Where to change comments to configuration files))

[Ferdinand Soethe <sa...@soethe.net>]

In 'Re: Comment on index.html (Re: Where to change comments to
configuration files)'
Ross Gardler wrote:

FS> Sorry, I shouldn't respond to messages one by one. That way I missed
FS> your solution in 'Re: Inkonsistency in implementation of default file
FS> and site.xml and what to do about it' when I wrote my reply.

RG> One of the reasons for keeping everything in one thread. This particular
RG> issue spanned three different threads because of subject changes. It's
RG> sometimes very difficult to know when to change the subject. I always
RG> try not too unless I have totally changed the direction the thread is
RG> taking.

I've started to move discussions to a new thread as soon as the topic
changes significantly. The main reason being that in searching the
archives I have often come across loooong threads that touched the
subject I was looking for once and then discussed something else for
the next 100 messages. And since you can't be sure you have to read
carefully through all of them.

I also like the fact that I can clearly see that a threat is moving on
to something else (perhaps something I'm not interested in) so that I
don't need to follow this new thread.

At least that's the theorie.

My problem is not different threads but the temptation of sending instant
replies. I just needed to take the time, read all new stuff and then
respond to avoid this.

--
Ferdinand Soethe

Re: Comment on index.html (Re: Where to change comments to configuration files)

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 
> RG> But that simply is not correct. It *is* configurable as I have written
> RG> on a number of occasions now.
> 
> Sorry, I shouldn't respond to messages one by one. That way I missed
> your solution in 'Re: Inkonsistency in implementation of default file
> and site.xml and what to do about it' when I wrote my reply.

One of the reasons for keeping everything in one thread. This particular 
issue spanned three different threads because of subject changes. It's 
sometimes very difficult to know when to change the subject. I always 
try not too unless I have totally changed the direction the thread is 
taking.

> Will adjust documentation accordingly.

I saw that - it's great to see someone actually documenting what is 
discussed here.

Thanks!!!

Ross

Re: Comment on index.html (Re: Where to change comments to configuration files)

[Ferdinand Soethe <sa...@soethe.net>]

Ross Gardler wrote:

RG> But that simply is not correct. It *is* configurable as I have written
RG> on a number of occasions now.

Sorry, I shouldn't respond to messages one by one. That way I missed
your solution in 'Re: Inkonsistency in implementation of default file
and site.xml and what to do about it' when I wrote my reply.

Will adjust documentation accordingly.

--
Ferdinand Soethe

Re: Comment on index.html (Re: Where to change comments to configuration files)

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> 
> 
> 
> Ross Gardler wrote:
> 
> (about this comment
> 
> FS> <!-- Note: No matter what you configure here, Forrest will always try to load
> FS>        index.html when you request http://yourHost/
> FS> -->>
> )
> 
> RG> I'm -1 on the current comment as it gives the impression that it *can't*
> RG> be changed. This is bad. If someone needs to change it and they read
> RG> that comment then they will not bother to search the docs/ask on the
> RG> mailing lists.
> 
> RG> In my opinion it's better to have something undocumented (and therefore
> RG> prompt questions) than to have it incorrectly documented.
> 
> I disagree here. It might have been ok to just leave it before we knew
> about the inconsistencies it will create if you don't use index.html.

As far as I am aware the only inconsistency is that the index page 
credits will no longer work. Thorsten has already said this is fixed in 
views and I have said it is easy to fix in skins if my existing 
suggestions are tested and prove to be correct.

> Taking the comment out, people will just fall into the trap and perhaps
> not even know until the put their site on a server.

I'm not -1 on the comment, only -1 on the current wording. My issue is 
that it gives the false impression that it is not a configurable feature.

> I feel that inquisitive minds will stumple about the comment and come
> back asking for the reasons behind this or ways around this anyway.

In my experience users don't ask questions if something is written in 
the docs. Potential devs might, but users don't.

> In fact, thinking about it, I'd probably extend that comment to tell
> you that you have to have an index.html in the root for things to work
> properly.

But that simply is not correct. It *is* configurable as I have written 
on a number of occasions now.

> Apart from that:
> 
> Putting sufficient info to explain the whole situation into that
> comment will take perhaps 20 lines. That is a bit much for my taste.
> If it is not, I'll happily add that.

So put a link to a document that provides those twenty lines.

> Or I could either add a line to refer people to this thread or write
> up a short faq that sums up the facts about changing index.html and
> refer to that.

FAQ's are good.

Ross

Comment on index.html (Re: Where to change comments to configuration files)

[Ferdinand Soethe <sa...@soethe.net>]

Ross Gardler wrote:

(about this comment

FS> <!-- Note: No matter what you configure here, Forrest will always try to load
FS>        index.html when you request http://yourHost/
FS> -->>
)

RG> I'm -1 on the current comment as it gives the impression that it *can't*
RG> be changed. This is bad. If someone needs to change it and they read
RG> that comment then they will not bother to search the docs/ask on the
RG> mailing lists.

RG> In my opinion it's better to have something undocumented (and therefore
RG> prompt questions) than to have it incorrectly documented.

I disagree here. It might have been ok to just leave it before we knew
about the inconsistencies it will create if you don't use index.html.

But knowing that and only having learned about this by accident feels
a bit like leaving a big hole in the street uncovered and smashing the
streetlight.

Taking the comment out, people will just fall into the trap and perhaps
not even know until the put their site on a server.

I feel that inquisitive minds will stumple about the comment and come
back asking for the reasons behind this or ways around this anyway.
They'll benefit but won't be stopped. But those who want to use
Forrest without knowing the details will get a clear message.

In fact, thinking about it, I'd probably extend that comment to tell
you that you have to have an index.html in the root for things to work
properly.


Apart from that:

Putting sufficient info to explain the whole situation into that
comment will take perhaps 20 lines. That is a bit much for my taste.
If it is not, I'll happily add that.

Or I could either add a line to refer people to this thread or write
up a short faq that sums up the facts about changing index.html and
refer to that.

wdyt

--
Ferdinand Soethe

Re: Where to change comments to configuration files

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 
> RG> Best to change it in all occurances of the file as people could look at
> RG> any of the official Apache docs for guidance.
> 
> Added info to files in fresh-site and site author. I'd rather not
> do this in the future but instead prefer for us to agree that we will
> maintain the 'nice' documented version of files in fresh site since
> doing everything twice seems such a waste of time.

With search and replace across multiple files it's easy, as long as we 
ensure that the text in each file is identical (which it will be if we 
use search and replace tools).

However, I do agree that there is an overhead here.

> RG> As I mentioned on the user list - be sure to add info abot how to change
> RG> this behaviour too. This is not a limitation that is rigid. in design.
> 
> Have not added this to the comment for now because there seems to be
> no easy answer to the point where it is in fact rigid. I'll attach
> more info on that to the relevant thread.

I'm -1 on the current comment as it gives the impression that it *can't* 
be changed. This is bad. If someone needs to change it and they read 
that comment then they will not bother to search the docs/ask on the 
mailing lists.

In my opinion it's better to have something undocumented (and therefore 
prompt questions) than to have it incorrectly documented.

Ross