"Walter Bright" <newshound2@digitalmars.com> wrote in message news:jesifv$2sm9$1@digitalmars.com...
>
> ---------------------
> giving you powerful compile-time code generation abilities that'll make your code cleaner, more flexible and even more ecient.
>
> =>
>
> giving powerful compile-time code generation abilities that'll make code cleaner, more flexible and even more ecient.
> ------------------------

This particular one, I honestly think the "before" sounds better.  But I do agree with...the poster to whom this author is replying to...on the other examples.

On 01/14/2012 09:14 PM, Andrei Alexandrescu wrote:
> Since we're on this topic I can't stop picking - all in good fun I hope
> - on Jonathan, the master of words. The following two sentences convey
> the same exact information:
>
> 1.
>
>> There are certainly times when reducing how much "you" is used reduces
>> the
>> amount of text at no extra cost, but there are other times, when it's
>> far more
>> natural to use "you," and it can become harder to produce sentences
>> without
>> completely reworking that section of text if "you" is removed.
>
> 2.
>
>> Sure, it can reduce the word count, but I
>> really don't think that it does all that much to improve the quality
>> of the
>> text, and it can require quite a bit more work, since it tends to be
>> unnatural
>> to avoid "you" in the way that technical writers like to.
>
> This pattern is quite frequent in Jonathan's posts. I trained myself to
> skip the last sentence of each paragraph and often the last paragraph
> entirely.
>
>
> Andrei
>

In longer posts, I think the information is often laid out in an approximately palindromic way.

"Philippe Sigaud" <philippe.sigaud@gmail.com> wrote in message news:mailman.374.1326575051.16222.digitalmars-d-announce@puremagic.com...
> On Sat, Jan 14, 2012 at 21:07, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:
>> On 1/14/12 5:21 AM, Philippe Sigaud wrote:
>>>
>>> Uh, I don't think it'll ever be a book. I didn't write it with a book in mind.
>>
>>
>> It's organized as a book (TOC, index, structure) and has 141 pages with
>> quite a few more to come. At this point it would be more difficult to
>> make
>> it /not/ a book.
>
> Fair point :)
>
> In my mind, a book is at least 300 pages and, well, professionally done. I can see Walter's point about ebook though.
>

I have plenty of physical books that are shorter than that!

On 1/14/2012 1:00 PM, Nick Sabalausky wrote:
> "Walter Bright"<newshound2@digitalmars.com>  wrote in message
> news:jesl4i$30v3$1@digitalmars.com...
>>
>> You and I are going to disagree on this.
>>
>
> Dosn't the reader mean "The reader and I are going to disagree on this"? ;)
> (only j/k, of course. Although I have always hated when authors say "the
> reader" instead of "you" which is what was obviously meant anyway. I just
> sounds bad. I always read it as a clear sign the author was trying *way* too
> hard to be "correct".)

I agree with your comment about "the reader" being pretentious.

As for my use of "you" there, I was talking specifically to Jonathan. That's different from writing a tech manual. Wearing jeans is appropriate in a conversation.

>> But I will add that excessive use of "you" in technically minded books
>> tends to, in my mind, reduce the book a grade in quality.
>
> The key there is "excessive use", not "any use". Eliminating excessive use
> of "you" certainly improves the quality. But compulsively eliminating "you",
> at best, makes the text sound pedantic, at worst, decreases the quality.
> Either way, compulsively eliminating it leads to pointless contrivances and
> awkward euphemisms like "the reader".

The steps are:

Novice: follow the rules because you're told to

Master: follow the rules because you understand the rules

Guru: break the rules because you know the limits of the rules

On 1/14/2012 1:09 PM, Timon Gehr wrote:
> In longer posts, I think the information is often laid out in an approximately
> palindromic way.

We're not in Notlob, you know.

On Sat, Jan 14, 2012 at 14:56, Zachary Lund <admin@computerquip.com> wrote:
> On page 78 where template mixins are discussed, some of the variable names feel rather confusing. I would suggest changing them to be more distinct.

OK, done. Tell me if it's better?

On Sat, Jan 14, 2012 at 16:56, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:
> On 1/13/12 3:20 PM, Philippe Sigaud wrote:

> "They are used everywhere in Phobos, D standard library and any D user should know about them." -> "They are used everywhere in Phobos---D's standard library---and therefore any D user should know about them."

Done.

> "But, based on C++’s templates as they are, they can be a bit daunting at first." -> "But, based on C++’s templates as they are, D templates can be a bit daunting at first."

Done.

> "Well, D’s sane syntax for templates, nifty things like static if, alias or tuples cured me of that impression." -> "Well, D’s sane syntax for templates and nifty features such as static if, alias, or tuples, cured me of that impression." (Generally prefer "such as" to "like".)

Done.

> "I hope this docu- ment will help you also." -> "I hope this docu- ment will help you, too."

Done.

> "Part III presents other metaprogramming tools: string mixins (18), compile-
> time function evaluation (19) and __traits (20)." -> "Part III presents
> other metaprogramming tools: string mixins (18), compile- time function
> evaluation (19), and __traits (20)." (Use the "Oxford comma" throughout.)

Done (well, not the Oxford comma)

> "template-y" -> "\mbox{template-y}"

Done.

> I think italics for comments look a bit baroque, how about slanted text?

pygments/minted do not do slanted. I modifyed my own "borland.py" to get non-slanted comments. Anyone generating the pdf from the .tex files will get another highlighting, though.


> "...in the next sections (You’ll see for example..." -> "...in the next sections (you’ll see for example..."

Done.

> "... except inside a (standard) function." -> "except inside a (regular)
> function."

Done.

> Would be great to adjust the code formatting package to not number examples of 1 line long.

Done. Now, only code samples where I refer to some lines are numbered.

> "Templates Building Blocks" -> "Template Building Blocks"

Done.

> "Up to now, templates must seem not that interesting to you..." -> "Up to now, templates may not seem all that interesting..."

Done.

> "It’s both an expression and a declaration, so I’ll call it a construct." ->
> "It’s both a statement and a declaration, so I’ll call it a construct." In
> fact you can call it a declaration because some declarations may occur
> wherever a statement is allowed.

Done.

Thanks for the comments!

On Sat, Jan 14, 2012 at 17:00, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:
> On 1/14/12 9:56 AM, Andrei Alexandrescu wrote:
> [snip]
>
> Oh, one more thing. It would be great to make the explanatory boxes either floats, sidebars, or \mbox{}es so they don't span more than one page. Look what happened with "Specializations or static if or Templates Constraints?" on page 21.

OK, done.

I (re)learnt some things about LaTeX spaces, boxes and lengths in the
process *shudder*

On 01/14/2012 12:14 PM, Andrei Alexandrescu wrote:
> Since we're on this topic I can't stop picking - all in good fun I hope
> - on Jonathan, the master of words. The following two sentences convey
> the same exact information:
>
> 1.
>
>> There are certainly times when reducing how much "you" is used reduces
>> the
>> amount of text at no extra cost, but there are other times, when it's
>> far more
>> natural to use "you," and it can become harder to produce sentences
>> without
>> completely reworking that section of text if "you" is removed.
>
> 2.
>
>> Sure, it can reduce the word count, but I
>> really don't think that it does all that much to improve the quality
>> of the
>> text, and it can require quite a bit more work, since it tends to be
>> unnatural
>> to avoid "you" in the way that technical writers like to.
>
> This pattern is quite frequent in Jonathan's posts. I trained myself to
> skip the last sentence of each paragraph and often the last paragraph
> entirely.
>
>
> Andrei
>

I've always wanted to say the same but I couldn't be sure that I wouldn't be offensive. Now, hiding behind Andrei:

+1 :)

Ali

On 1/14/12 3:04 PM, Philippe Sigaud wrote:
> On Sat, Jan 14, 2012 at 21:07, Andrei Alexandrescu
> <SeeWebsiteForEmail@erdani.org>  wrote:
>> On 1/14/12 5:21 AM, Philippe Sigaud wrote:
>>>
>>> Uh, I don't think it'll ever be a book. I didn't write it with a book in
>>> mind.
>>
>>
>> It's organized as a book (TOC, index, structure) and has 141 pages with
>> quite a few more to come. At this point it would be more difficult to make
>> it /not/ a book.
>
> Fair point :)
>
> In my mind, a book is at least 300 pages and, well, professionally
> done. I can see Walter's point about ebook though.
>
> Thank you all for the encouragements!

Great. With the publishing world undergoing quite some stir, I think it would be very interesting to experience with self-publishing via Kindle.

FWIW about 300 - not at all. "Exceptional C++" has 206 pages head to toe and is a great book. In fact 300 is probably a good upper limit in today's short-attention-span world.


Andrei