## digitalmars.D - Publication of the French traduction on ddili

=?ISO-8859-1?Q?Rapha=EBl_Jakse?= <raphael.jakse gmail.com> writes:
Hello everybody.

I published the current state of my translation on Gitorious:

https://gitorious.org/programmez-en-d

There are about 42 chapters still to translate, with three of them still
to translate from Turkish to English.

I think it is time to begin a proofread of the first chapters.
For the moment, I'm willing to continue the translation of the chapters
which are still to translate, even though this might change in the
future. This week I managed to translate 4 chapters, I hope to advance
the translation at good pace for Christmas holidays.

Important facts:
- You can get the ordering of the chapters in langage_d.whata, which
is the main document, and in map.txt, which lists the connections
between file names of English chapters at
and French file names.
- The document is written in Whata!, which is a home made syntax
translating in LaTeX and HTML to produce the final document. You can get
a program written in D which translate Whata! into LaTeX here:
https://gitorious.org/whata/whata-d/

To produce a PDF of the whole document, install whata and type:
$pdfwhata langage_d.whata Be sure you installed XeLaTeX. To produce a PDF of a chapter, type:$ pdfwhata the_chapter.whata

Some chapters, like the chapter on exceptions, are somewhat broken
because of special characters. When I or someone find a way to make
LaTeX handle special characters that are not part of its default font,
we'll be in the best world ever.
- corrections of the exercises are in the corrections folder.
- first chapters were translated a year ago, and this is my first
real-life translation of a document. Last chapters were translated
recently, often under tiredness. While I try to do my best, expect many
silly mistakes (I've kind of proofread some parts, it wasn't pretty)
- The translation should be published on dlang-fr, both in HTML and
PDF. I still didn't published the Whata! to HTML converting program as
it's not quite ready in my opinion, but it works somewhat well.

For those who want to  proofread, the best thing to do is probably to
say you are proofreading the chapter x, and contact me for corrections.
You can ask for a pull-request or send me your correction by mail, or
use another way I didn't think of and is convenient for all of us. In
of the same chapter is not bad!

I will be more than happy if you suggest improvements, rephrasing or
anything beyond grammar and orthographic mistakes. Please spam; I
already spam Ali with corrections of his English version. I will be glad

Do you think we should start publishing the first proofread chapters?

Cheers,
Raphal

Dec 06 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
First, kudos for translating all this! I'm sure that'll be a good
reference and maybe pave the way for other translations (Spanish,
German & Japanese come to mind).

I have a few questions:

- why did you use this whata! language instead of a standard format,
like markdown or even ddoc? At least that way you can re-use many
tools that already exist. markdown is known by many people, and pandoc
is able to translate it into dozens of different format (including
LaTeX and pdf and ePub).

Some chapters, like the chapter on exceptions, are somewhat broken
because of special characters. When I or someone find a way to make
LaTeX handle special characters that are not part of its default font,
we'll be in the best world ever.

- What special chars?

- can we push pull requests directly on Gitorious? I'm more used to github.

- How do you intend to publish this text?

Dec 08 2013
=?UTF-8?B?UmFwaGHDq2wgSmFrc2U=?= <raphael.jakse gmail.com> writes:
Le 08/12/2013 18:05, Philippe Sigaud a écrit :
First, kudos for translating all this! I'm sure that'll be a good
reference and maybe pave the way for other translations (Spanish,
German & Japanese come to mind).

I have a few questions:

- why did you use this whata! language instead of a standard format,
like markdown or even ddoc? At least that way you can re-use many
tools that already exist. markdown is known by many people, and pandoc
is able to translate it into dozens of different format (including
LaTeX and pdf and ePub).

To be fair, I used Whata! mainly because I am the author of this syntax
and I'm used to it.

I can try to explain why I wrote Whata! instead of Markdown.
When I started Whata!, it was for writing maths lessons, just before
Markdown started to be well known by everybody. I wanted it fast to
write and easy to read, I didn't know Pandoc at that time. Markdown is
in fact easier to read but I don't like some part of it like being able
to write HTML code inside it or indenting for code blocs: I like to
indent my documents when I write them. I wanted support for maths, for
sections like in HTML5, and the possibility to extend the syntax with
custom tags and first class support for HTML as well as PDF output,
among other things.
I'm willing to make writing complex documents with Whata! possible,
which I think Markdown is not for.

Concerning LaTeX, I find it verbose, inconsistent, rigid, difficult to
learn and I think it doesn't help enough to separate presentation and
contents. It is excellent for its PDF rendering and its syntax for
writing algorithms and formulas, but I don't see myself taking notes in
LaTeX. Morever, LaTeX to HTML converters don't seem to produce pretty HTML.

Regarding DDoc, I just didn't know D when I started Whata! (I started it
in PHP, and I still use the second version of the PHP program to produce
HTML versions of the document), and DDoc when I started the translation
of the book. I still find Markdown better to write plain documents than
DDoc.

That said:
- I might be entirely wrong in even writing Whata! instead of
embracing Markdown
- Markdown should be good enough for this book, as long as it it
possible to write one file by chapter without any hack
- DDoc might be good, but a LaTeX output would be great
- I'll try to add support for Whata! in Pandoc. Maybe DDoc should also
- If necessary, we'll switch to Markdown for this translation.
However, it would be sad for me :-) Please say it if you want to work in
Markdown.

Seeing the whole translation written in Whata!, would be represent a
small success for me, but I'm eager to drop Whata! for this translation
if people ask for it. On the other hand, I think Whata! is easy enough
for proofreading and hopefully for writing new chapters.

Some chapters, like the chapter on exceptions, are somewhat broken
because of special characters. When I or someone find a way to make
LaTeX handle special characters that are not part of its default font,
we'll be in the best world ever.

- What special chars?

◁ :  U+25C1
▶ :  U+25B6
� :  U+FFFD

- can we push pull requests directly on Gitorious? I'm more used to github.

I never used pull requests yet, I think it is possible. I'll try to get
- How do you intend to publish this text?

Short answer : in PDF and HTML format on dlang-fr.org. I'll let Munrek
present his website again if needed ;-)

I think we should progressively publish chapter as they are proofread,
and show a notice to say that the document is under translation and
proofreading and if people want to participate, they can. I'm open to
any other idea of how we should do this.

Unfortunately, I deleted the original post by error, so here it is.

Hello everybody.

I published the current state of my translation on Gitorious:

https://gitorious.org/programmez-en-d

There are about 42 chapters still to translate, with three of them still
to translate from Turkish to English.

I think it is time to begin a proofread of the first chapters.
For the moment, I'm willing to continue the translation of the chapters
which are still to translate, even though this might change in the
future. This week I managed to translate 4 chapters, I hope to advance
the translation at good pace for Christmas holidays.

Important facts:
- You can get the ordering of the chapters in langage_d.whata, which
is the main document, and in map.txt, which lists the connections
between file names of English chapters at
and French file names.
- The document is written in Whata!, which is a home made syntax
translating in LaTeX and HTML to produce the final document. You can get
a program written in D which translate Whata! into LaTeX here:
https://gitorious.org/whata/whata-d/

To produce a PDF of the whole document, install whata and type:
$pdfwhata langage_d.whata Be sure you installed XeLaTeX. To produce a PDF of a chapter, type:$ pdfwhata the_chapter.whata

Some chapters, like the chapter on exceptions, are somewhat broken
because of special characters. When I or someone find a way to make
LaTeX handle special characters that are not part of its default font,
we'll be in the best world ever.
- corrections of the exercises are in the corrections folder.
- first chapters were translated a year ago, and this is my first
real-life translation of a document. Last chapters were translated
recently, often under tiredness. While I try to do my best, expect many
silly mistakes (I've kind of proofread some parts, it wasn't pretty)
- The translation should be published on dlang-fr, both in HTML and
PDF. I still didn't published the Whata! to HTML converting program as
it's not quite ready in my opinion, but it works somewhat well.

For those who want to  proofread, the best thing to do is probably to
say you are proofreading the chapter x, and contact me for corrections.
You can ask for a pull-request or send me your correction by mail, or
use another way I didn't think of and is convenient for all of us. In
of the same chapter is not bad!

I will be more than happy if you suggest improvements, rephrasing or
anything beyond grammar and orthographic mistakes. Please spam; I
already spam Ali with corrections of his English version. I will be glad

Do you think we should start publishing the first proofread chapters?

Cheers,
Raphaël


Dec 08 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/8/13 1:22 PM, Raphaël Jakse wrote:
To be fair, I used Whata! mainly because I am the author of this syntax
and I'm used to it.

I'd say that's a perfectly reasonable answer.

I can try to explain why I wrote Whata! instead of Markdown.

Does Whata! have a good macro system? After much thinking I got to the
conclusion a good macro system is essential for generating quality
which lack decent macro systems).

Andrei

Dec 08 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sun, Dec 8, 2013 at 10:29 PM, Andrei Alexandrescu
<SeeWebsiteForEmail erdani.org> wrote:
On 12/8/13 1:22 PM, Raphaël Jakse wrote:
To be fair, I used Whata! mainly because I am the author of this syntax
and I'm used to it.

I'd say that's a perfectly reasonable answer.

Well, using Ddoc would be a good demonstration it's possible to write
entire document in it (or not!).

Using markdown would open up the text to people already used to it
(like many people using github, for example) and facilitate pull
requests. If people must learn a new syntax to contribute to a
document, it's less certain they will do it. At this stage, I'm not
sure where to find a Whata! tutorial.

Using plain text is also an option, I guess.

What format used Ali? HTML?

I can try to explain why I wrote Whata! instead of Markdown.

Does Whata! have a good macro system? After much thinking I got to the
conclusion a good macro system is essential for generating quality published
material (which sadly is contradicted by the likes of Markdown which lack
decent macro systems).

Indeed, although I'm not sure Markdown goal is to generate 'quality'
documents, but more 'easily readable and manipulable documents'.

LaTeX is acceptable for macros, but full of gotchas.
I still have to use Ddoc for more than 1-page long documents.

Or else, we need a document-writing library in D, which could emit
Ddoc, HTML, LaTeX and pure text :)

Dec 08 2013
=?UTF-8?B?UmFwaGHDq2wgSmFrc2U=?= <raphael.jakse gmail.com> writes:
Le 08/12/2013 22:41, Philippe Sigaud a écrit :
On Sun, Dec 8, 2013 at 10:29 PM, Andrei Alexandrescu
<SeeWebsiteForEmail erdani.org> wrote:
On 12/8/13 1:22 PM, Raphaël Jakse wrote:
To be fair, I used Whata! mainly because I am the author of this syntax
and I'm used to it.

I'd say that's a perfectly reasonable answer.

Well, using Ddoc would be a good demonstration it's possible to write
entire document in it (or not!).

Using markdown would open up the text to people already used to it
(like many people using github, for example) and facilitate pull
requests. If people must learn a new syntax to contribute to a
document, it's less certain they will do it. At this stage, I'm not
sure where to find a Whata! tutorial.

Soon to be published.

As for learning the new syntax, I think we can assume people who learned
D will be able to understand it when they read it and bring corrections
to Whata! documents without having to learn, and to learn it without
much trouble.

Still, we can switch to Markdown if needed. I think DDoc is great for
commenting D code and build beautiful documentation but might lack a
good PDF output as for today.

Here are the main parts of Whata! I use:

[ = Title section

Contents of the section
]

A paragraph with a **bold** text, ''italic'', [* important (like <em> in
HTML)], [** strong (like <strong> in html].

An inline math formula : [m \frac{1}{2} + 42 \overset{?}{=} \frac{85}{2}]

A [color=blue display-mode] formula:

[M \sum_{i=1}{n} \frac{n(n+1)}{2}]

This program:

[code=d <<<
int main() {
writeln("hello world");
}
]

results in:

[output <<<
hello wold
]

We could introduce a variable named [c foo]. Did you know [c foo] and
foo are equivalent ? The <<< [c ] >>> tag let you explicit the
language, like in [c=d void main { writeln("hello") }].

Each day, I take three meals:
# Breakfast
- cereals
- milk
# Lunch
- meat
- vegetables
- cheese
- dessert
# Dinner
- pasta
- cheese
- yogurt

(meals are ordered, their contents are not)

Using plain text is also an option, I guess.

We need formatting and structure, plain text is not really an option IHMO.

What format used Ali? HTML?

DDoc ;-)

I can try to explain why I wrote Whata! instead of Markdown.

Does Whata! have a good macro system? After much thinking I got to the
conclusion a good macro system is essential for generating quality published
material (which sadly is contradicted by the likes of Markdown which lack
decent macro systems).

Indeed, although I'm not sure Markdown goal is to generate 'quality'
documents, but more 'easily readable and manipulable documents'.

LaTeX is acceptable for macros, but full of gotchas.
I still have to use Ddoc for more than 1-page long documents.

Or else, we need a document-writing library in D, which could emit
Ddoc, HTML, LaTeX and pure text :)


Dec 08 2013
=?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 12/08/2013 03:03 PM, Raphaël Jakse wrote:

Le 08/12/2013 22:41, Philippe Sigaud a écrit :
What format used Ali? HTML?

DDoc ;-)

I wanted to use what D offered partly to also learn DDoc. DDoc has some
issues and apparently some limitations but it worked for me.

Ali

Dec 08 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Mon, Dec 9, 2013 at 1:42 AM, Ali Çehreli <acehreli yahoo.com> wrote:

What format used Ali? HTML?

DDoc ;-)

I wanted to use what D offered partly to also learn DDoc. DDoc has some
issues and apparently some limitations but it worked for me.

What issues and limitations?

Dec 09 2013
=?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 12/09/2013 10:02 AM, Philippe Sigaud wrote:
On Mon, Dec 9, 2013 at 1:42 AM, Ali Çehreli <acehreli yahoo.com> wrote:

What format used Ali? HTML?

DDoc ;-)

I wanted to use what D offered partly to also learn DDoc. DDoc has some
issues and apparently some limitations but it worked for me.

What issues and limitations?

Nothing major and nothing more than you and I have already discussed: ;)

http://forum.dlang.org/post/l579tu$2vta$1 digitalmars.com

Ali

Dec 09 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Tue, Dec 10, 2013 at 12:02 AM, Ali Çehreli <acehreli yahoo.com> wrote:
On 12/09/2013 10:02 AM, Philippe Sigaud wrote:
What issues and limitations?

Nothing major and nothing more than you and I have already discussed: ;)

http://forum.dlang.org/post/l579tu$2vta$1 digitalmars.com

Now I'm feeling old.

Dec 09 2013
=?UTF-8?B?UmFwaGHDq2wgSmFrc2U=?= <raphael.jakse gmail.com> writes:
Le 08/12/2013 22:29, Andrei Alexandrescu a écrit :
On 12/8/13 1:22 PM, Raphaël Jakse wrote:
To be fair, I used Whata! mainly because I am the author of this syntax
and I'm used to it.

I'd say that's a perfectly reasonable answer.

I can try to explain why I wrote Whata! instead of Markdown.

Does Whata! have a good macro system? After much thinking I got to the
conclusion a good macro system is essential for generating quality
which lack decent macro systems).

Depending on what you mean by macro, I got to the same conclusion and
marcos are planned at high priority.

When the work is done, users will be able to define their own tag to do
whatever they want.
However, they might need to do it for each output format (LaTeX.

An example would be a [theorem] tag :

[theorem Fermat's little theorem |
If [m p] is a prime number, then for any integer [m a], the number [m
a^p-a] is an integer multiple of [m p].
]

producing the following HTML output:

<section class="whata-theorem">
<h1 class="theorem-title"> Fermat's little theorem </h1>
<div class="theorem-content">
<p>If <script title="2+2" type="math/tex">p</script> is a prime
number, then for any integer <script title="a"
type="math/tex">a</script>, the number <script title="a^p-a"
type="math/tex">a^p-a</script> is an integer multiple of <script
title="p" type="math/tex">p</script>.</p>
</div>
</section>

This is already possible and used in the HTML version of Whata!, but not
very convenient as-is. Still to be implemented in the LaTeX version.

Template seems to be a good way to implement simple user-defined tags.
For more complex stuffs, users should be able to write package for
whata, like in LaTeX. However, unlike LaTeX, parsing will be done by the
Whata! parser, the package will have to use either the DOM tree output
by Whata!, or its text content.
This is to avoid situations like lstset breaking utf-8 if special
characters are used in listings under certain conditions, or having to
use ^^J if you use listings inside tabularx, or having to declare
lstlistings after the babel package.

This won't prevent user defined tags to parse their text content if they
need a particular language.
If someone needs a [html] tag which is output as-is to HTML, it will be
possible to define it:

[html <<<
<p> a HTML paragraph </p>
>>>]

But structure of the document won't be guaranteed anymore, and any
compatibility with the LaTeX output might be hard to reach.

Users can also define arbitrary values in their document using the [set]
tag at the beginning of the Whata! file. These This is already used to
give a title, a date and an author. Values are also parsed as Whata!.

[set
title  = "Programmer en D"
author = "Ali Çehreli, [i traduit par Raphaël Jakse]"
]

Eventually, users will be able to use templates HTML and LaTeX templates
for their documents. They are already able to give a css file to use for
the HTML version. I don't know how to style a LaTeX document yet. As a
workaround, they can do some post treatment to the generated .tex file.

Once again, I'm open to any suggestion ;-)

Andrei


Dec 08 2013
=?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 12/06/2013 09:21 AM, Raphaël Jakse wrote:

I published the current state of my translation on Gitorious:

Thank you and the future reviewers for their work. What an honor to see
it in another language! I especially liked it that you carried some of
my rare silly jokes to French e.g. "Ce livre a été relu par Ergin Güney
pour être élevé de mon englais à l'anglais" after "This book has been
proofread by Ergin Güney to be elevated to English from my Inglish." ;)

There are about 42 chapters still to translate, with three of them

still to
translate from Turkish to English.

We should also figure out how to move the updates to the French version.
Perhaps I should be the one posting pull requests to your project in
English? :) For example, the Acknowledgments chapter has already many
more names than in the French translation. :)

Ali

Dec 08 2013
=?UTF-8?B?IlJhcGhhw6ts?= Jakse" <raphael.jakse gmail.com> writes:
On Monday, 9 December 2013 at 00:49:00 UTC, Ali Çehreli wrote:
On 12/06/2013 09:21 AM, Raphaël Jakse wrote:

I published the current state of my translation on Gitorious:

Thank you and the future reviewers for their work. What an
honor to see it in another language! I especially liked it that
you carried some of my rare silly jokes to French e.g. "Ce
livre a été relu par Ergin Güney pour être élevé de mon englais
à l'anglais" after "This book has been proofread by Ergin Güney
to be elevated to English from my Inglish." ;)

Your joke made me smile. I'm lucky it translated well into French
:-)
Feel free to point me things you would appreciate to see
carefully translated which I might have not seen.

There are about 42 chapters still to translate, with three of

them still to
translate from Turkish to English.

We should also figure out how to move the updates to the French
version. Perhaps I should be the one posting pull requests to
your project in English? :) For example, the Acknowledgments
chapter has already many more names than in the French
translation. :)

As your book is versioned, I managed to find a convenient way to
keep track of changes. I got a diff between revision 501 (Sept
2012) (to be sure) and today (rev 654), I'm going to update the
translation.

To keep track of changes, I just need to do this:
$svn up$ svn diff -r 501 > changes
\$ kompare changes

And create a file in my repository which stores the revision to
which the translation correspond.

To keep track of changes passively, I just subscribed to

With this, keeping the French translation up-to-date should cost
nothing more than translating the modifications.

Note for later: use a versioning system for all new consequent
document.

Ali


Dec 09 2013
=?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 12/09/2013 06:25 AM, "Raphaël Jakse" <raphael.jakse gmail.com>" wrote:

As your book is versioned, I managed to find a convenient way to keep
track of changes.

Perfect! :)

Ali

Dec 09 2013