View mode: basic / threaded / horizontal-split · Log in · Help
January 13, 2012
A tutorial on D templates
[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
January 13, 2012
Re: A tutorial on D templates
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
January 14, 2012
Re: A tutorial on D templates
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
January 14, 2012
Re: A tutorial on D templates
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.

:-)
January 14, 2012
Re: A tutorial on D templates
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
January 14, 2012
Re: A tutorial on D templates
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
January 14, 2012
Re: A tutorial on D templates
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.
January 14, 2012
Re: A tutorial on D templates
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'?
January 14, 2012
Re: A tutorial on D templates
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."
January 14, 2012
Re: A tutorial on D templates
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
« First   ‹ Prev
1 2 3 4 5
Top | Discussion index | About this forum | D home