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.


Andrei

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.

I hesitated on this. OK, I'll try, I made it an issue.

Do you think code samples should be floats also, so as not to sit on more than on page?

On Sat, Jan 14, 2012 at 16:56, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:
> On 1/13/12 3:20 PM, Philippe Sigaud wrote:
>>
>>
>> https://github.com/PhilippeSigaud/D-templates-tutorial/blob/master/dtemplates.pdf
>>
>> (click on View Raw)
>>
>> If you have any comment, criticism, explanation, what have you, I'm game.
>
>
> This is great! Should I post to reddit, or hold off a bit more?

I'd prefer you to wait a bit, because I think I didn't some code samples and they either do not compile or produce different results. That'd badly reflect on D.

Maybe I'll write a small script to extract code samples and compile them. Do you have anything like this for TPDL?

I have a problem with implicit main() and/or presenting in one sample
code that should be in the global scope and some that must be put into
a main.
I wondered whether I should present only 'compile-as-shown' examples,
which means putting import statements and void main() {/* some code
*/} everywhere.

>
> The document is informative, well written, and beautifully formatted. I found the introduction a bit difficult to get into, so I'm submitting a few suggestions below. I didn't have time to get through everything, but anyway the quality of the text improves very much once it gets into the material.

Thanks for the compliments and thanks for the suggestions!
Indeed, the introductory text was not my main goal while writing this :)

I also discovered something you explained when you were writing TDPL: it's difficult to find interesting examples that don't use soon-to-be-introduced features.

(snip corrections).

Thanks a lot, I'll make them issues and correct this.


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

I asked myself the same question. I'll dive into pygment's formatting script.


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

I tried to get two different D environments, one with numbered lines (only when I want to refer to a line, that's less than 5% of all code samples) and an unnumbered one, but it didn't work. I'll try again.

Philippe

On 1/14/2012 12:36 AM, Jonathan M Davis wrote:
> I confess that it's a bit of a pet peeve of mine when people insist on
> avoiding words like you and your. I completely disagree that it's a problem.
> And there are times where avoiding it can cause problems and make the text
> more awkward (though it is true that you can often avoid it fairly easily if
> you really want to).

(though it is true that it can be avoided fairly easily)

Fixed that for you. What advantage does the "you" version have, besides upping the word count?


> But I know that there are plenty of technical writers who would agree with
> you.

I cannot recall any professional technical book that used "you" (yes, I'm sure you can find an example!). It's like wearing jeans to a wedding.

On 1/14/2012 3:21 AM, Philippe Sigaud wrote:
>> I strongly encourage you to continue with it, and release it as a book. We
>> could sure use another book on D!
>
> Uh, I don't think it'll ever be a book. I didn't write it with a book in mind.

It looks like a book, and I see no reason why it can't be. It'll see far wider distribution as a book.


>> I strongly suggest making the formatting work for a Kindle edition of your
>> book. PDF files do badly on e-readers.
>
> What I want (maybe in 1-2 months) is to write a simple D script that
> takes the .tex files and transform them into simple marked-up text, to
> produce a DDoc file or an HTML one.

Kindle ebooks can be automatically generated from HTML text with the kindlegen.exe program downloadable from Amazon. I have the D specification automatically "kindle-izable" in the makefile for dlang.org.

The main issue is the short line length, which negatively impacts examples and tables.

Another issue is Kindle is black & white, so while the colored text does make it better, it should still be usable if rendered in black & white (which should be done anyway, as many people are color blind).

On 1/14/2012 7:05 AM, Jeff Nowakowski wrote:
> On 01/14/2012 03:16 AM, Walter Bright wrote:
>>
>> Minor stylistic nit pet peeve of mine: please remove the word "you" and
>> "your" from the prose.
>
> That sounds a bit strict, and looking at one of your articles I see it used in
> the second sentence: "A pure function does what you'd expect — the compiler
> enforces purity of the function."

What can I say? Ya got me there. I do tend to write "you", and remove them in a later pass.

But let's take some examples from the first page of the text, and see if the elidition looks better:

---------------------
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.
------------------------
its material doesn’t so much teach you how to use templates as show you their syntax and semantics.

=>

its material doesn’t so much teach how to use templates as show their syntax and semantics.
-----------------------
the standard ‘building blocks’ you'll use in almost all your templates,

=>

the standard ‘building blocks’ used in almost all templates,
-----------------------
and what you can build with them in conjunction with templates.

=>

and what can be built with them in conjunction with templates.

On Saturday, January 14, 2012 10:26:22 Walter Bright wrote:
> On 1/14/2012 12:36 AM, Jonathan M Davis wrote:
> > I confess that it's a bit of a pet peeve of mine when people insist on avoiding words like you and your. I completely disagree that it's a problem. And there are times where avoiding it can cause problems and make the text more awkward (though it is true that you can often avoid it fairly easily if you really want to).
> 
> (though it is true that it can be avoided fairly easily)
> 
> Fixed that for you. What advantage does the "you" version have, besides upping the word count?

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. And honestly, it just seems overly picky to me. 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.

- Jonathan M Davis

Counter-argument: You can't make a pull request to a book. Just take a look at the mountain of errata entries for tdpl.

On 1/14/2012 11:00 AM, Jonathan M Davis wrote:
> 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. And honestly,
> it just seems overly picky to me. 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.

You and I are going to disagree on this.

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. This is not a decision I consciously make, it's just that it doesn't read like a professional technical book would. In fact, it took me a while to figure out why I didn't find certain texts to be professional sounding.

Like I said, it's like wearing jeans to a wedding. It doesn't matter how nice the jeans are, or that jeans are appropriate in other contexts. It doesn't matter how you feel about it.

Strunk & White's "The Elements of Style" rule 17: Omit Needless Words

> and it can require quite a bit more work,

This is not an issue. The whole of the document can be fixed in a handful of minutes.

On 1/14/2012 11:03 AM, Andrej Mitrovic wrote:
> Counter-argument: You can't make a pull request to a book. Just take a
> look at the mountain of errata entries for tdpl.

Ebooks can be fixed easily. Print books cannot.