Le 08/12/2013 22:41, Philippe Sigaud a écrit :
On Sun, Dec 8, 2013 at 10:29 PM, Andrei Alexandrescu
<seewebsiteforem...@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
- bread
- 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 :)
