Improving ddoc

[Andrei Alexandrescu via Digitalmars-d]

ketmar via Digitalmars-d <digitalmars-d at puremagic.com> wrote:
> On Thu, 1 Jan 2015 00:14:23 +0100 Andrej Mitrovic via Digitalmars-d
> <digitalmars-d at puremagic.com> wrote:
> 
> On 1/1/15, ketmar via Digitalmars-d <digitalmars-d at puremagic.com> wrote:
> ah, "markdown" here means "anything human-readable", be it markdown,
> textile, restructured, or something completely different. i don't really
> care, as long as it's not littered by visual noise.
> 
> I think the best way to show the benefits of any of these formatting
> syntax flavors is to actually write a sample documentation page based on
> an existing one from phobos/dlang.org, with the same (or close to) the
> generated output as the ddoc one, and then we can clearly see how the two
> compare and whether it's worth considering looking into.
> 
> I personally agree the ddoc macro's can introduce a lot of visual noise.
> 
> there is no sense in demonstrating anything, as Walter and Andrei seems
> to be sure that Ddoc is human-readable, and there's no much sense in
> changing it, as people should always generate html/TeX/other output, not
> trying to read the documentation right in .d files. anything less
> powerful than Ddoc will be rejected with arbitrary reason (see Walter
> posts about escaping in markdown, for example).

That's unfair. You wouldn't us to give in to emotional arguments that lack
reason. Make good points and they'll be minded. -- Andrei