On Monday, 29 December 2014 at 23:56:47 UTC, Walter Bright wrote:
On 12/29/2014 3:31 PM, Kiith-Sa wrote:
because I need macros even for something as common as an
inline code fragment.
Markup, macro, same thing.
Not to mention, if I include the full table lines, not just
~70 chars this
newsgroup will take, the difference in readability is much
more massive.
Not really, because you can create your own custom macros to
shorten things up.
I use Ddoc all the time, and I create custom macros ALL THE
TIME for semantic shortcuts, prettying things up, saving
typing, etc. Any repetitive tasks are candidates for a custom
macro.
If you're not using custom macros, and you find Ddoc tedious
and repetitive, you're using it wrong.
I cannot use a custom macro to shorten $(D a == b). A
well-written paragraph will have 20 such $(D XXX), $(B XXX), $(I
XXX), not to mention $(SOMELINK xxx.com XXX). And there's no way
to make lists or tables readable: *unless* their contents is
homogenous, at best I will have rows full of $(XXX ).
etc. is completely unreadable for anyone but people who have
spent at least a year looking at the mess that is Phobos
documentation comments.
Javadoc is more readable in sources, as is Doxygen. Python's
Sphinx is more readable in their sources.
[Rust](http://doc.rust-lang.org/rustdoc.html) is using markdown
for their documentation and they don't have any issues either.
Yes, *you* use DDoc all the time. But *you* are also forcing it
on everyone using the language, and on any average programmer who
may potentially use D, most of whom don't share your love for
macros and MANY of whom know much more common formats like
Markdown. Most people don't write their docs in LaTeX either.
Besides, no-one is proposing to *remove* the macros, the proposal
it to add syntax for basic cases which frankly can *not* be made
any less ugly with macros. And yeah, so you will need to escape
I'm writing my *thesis* in ReStructuredText, which is basically
Markdown on steroids with *way* more special characters than
Markdown, and I almost never need to escape anything.
Either way, I'm done with this argument, I expect it will take
many more pissed-off users for this to change.
As for the CSS thing, yes, you need that built in. It doesn't
have to be amazing but it *has to be usable*.
to be usable, documentation must be as simple to generate as:
doxygen Doxyfile
That's what a user coming from most different languages expects,
if they don't get it, it seems *broken* and is extremely
off-putting. When I was starting with D this almost made me give
up. Bare HTML files, no cross-referencing, unreadable, no menu.
No information on the site on how to get a usable documentation
(not sure how it's now, it's been a few years), and coming from
Doxygen, writing a bunch of .ddoc files I wasn't even told about
wasn't what would come to my mind.
The default does not need to look amazing, but there must be
something usable to start with, without *any* work other than
having documentation comments in your code. Any other common
documentation generator will produce something that can at least
be browsed.
