colour lib needs reviewers

[Andrei Alexandrescu via Digitalmars-d]

On 09/15/2016 02:55 AM, Jacob Carlborg 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.

Yah, this is terrible (it happens with http: all the time). We need to 
suppress the special meaning of ":" to only the cases when it's preceded 
by only one word and followed by a newline, e,g, "\ncolor:\n".

> 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

Can this be done by defining the expansion macros appropriately?

> * 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?

Slashes are tolerable. The underscore I agree it's a quirk.

> If anything
> it should be the fully qualified name.

That'd be nice.

> Ideally it should be automatic,
> or a compiler recognized macro that inserts the link

Ironically the underscore is necessary because ddoc does too much 
automatically.

> * 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.

I think we should start with a postprocessing-based approach and see 
what capabilities need to be added to obviate the need for postprocessing.

> 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.

That's a fair assessment, and an actionable one.


Andrei