View mode: basic / threaded / horizontal-split · Log in · Help
January 14, 2012
Re: A tutorial on D templates
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
January 14, 2012
Re: A tutorial on D templates
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?
January 14, 2012
Re: A tutorial on D templates
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
January 14, 2012
Re: A tutorial on D templates
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.
January 14, 2012
Re: A tutorial on D templates
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).
January 14, 2012
Re: A tutorial on D templates
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.
January 14, 2012
Re: A tutorial on D 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
January 14, 2012
Re: A tutorial on D templates
Counter-argument: You can't make a pull request to a book. Just take a
look at the mountain of errata entries for tdpl.
January 14, 2012
Re: A tutorial on D templates
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.
January 14, 2012
Re: A tutorial on D templates
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.
1 2 3 4 5 6
Top | Discussion index | About this forum | D home