Improving ddoc

[Ary Borenszweig via Digitalmars-d]

On 1/1/15 2:35 PM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= 
<ola.fosheim.grostad+dlang at gmail.com>" wrote:
> On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig wrote:
>> What's cross-library-indexing? You mean show documentation for many
>> libraries at once?
>
> Yes, many libraries, source code with builtin links, links to github
> with line numbers, docs for other languages when D wrappers are
> provided. The ideal is to propagate as much useful information as
> possible to a normalized universal format that makes it easy to build
> intelligent information systems using some kind of deduction. You should
> generate a database, not a document.
>
> HTML is underpowered and assumes that domain specific semantical
> information is encoded in a different layer like RDF, but that leads to
> solutions that are overly complicated compared to a domain specific XML
> format.

I really don't understand why you say that.

I just started writing a documentation generator for the Crystal 
programming language.

http://crystal-lang.org/api/

You can read about its features here:

http://crystal-lang.org/2014/12/31/crystal-0.5.6-release.html

Now, I go here

http://dlang.org/phobos/std_file.html

and I can't believe that after 10+ years of development, D documentation 
still doesn't have a basic feature like inter-linking between types (I 
even once submitted a PR but it wasn't accepted because other code was 
written on top of it and then the merge was hard to do). For example:

http://dlang.org/phobos/std_file.html#.timeLastModified

I should be able to click SysTime and go to that type definition.

But, DDoc can generate Latex.

Then, take a look at Rust. Guess what they use for their documentation? 
Markdown! Here's a web framework called Iron:

http://ironframework.io/

Here are the API docs:

http://ironframework.io/doc/iron/

Let's take a look at enum.Method:

http://ironframework.io/doc/iron/method/enum.Method.html

See that red "String" text? Click it and it takes you here:

http://doc.rust-lang.org/nightly/collections/string/struct.String.html

Wow! It took you to the String definition in an entirely different host!

Back to Crystal's docs, below every method there's a "View Source" link 
that takes you to that code in GitHub. No such thing in D.

Note that all of this was done with just Markdown (HTML) and by making 
the documentation generator understand and use the language as much as 
possible, something with DDoc doesn't do. I once submitted a PR to fix 
that, but it was ignored.

I would suggest D to use a simple language to write the documentation, 
and then a powerful tool that understands the semantics of the language 
and allows you to generate good looking, easily browsable documentation. 
Neither JSON, XML, YAML or macros are needed for that.