[Cross-posted with D.learn, since it's also a learning-related post]

Hello all,

I discovered D a few years ago and, seeing the recent increase in community projects, I looked for a way to bring my own small part to it.

I quite like D templates and wanted to try LaTeX again, so I decided to bite the bullet and wrote a tutorial on templates. It's far from finished and most probably full of mistakes but since it's already quite big, I need some inputs.

It's a Github project, here:

https://github.com/PhilippeSigaud/D-templates-tutorial

The resulting pdf is there:

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. What section should be expanded, what example would be cool, etc. If you see a mistake, do not hesitate to tell me: it's the first time I put thoughts on paper like this. Github issues management is far from perfect, but it's usable. Even better would be pull requests :)

There is an 'Examples' section where I show what can be done with templates and there I 'borrowed' some code posted here, with attribution. I already exchanged with Andrej Mitrovic (thanks!), but also took some code from Timon Gehr, Simen Kjaeraas, Trass3r and Jacob Carlborg. Guys, if any of you have a problem with that, tell me so and I'll take down the code of course. But if any of you could give me some explanation (a small paragraph or two?) about what your code does, I'll be forever grateful :)

This also extend to anyone who would want to share some template love/lore with the rest of us.

Philippe

Philippe Sigaud:

> https://github.com/PhilippeSigaud/D-templates-tutorial/blob/master/dtemplates.pdf
> 
> (click on View Raw)

I am using a pdf blocking plug-in, that causes that GitHub link to save a fake pdf file :-(

Is your tutorial containing the (a,b) => a * b syntax too?

I'd like operators in your text to have a space around:
a * b
instead of
a*b
(Unless the space is finishing on the line).

In my opinion
foo!q{ a * b }
Is more readable than:
foo!"a*b"

Bye,
bearophile

On Fri, Jan 13, 2012 at 23:07, bearophile <bearophileHUGS@lycos.com> wrote:
> Philippe Sigaud:
>
>> https://github.com/PhilippeSigaud/D-templates-tutorial/blob/master/dtemplates.pdf
>>
>> (click on View Raw)
>
> I am using a pdf blocking plug-in, that causes that GitHub link to save a fake pdf file :-(

On the main project page, there is a Zip icon on the left, to download the entire project as a zip, pdf included.

Of course, if you've git installed:

$ git clone git@github.com:PhilippeSigaud/D-Template-Tutorial.git

should do the trick.


> Is your tutorial containing the (a,b) => a * b syntax too?

A bit. I began in september and had to change bits due to D
evolutions:) (CTFE opening new possibilities and this new syntax).
But I still have many things to change, and I didn't explain this syntax.

If you want to discuss the text, I propose we do it on D.learn, so as not to pollute D.announce too much.

Philippe

On 1/13/2012 1:20 PM, Philippe Sigaud wrote:
> This also extend to anyone who would want to share some template love/lore with
> the rest of us.

I see you've already done a great deal of work on this, it looks nice! I strongly encourage you to continue with it, and release it as a book. We could sure use another book on D!

I strongly suggest making the formatting work for a Kindle edition of your book. PDF files do badly on e-readers.

Minor stylistic nit pet peeve of mine: please remove the word "you" and "your" from the prose. It's nearly always redundant, and the sentences flow better without it. "You" is a filler word, similar to "um", "like", and "basically".

For example,

Like, I basically think that you will basically prefer the, um, text once basically you, like, remove basically them, like, ok. Know what I'm saying?

   =>

The text will look better without them.

:-)

On Saturday, January 14, 2012 00:16:37 Walter Bright wrote:
> On 1/13/2012 1:20 PM, Philippe Sigaud wrote:
> > This also extend to anyone who would want to share some template love/lore with the rest of us.
> 
> I see you've already done a great deal of work on this, it looks nice! I strongly encourage you to continue with it, and release it as a book. We could sure use another book on D!
> 
> I strongly suggest making the formatting work for a Kindle edition of your book. PDF files do badly on e-readers.
> 
> Minor stylistic nit pet peeve of mine: please remove the word "you" and "your" from the prose. It's nearly always redundant, and the sentences flow better without it. "You" is a filler word, similar to "um", "like", and "basically".
> 
> For example,
> 
> Like, I basically think that you will basically prefer the, um, text once basically you, like, remove basically them, like, ok. Know what I'm saying?
> 
>     =>
> 
> The text will look better without them.
> 
> :-)

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).

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

- Jonathan M Davis

On Sat, Jan 14, 2012 at 09:16, Walter Bright <newshound2@digitalmars.com> wrote:
> On 1/13/2012 1:20 PM, Philippe Sigaud wrote:
>>
>> This also extend to anyone who would want to share some template love/lore
>> with
>> the rest of us.
>
>
> I see you've already done a great deal of work on this, it looks nice!

Thanks. LaTeX work, mostly. At one time, I asked Andrei for the latex formatting functions used in TDPL, but he was authorized to distribute it. That would permit D docs to get TDPL look & feel.

> 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.



> 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.


Is there any tex -> <whatever format ebooks use> or pdf -> ebook converters?


> Minor stylistic nit pet peeve of mine: please remove the word "you" and "your" from the prose. It's nearly always redundant, and the sentences flow better without it. "You" is a filler word, similar to "um", "like", and "basically".

I'll look and try.

Philippe

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.

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, added as an issue.

You mean all the 'name', 'Named', 'named'?

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."

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?

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.

"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."

"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."

"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".)

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

"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.)

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

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

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

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

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

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

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

"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.



Andrei