httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noirin Plunkett <noi...@apache.org>
Subject Re: Patch for docs/manual/howto/ssi
Date Fri, 25 May 2007 12:48:57 GMT
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