Improving ddoc

[ketmar via Digitalmars-d]

On Thu, 1 Jan 2015 05:50:18 +0000 (UTC)
Andrei Alexandrescu via Digitalmars-d <digitalmars-d at puremagic.com>
wrote:

> 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

p.s. i already demonstrated excerpt from std.algorithm in that other
topic. Walter says that i didn't bother to format Ddoc noise, not even
reading my post about it till the end, where i told that there is no
much sense in formatting Ddoc, as it will still be noise.

so i will not even to try to do it again and again just to read the
same answers again and again. about "that needs escaping too", about
"we can't specify different fonts there" and so on. i wrote several
times that Ddoc is reminding DTP, and it is not human-readable. i even
shown the sample. seems that Walter is clearly missing the point of
human-readable documentation (i think that he just don't care, as from
his POV documentation must be preprocessed to standalone files, there's
no reason to read it inside .d source; and he wants powerful
preprocessor with DTP features).

sorry about you, though, as you didn't seem to tell anything like that
except some messages that (it seems) just trying to stop the flamefest.
mea culpa.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20150101/909a1ff9/attachment.sig>