colour lib needs reviewers

[Manu via Digitalmars-d]

Do we mind moving this discussion to the other topic I started
actually on this topic?

It's slightly upsetting that this discussion about ddoc is more
popular than the colour lib I spent months workinng on :(


On 15 September 2016 at 16:55, Jacob Carlborg via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
> 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