Worst Phobos documentation evar!

Anon via Digitalmars-d digitalmars-d at puremagic.com
Wed Dec 31 11:59:54 PST 2014


On Wednesday, 31 December 2014 at 19:11:27 UTC, Walter Bright 
wrote:
> On 12/31/2014 7:20 AM, Vladimir Panteleev wrote:
>> On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright 
>> wrote:
>>> * reddit
>>> * github
>>
>> These both use Markdown. The syntax is the same, except for 
>> minor things, such
>> as the handling of newlines.
>
> Yes, the same only different.

Just like DDoc macros and Makefile macros. They're the same, but 
different.
Also, the differences between Markdown implementations are 
trivial, and do not effect the readability of the source, which 
is the entire point of Markdown - making the "plain-text" 
readable, rather than polluting it with HTML (or DDoc) tag noise.

>>> * wiki
>>> * hackernews
>>
>> Hacker News and both the new D Wiki, and the old, do not use 
>> Markdown.
>
> It's just another variation of it - which is my point.

And your point is completely wrong. DDoc and Makefiles both use 
$(MACROS), does that mean that DDoc is a variation of Make?

Yes, *lots* of things use common elements. Because that makes 
things more easily understood when *reading*, which is the single 
most important thing for documentation. The macros are fine for 
when they are needed, but you shouldn't have to use gotos and 
jumps when all you want is a gorram foreach loop. Nor should you 
have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a 
list.

> I know that Markdown formatting is context sensitive.
> And what happens if you want to have a * at the beginning of 
> the line of
> output?
> And a | in a table entry? And so on for each of the context 
> sensitive things?

A backslash. Y'know, the unambiguous, 
familiar-to-all-programmers, really-hard-to-mistype thing that 
almost everything but HTML and DDoc use for escaping?


More information about the Digitalmars-d mailing list