On Saturday, January 14, 2012 11:30:25 Walter Bright wrote:
> You and I are going to disagree on this.

I didn't really expect otherwise.

- Jonathan M Davis

On 1/14/12 10:57 AM, Philippe Sigaud wrote:
> 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?

Code samples should be able to span multiple pages. Never heard a complaint about it. In contrast, the explanatory boxes are a sort of a unit.


Andrei

On 1/14/12 11:08 AM, Philippe Sigaud wrote:
> 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?

Emailed.

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

Yah, I defined several LaTeX environments and a little syntax for that. I also arranged to ignore "..." when it appears alone on a line. Overall it was an effort well worth it.

> I wondered whether I should present only 'compile-as-shown' examples,
> which means putting import statements and void main() {/* some code
> */} everywhere.

Define distinct environments for stuff that must be top level vs. stuff that must be wrapped in main or unittest.


Andrei

On 1/14/12 12:26 PM, 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?
>
>
>> 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.

"You" can convey a conversational, intimate tone that can be helpful. Together with "I" for the author and "we" as the author plus the reader, "you" can create quite a good frame.

That being said, I agree - "you" is a license that should be at best used sparingly, as is "I".


Andrei

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.


Andrei

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

On Sat, Jan 14, 2012 at 21:14, Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org> wrote:

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

:) I do the same.

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

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

(Much like my use of "like" in the previous sentence. Yes, "like" can be filler, but changing that sentence to use "such as" would have done nothing but...pointlessly increase the word count.)

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

Got it, thanks a lot!

>> 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.
>
>
> Yah, I defined several LaTeX environments and a little syntax for that. I also arranged to ignore "..." when it appears alone on a line. Overall it was an effort well worth it.

I'll do the scaffolding.


>> I wondered whether I should present only 'compile-as-shown' examples, which means putting import statements and void main() {/* some code */} everywhere.
>
>
> Define distinct environments for stuff that must be top level vs. stuff that must be wrapped in main or unittest.

OK.

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!