On 6/30/2011 6:28 AM, KennyTM~ wrote:
No, you don't have to. I'll often write it as:
$(CHAPTER foo, bar)
The 'foo' is still here. By natural I mean once you have a 'bar', you often
don't need to care about the 'foo'.
Right, I agreed that Sphinx does better with that detail.
Also, in d-programming-language.org $(LINK2
x.html#y, y) is used, but $(CHAPTER x, y) does not exist.
Right, but defining your own macros is completely trivial, and when using Ddoc
for more than a few lines, I'd expect one to define helpful macros specific to
what you're writing.
If you're going to avoid writing such macros, then writing Ddoc source is
probably going to be clumsy. It's just not meant to be used that way - like
trying to write C code without writing any functions other than main().
With Ddoc, you can read the HTML manual and apply it directly to Ddoc.
Ddoc doesn't even know what HTML is, so it has no need to replicate its
functionality in a same-only-different manner.
Neither does Sphinx. '.. class::' is not tied to HTML either.
I think you misunderstood me. I meant I don't have to learn a separate-but-equal
markup language. If I know html, then using Ddoc is a no-brainer to use. If you
need more than a few minutes to get the hang of it, something is wrong. Maybe if
you're unfamiliar with text macros, but I can't see a person competent to write
programming manuals not knowing them.
Expecting someone who's expertise is flower arranging to learn/use Ddoc is
likely a hopeless task.
If you need all of these attributes, why not use raw HTML (yes there is '..
raw::')?
Because writing HTML more than once is a giant annoying pain. With Ddoc, I hide
those naughty bits in a macro, then use the macro.
How is '.. class:: cppcode' different from '$(CPPCODE x)' in terms of
redundancy?
Since CPPCODE is a macro, it can expand to anything. I can use it to set the
html tag, font, color, size, class, whatever. And, I can *change* it globally by
changing the macro, not by editing each instance.
It's the same rationale for why we have user-defined aliases, classes, and
functions in programming languages.
I think I've completely failed to make that point.
What if you have something it doesn't highlight for you? Like D? :-)
You contribute to Pygment! :)
:-(
BTW it *does* highlight D. See http://pygments.org/languages/ for the support.
And when D gets a new keyword? Everyone has to wait for the next upgrade cycle
of Sphinx. With Ddoc, it's automatic.
OTOH, DDoc doesn't highlight anything besides D (not that it's an advantage in
this context).
That's right.
