httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Stevenson <t...@pc-tony.com>
Subject Re: Patch for docs/manual/howto/ssi
Date Fri, 25 May 2007 13:24:36 GMT
Noirin,

Thanks for that, updated patch attached. 3rd time lucky, maybe?
Who knows, next time I may get it on the 1st or 2nd go.

:)


--
Tony


Noirin Plunkett wrote:
> On Fri, May 25, 2007 at 12:36:28PM +0100, Tony Stevenson wrote:
>   
>> Please find attached an updated patch file, there are few additional 
>> changes, a few stupid mistakes in the original.
>>     
>
> My suggestions follow inline. Just a few thoughts - and all my own
> opinion =)
> N
>
>   
>> --
>> -    <p>The decision of when to use SSI, and when to have your page
>> -    entirely generated by some program, is usually a matter of how
>> +    <p>The decision of when to use SSI, is usually a matter of how
>>      much of the page is static, and how much needs to be
>>     
>
> I'd leave this as it is in the original (perhaps changing 'some program'
> to 'some other program') - the new phrasing seems clumsy. If you want to
> keep the new phrasing, please lose the comma after SSI - it was a clause
> marker in the original, for a clause that's now gone =)
>
>   
>> -    do this. You can tell Apache to parse any file with a
>> +    do this. You can either tell Apache to parse any file with a
>>     
>
> I'm also not keen on this change. The 'or' is way too far away for an
> 'either' to make sense.
>
>   
>> -    add SSI directives to an existing page, you would have to
>> -    change the name of that page, and all links to that page, in
>> +    add SSI directives to any existing pages, you would have to
>> +    change the name of those pages, and all links to them, in
>>     
>
> change the names (unless all the pages have just one name, that they
> share between them)
>
>   
>> +    <p>You might occasionally see people recommending that you should 
>> +    configure Apache to parse all <code>.html</code> files for SSI,

>> +    so that you don't have to mess with <code>.shtml</code> file names.

>> +    These folks have perhaps not heard about the <directive 
>>      module="mod_include">XBitHack</directive>. The thing to
>>      keep in mind is that, by doing this, you're requiring that
>>     
>
> I'd also change the 'this' - it's not clear that 'this' refers to
> 'telling Apache to parse everything' rather than to 'XBitHack'.
>
>   
>> -    can slow things down quite a bit, and is not a good idea.</p>
>> +    can slow things down quite a bit, and is generally considered bad practice.</p>
>>  
>> +    <p>On Windows however, there is no such thing as an execute
>> +    bit, so that means you can only use the first method.</p>
>>     
>
> 'which means' (rather than 'so that means')
>
>   
>>      <p>If you don't like the format in which the date gets printed,
>>      you can use the <code>config</code> element, with a
>> -    <code>timefmt</code> attribute, to modify that formatting.</p>
>> +    <code>timefmt</code> attribute, to modify the formatting.</p>
>>     
>
> 'to modify it' or 'to modify that formatting' are better English =)
>
>   
>> -    <p>If you are managing any site that is more than a few pages,
>> -    you may find that making changes to all those pages can be a
>> -    real pain, particularly if you are trying to maintain some kind
>> +    <p>If you're managing any sites that are more than a few pages,
>> +    you may find that making changes to all those pages can be quite cumbersome,
>> +    particularly if you are trying to maintain some kind
>>      of standard look across all those pages.</p>
>>     
>
> 'you are' would be better than "you're", for consistency.
>
>   
>> -    but must be on the same server as the file being served.</p>
>> +    but this must be on the same server as the file being served.</p>
>>     
>
> I'd change the 'this must [...]' to 'must [...] in this case'
> personally, but it's just a minor style thing.
>
>   
>>      <p>Using the <code>set</code> directive, you can set variables
>> -    for later use. We'll need this later in the discussion, so
>> +    for later use. You'll need this later in the discussion, so
>>      we'll talk about it here. The syntax of this is as follows:</p>
>>     
>
> Consistency is good - I'd leave the "We'll" here.
>
>   
>>  
>> -    <p>Now that we have variables, and are able to set and compare
>> -    their values, we can use them to express conditionals. This
>> +    <p>Now that you're able to set and compare
>> +    variables and their values, you can use them to express conditionals. This
>>     
>
> I'd rephrase this as "Now that you are able to set and compare the
> values of variables" or similar - you're not really comparing the
> variables as such.
>
>   
>>  <example>
>>          &lt;!--#if expr="${Mac} &amp;&amp; ${InternetExplorer}" --&gt;<br
/>
>> -        Apologetic text goes here<br />
>> +        Text string 1 goes here<br />
>>          &lt;!--#else --&gt;<br />
>> -        Cool JavaScript code goes here<br />
>> +        Text string 2 goes here<br />
>>          &lt;!--#endif --&gt;
>>  </example>
>>     
>
> Actually, the old stuff, while potentially perjorative, is clearer, I
> think. Perhaps you could change it to "You're using Internet Explorer on
> a Mac" vs "You're not using Internet Explorer on a Mac"
>
> ...
>
> That's a pretty comprehensive patch, thanks again Tony =)
>
> Noirin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
>   

Mime
View raw message