DLang Spec rewrite (?)

Borden 2013 at bordenrhodes.com
Sat May 25 18:22:15 PDT 2013


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


More information about the Digitalmars-d mailing list