current ddoc state of the art

[Adam D. Ruppe via Digitalmars-d]

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.