On Jul 1, 11 03:10, Walter Bright wrote:
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().
Right. Perhaps d-p-l.org should replace those $(LINK2 x#y, z) by
$(CHAPTER x, y, z) also. (or $(SECTION x, y, z) depending on what y is).
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.
OK.
I agree DDoc make a very easy to define and change a macro, but this
isn't a unique capability of DDoc. (Also you write your own '..
cppcode::', as I've said before. It's just not as straight-forward as
DDoc :) )
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.
If D can get a new keyword we won't see 'inout(T)' and 'auto ref' and
'final switch' and all overloads of 'static' ;-) And missing a few
keywords (say, __gshared) isn't fatal.
OTOH, DDoc doesn't highlight anything besides D (not that it's an
advantage in
this context).
That's right.
(actually I wanted to write "not that it's _a disadvantage_ in this
context". My mind lost in the double negativeness :) )
