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