colour lib needs reviewers

[Jacob Carlborg via Digitalmars-d]

On 2016-09-14 22:14, Andrei Alexandrescu wrote:

> Why? -- Andrei

I've recently worked on a theme for Ddoc that will be used in TextMate. 
For convince I started by adding the CSS inline in the head tag. Turns 
out if you have CSS looking like this:

.foo {
   font-weight: bold;
   background-color: white;
}

Everything works perfectly fine. Then I added text color as well:

color: black;

Guess what happens? It cuts, it cuts everything after "color". The 
solution is to use a colon macro:

Macros:
   COLON = :

color$(COLON) black;

It took me quite a while and a lot of frustration until I figured that 
out. But I guess that's an inherit problem with a macro system.

That is what I'm missing from Ddoc:

* Inline source code for each symbol [1]. The [1] example both has a 
button to show the source code inline and a direct link to GitHub

* Link to GitHub for each symbol [1] and for the whole module. The way 
it's done now with $(PHOBOSSRC std/net/_isemail.d) is not standardized 
and feels like a hack. Why slashes and why the underscore? If anything 
it should be the fully qualified name. Ideally it should be automatic, 
or a compiler recognized macro that inserts the link

* Ddoc should organize symbols by visibility [2]
* Ddoc should generate index table [3]
* Ddoc should organize a module by symbol category [4]
* Add a way to inherit documentation from the parent class [5]

* Ddoc should give a list of inherited members [6]. JavaDoc does this by 
default [7]

* Consistent way of cross-referencing. Ideally one would just pass the 
fully qualified name (or local name for symbols in the same module) to a 
compiler recognized macro and it would generate the appropriate links

* An index page with all symbols, including a filter [8]. This is super 
convenient when you know the symbol to use but you need to double check 
how it's used or the behavior. I use it almost every day with Ruby

All this should be done within Ddoc without the need for any post 
processing.

In general I feel that Ddoc is too much focused on a generic macro 
system instead of focusing on being a good tool for writing 
documentation for code.

[1] 
http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-first

[2] https://issues.dlang.org/show_bug.cgi?id=11893
[3] https://issues.dlang.org/show_bug.cgi?id=11891
[4] https://issues.dlang.org/show_bug.cgi?id=11892
[5] https://issues.dlang.org/show_bug.cgi?id=10399
[6] https://issues.dlang.org/show_bug.cgi?id=7688

[7] 
http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fdom%2FSimpleName.html

[8] http://ruby-doc.org/core-2.3.1

-- 
/Jacob Carlborg