Publication of the French translation of Ali's "Programming in D" book

[Raphaël Jakse]

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