www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Publication of the French traduction on ddili

reply =?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 
https://code.google.com/p/ddili/source/browse/#svn%2Ftrunk%2Fsrc%2Fders%2Fd.en 
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 
case you have any doubt about whether a chapter is already proofread or 
not, please ask, I will keep track of what happens. Several proofreaders 
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 
if you begin your e-mail subjects with [trad-ddili].

If you have any idea, question, suggestion, reclamation, please ask :-)

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

Cheers,
Raphal
Dec 06 2013
next sibling parent reply 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
parent reply =?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 
be added to Pandoc?
  - 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.

Please comment ;-)


 `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 
some information about this and post here

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


Thanks for your answer !


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
 https://code.google.com/p/ddili/source/browse/#svn%2Ftrunk%2Fsrc%2Fders%2Fd.en
 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
 case you have any doubt about whether a chapter is already proofread or
 not, please ask, I will keep track of what happens. Several proofreaders
 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
 if you begin your e-mail subjects with [trad-ddili].

 If you have any idea, question, suggestion, reclamation, please ask :-)

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

 Cheers,
 Raphaël
Dec 08 2013
parent reply 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 
published material (which sadly is contradicted by the likes of Markdown 
which lack decent macro systems).


Andrei
Dec 08 2013
next sibling parent reply 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
parent reply =?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:

      - bread
      - cereals
      - milk

      - meat
      - vegetables
      - cheese
      - dessert

      - 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
parent reply =?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
parent reply 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
parent reply =?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
parent 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
prev sibling parent =?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
 published material (which sadly is contradicted by the likes of Markdown
 which lack decent macro systems).


Thank you for your answer.

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
prev sibling parent reply =?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
parent reply =?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 
https://code.google.com/feeds/p/ddili/svnchanges/basic

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
parent =?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