I want to keep this discussion focussed on the DLang spec source
code. If we want to debate the features of DDoc, we should do it
in another thread.
However, as not to appear full of cricism but short of ideas, I'm
going to break my own rule and suggest, at least for the purposes
of solving some of the issues I've run into with the DLang spec
source, that integrating some wiki-markup into DDoc may help. For
example:
1) Allowing sections to be defined using == Heading == or ===
Heading === instead of $(HEADING ) or variants. The advantage
that Wiki syntax has over macro-syntax is that it automatically
works out the section nesting (which is essential for building
tables of contents in things such as, hint hint, eBooks) whereas
macros can only do it if the subheadings are nested as arguments.
1a) Using ==Headings== and the existing /** */ code standards,
DDoc could have a predefined $(TOC) macro which would
auto-generate the TOC. /** */ would form the main headings and
==Heading== would be the subheadings, prettily nested when
formatted.
2) Adopting Latex's rule that a double line break means a new
paragraph. This will effectively make the $(P) macros rampant in
the DLang spec documentation unnecessary.
3) Defining tables using the +---+ syntax. I know that this will
be unpopular due to the existing /++ documentation code rules
(and thus is open to alternatives). However, one must admire how
simply Wiki markup has elegantly solved a problem that Latex and
XML dosen't.
4) Using either * or - to indicate bullet points, similar to Wiki
markup. Again, I know that it'll have to be coded as not to
confuse the parser with /** */ and operands.
4a) Maybe #) to indicate ordered lists? (again, similar to Wiki
markup)
5) Use the [[Link|Link name]] instead of $(Link) macros to
cross-link. By default, Link would be a reference to some other
DDoc and allow links to be handled automagically.
How will this all help the DLang spec? Well, if the spec could be
rewritten entirely in a /** */ block, with reasonable macro use,
then couldn't it be parsed more readily into the necessary
formats? Wouldn't it also make the source more readable and
editable without all of the nested parentheses? Wouldn't the
syntax be self-documenting?
Anyway, just throwing stuff against the wall to see what sticks...
