On Tuesday, 27 February 2018 at 01:43:55 UTC, Jonathan M Davis
wrote:
Well, then basically, projects are going to need to decide to
go with adrdox over ddoc if they want clean documentation.
That's right, and I can't imagine anyone is going to put hours of
work into ddoc when they can spend seconds just writing and have
it just work on my site, including most common ddoc in addition
to a good subset of markdown and, if they decide to dive a little
bit deeper, can use my custom syntax custom-tailored to writing D
documentation quickly and easily like [link].
https://www.youtube.com/watch?v=Ak516vtDTEA
They'll probably get better documentation with adrdox than the
default ddoc if they do nothing, but any project that actually
goes to the effort of having nice looking documentation is
going to fall flat on its face with adrdox unless it buys into
adrdox whole hog.
Eh, that's not true. I am *very* compatible with Phobos (have you
use dpldocs.info before? 9/10 dentists agree, it is vastly
superior to dlang.org, and the tenth dentist is paid to lie), and
since most "nicer" ddoc borrows from the phobos definitions, most
of them will just work too. I actually even just added your LREF2
macro to the internal macro compatibility list, bringing my
compatibly with your syntax to near-total.
BTW you misspelled "element" here:
http://dxml.dpldocs.info/source/dxml.dom.d.html#L119
On your version, third paragraph:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_dom.html#.DOMEntity
adrdox (my build here anyway, which knows the whole phobos tree
too) caught that and issued a broken link warning. Did ddoc? I
already know the answer.
Of course, if you were using adrdox syntax, that mistake wouldn't
have happened in the first place, instead of writing:
$(REF_ALTTEXT EntityType.elementStart, EntityType.elmentStart,
dxml, parser)
You would have simply wrote [EntityType.elementStart] and not had
to repeat yourself telling the compiler what it already knows (in
a bizarre order, no less).
Of course, even with the broken link, the adrdox result is usable:
http://dxml.dpldocs.info/dxml.dom.parseDOM.2.html
links to:
http://dxml.dpldocs.info/dxml.parser.EntityType.html#elmentStart
and you can see it in the table.
Whereas the ddoc link goes to:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_parser.html#.EntityType.elmentStart
where the anchor is who-knows-where.
Moreover, look at this:
http://dxml.dpldocs.info/dxml.util.asNormalized.html
"combines parseStdEntityRef and parseCharRef along with
processing for $(DCODE_STRING '\r') to"
and compare with:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_util.html#.asNormalized
"combines parseStdEntityRef and parseCharRef along with
processing for to "
See something missing? Yes, you write DCODE_STRING instead of the
definition of D_CODE_STRING and ddoc swallowed your text. (Yes, I
know you can define ddoc to output undefined macros, just like
adrdox does. But it doesn't by default, so a typo in a macro name
means text just ~disappears~.)
And again, that is unlikely to have happened if you just used the
standard backticks (`'\r'`) which don't render exactly the same
but are good enough. ddoc supports them too, so this isn't even
an adrdox thing... but I'd argue that merely having user-defined
macros makes you more likely to try to use them, increasing the
likelihood for mistakes like this. That's the main reason why I
decided to simply not support them, the cost outweighs the
benefits.
I don't say this to pick on you - you have some of the nicest
ddoc I have ever seen, and you actually make the effort to write
it all up in the first place.
But even you, who know how to use ddoc very well and have
obviously spent some time on it here, made trivial mistakes here
that just don't happen with adrdox.
