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