Good evening, Professor,
On Sunday, 26 May 2013 at 02:05:55 UTC, Andrei Alexandrescu wrote:
What vexes me is that all the sugar you propose goes against
what you opened with...
I'm not trying to cause any offence, and I apologise if any of my
phrasing or comments are construed that way. I know that I can be
a little bit terse at times but I hope it's taken in the best
possible way because I have full respect for the design and
implementation of the language.
On Sunday, 26 May 2013 at 02:05:55 UTC, Andrei Alexandrescu wrote:
I can hypothesize that the shortest path between where we are
and what you're trying to accomplish is a few dozens of macro
definitions. Did you try doing that and failed?
Indeed, it has run into some snags:
1) One of the first problems I ran into was coming up with rules
for spec.dd. My original objective was to enclose the $(TOC)
macro into <nav> tags, consistent both with the HTML5 spec and
ePUB3. However, <p> tags are not allowed within the <nav> tags,
but I also don't want to strip out the explanation the
informative information. I don't know how to define TOC to keep
the $(P) macro outside of the <nav> element which will enclose
the TOCENTRY items.
2) Consider, for example, parsing arrays.dd (my comment can be
easily applied to any other file). Unless I'm miscounting
parentheses, $(H4) macros are not being used within $(H3) macros.
Therefore, how do I get DDoc to parse the file so that it ends up
with nested <section> tags? for example:
<section><h3>Dynamic Arrays</h3>
<section><h4>Array Declarations</h4>
Content
</section></section>
3) Consider, for example, this part from abi.dd:
$(GRAMMAR
$(I MangledName):
$(B _D) $(I QualifiedName) $(I Type)
$(B _D) $(I QualifiedName) $(B M) $(I Type)
$(I QualifiedName):
$(I SymbolName)
$(I SymbolName) $(I QualifiedName)
$(I SymbolName):
$(I LName)
$(I TemplateInstanceName)
)
Say I want to style this using a descriptions list, the <dl> tag.
That's easy enough, but now how do I tell DDoc to tag the $(I)
macros using <dt> and <dd> tags?
4) Furthermore (still referring to the example above, because the
issue applies to other areas), how do I tell DDoc that $(I)s
within a $(GRAMMAR) macro are to be formatted using descriptions
list syntax, but keep the other $(I) macros as regular <i>
elements?
5) The link-related macros appear, by and large, to use relative
URLs. If I'm compiling only the DLang Spec into an ePUB, the
standard, I believe, requires that the links be resolvable.
That's easy enough if the relative URL in question points to
another page in the spec. However, if the link points to another
page on the website or a library document, which (for now) won't
be in the ePUB, is the only way to identify and fix those links
going to be by hand?
These are the problems that I've run into thus far. I'm doing my
best to appreciate the design and theory of DDoc, but maybe it's
too much of a paradigm shift for me and I end up fighting the
macros?
