Let's try to get state-of-the-art ddoc in here. Iff my backtick
PR goes through, I'll do another one bringing some of these
tricks to the default macro list.
What I want to do in this thread is get the nicest ddoc bits we
can do and analyze where they fail. If they rock, let's just put
those macros in the default set and document how to do it.
If they still suck, then maybe we can discuss using an
alternative.
First, lists. The current default macro is ok:
$(UL
$(LI item)
$(LI item)
)
But ddoc supports tail recursion which means we could:
Macros:
LIST=$(UL $(XLIST $1)$(XLIST $+))
XLIST=$(LI $1)$(XLIST $+)
L=$0
Then do:
$(LIST
foo,
bar,
$(L item, with, comma),
`code with commas, inline`, # also supported with my PR
)
That's perhaps better. The $(L macro is still needed for some
literal text passing - you can do a comma, a dollar sign, or
matching parens in there.
I think of it like being the quotes in a CSV file. Not needed if
there's no commas, available if there is.
The leading whitespace is kept on each item btw, but ignored by
html output, so it is OK on the web.
I honestly think that's good enough.
We can do similar with tables:
$(TABLE
$(TROW Some header, Some other header, Third header)
$(TROW Some row, Some other row, More info)
)
The problem is if the data is so long you'd like to break it onto
another line, but then the look is ruined.
$(TABLE
$(TROW Some header, Some other header, Third header)
$(TROW Some row that
is really long, Some other row, More info that
is really
long)
)
That works, it generates usable output, the long items don't
match up anymore in the source. It might be hard to read.
One idea is to use macros as a kind of footnote to reference long
data elsewhere:
$(TABLE
$(TROW Some header, Some other header, Third header)
$(TROW Some row, $(Long_data_here), $(fooa))
)
Macros:
fooa=cool
Long_data_here=We can put some longer data here
and it should work a lot nicer.
There's a few problems with that:
* the data doesn't appear where you want; you'd have to scroll
back and forth to actually read the table.
* Two functions that define the same macro name will override
each other; a doc from way down the file could wipe out your
footnote from up top.
So I think the state of the art ddoc table leaves something to be
desired. A markdown table syntax might be cool here.
Another thing that might help is scoping the macro definitions to
the symbol's scope. A macros: section on a module definition
defines macros usable throughout the whole file. On a class,
itself and its members. On an individual member, it only applies
there.
That could allow and encourage the use of local macros for all
kinds of little things including footnotes.
Remember, the purpose of this thread is to try to get as good as
we can for various tasks with the existing ddoc capabilities.
Only if that comes up short do we want to talk improvements, and
even then, I want this thread to be conservative.
