On Jun 30, 11 18:25, Walter Bright wrote:
On 6/30/2011 1:26 AM, KennyTM~ wrote:
Right, it's possible, but it is ugly. Isn't the point to show the syntax
"easier, nicer, and more productive"?
Ddoc has pretty much only one syntax. Sphinx seems to have a lot of them.
OK, if that's a concern.
What if the link points to another file? And what if sometimes you want
it intrafile, and another time interfile, without changing the source
text?
Yes it is supported by Sphinx with the :ref:`target` syntax.
http://sphinx.pocoo.org/markup/inline.html#ref-role
What's natural about that?
In DDoc you have to write $(LINK2 foo.html#bar, bar).
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'. Also, in
d-programming-language.org $(LINK2 x.html#y, y) is used, but $(CHAPTER
x, y) does not exist.
I don't see that as a
solution. For example, if you move MixinDeclaration to declaration.dd,
then
existing link to MixinDeclaration will break because you have to write
$(LINK2
module.html#MixinDeclaration) or define a macro in macro.ddoc, because
DDoc
can't automatically track the targets. This won't happen in reST/Sphinx.
Yes, the idea that a link may be somewhere in a collection files, is
probably better.
And what if, for the unordered list, you wish to add a "class=foo"
attribute for one of them, and "class=bar" for another?
Why would you need to do that?
Style sheets. For example, sometimes you want a list to go out
horizontally rather than vertically; this is controlled by the style
sheet. You specify a class for the list, and then the layout for that
class.
OK.
Anyway, this is also supported by docutils
natively with the '.. class::' directive ('.. rst-class::' in Sphinx):
.. rst-class:: foo
* 1
* 2
* 3
.. rst-class:: bar
* 4
* 5
* 6
http://sphinx.pocoo.org/rest.html#id2
http://docutils.sourceforge.net/docs/ref/rst/directives.html#class
This I don't particularly like. I've got to learn a new syntax for it,
I've got to read and learn a manual on what 'class' means for Sphinx and
do some spelunking to figure out if it is the same thing as an html
class or something different. The syntax arguably isn't better, either.
It's just different. Even worse, if I want to change the classes, I've
got to do a global search/replace. With Ddoc, I change one macro.
You don't have to use '.. class::'! Directives can be manually-defined
also. I'm just illustrating this is possible with the requirement 'you
wish to add a "class=foo" attribute for one of them, and "class=bar" for
another?'
(Also I didn't say _you_ have to learn reST. For instance, the site
could be maintained by some other people in Digital Mars or the D
"committee".)
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.
HTML has lots of these attributes. Are they *all* in Sphinx? What if a
new one is added to HTML? What if I want to use :: in my text? One
problem with a lot of text markup is you've got to provide escapes for
all that - which is why Ddoc pretty much sticks to $.
If you need all of these attributes, why not use raw HTML (yes there is
'.. raw::')? Besides, the output may not be HTML. Sphinx supports LaTeX,
ePub, man page, texinfo, etc. That should also be the same for Ddoc.
You can '::' escape it as ':\:', and '::' is special only at the end of
a line. In Ddoc there is $(LPAREN) and $(RPAREN) and & also.
In Ddoc, for another example, I did the documentation for the Digital
Mars C++ runtime library. For web pages, I formatted things using
definition lists. Unfortunately, those came out badly in the Kindle, but
using h4 instead worked much better. Since I had written the docs in
terms of a higher level Ddoc macro, I simply changed its definition to
use h4 instead of dl, and voila! thousands of library functions got
fixed without incredibly tediously recoding each one.
For me, a viable doc system needs to have some sort of symbolic
redefinition capability. Textual macro processors have existed for a
long time, and they work well for that, which is why Ddoc went that
direction. (You might notice that Ddoc macros are a lot like makefile
macros!)
OK.
(I did consider using the C macro preprocessor, but it is too
specialized for C.)
and by defining the macros, I can set them to use div's, pre's, whatever
attributes I want, and do this as many times as I need to for ALL of the
constructs.
That's not an advantage of DDoc. As I've shown above you could use the
'..
class::' directive to assign classes,
Do I gotta do that every time I write a CPPCODE section?
How is '.. class:: cppcode' different from '$(CPPCODE x)' in terms of
redundancy?
and it's also possible to write your own
directive or inline marker,
That would be better.
more than DDoc's simple macro system can do (e.g. it
can create Phobos's links on the top without relying on Javascript),
and you
could even use the '.. raw::' directive to drop down to HTML.
But whether the document writer want to expose to these capabilities
frequently?
I'd say no, they'd rather have functions to format the document nicely
by default.
The default works well 95% of the time. The rest of the time it doesn't,
and if you have to leave the documentation system, it really sucks.
Furthermore, Sphinx has the '.. code-block::' directive to even syntax
highlight
those C and C++ code for you.
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. OTOH, DDoc doesn't highlight anything besides D (not that it's
an advantage in this context).
I'd rather the source
look good out of the box than having to define dozens of macros to
make it look
good.
The point is, you can customize the macros to match the semantic content
of your documentation. It is not necessarily a low level thing. For
example, I might want to document a library function like this:
$(RTLENTRY name,
$(HEADER name.h)
$(PROTOTYPE
void name();
)
$(DESCRIPTION
name() is the greatest function evar!
)
$(EXAMPLE
name(); // great things happen
)
)
Or some such. Then, by manipulating the definitions of those macros, I
can generate all kinds of different markup. I could set it up as h4's,
h3's, tables, definition lists, etc. I could use a code font for HEADER,
and regular font for DESCRIPTION.
Yes. But as I've argued before, you can't highlight code in $(EXAMPLE a)
without relying on Javascript or other run-time solution.
If I used a markup language with no symbolic ability, I would have to
re-edit everything to change the layout of the output.
This isn't just pie in the sky. I really do write Ddoc stuff like this,
and really do change the layouts searching for something that is more
pleasing.
Yes.
