On 2010-08-06 19:23, Steven Schveighoffer wrote:
On Fri, 06 Aug 2010 11:48:00 -0400, Jacob Carlborg <d...@me.com> wrote:
On 2010-08-06 17:41, Alexander Malakhov wrote:
Steven Schveighoffer <schvei...@yahoo.com> писал(а) в своём письме Fri,
06 Aug 2010 18:28:41 +0700:
2. It seems like the documentation is HTML written as ddoc. I see $(P)
tags, $(LI) tags, etc. Can't we just write it as HTML?
I have had exactly same thought when I've first seen DDoc a week ago
I think many would feel much more comfortable that way.
I have virtually zero exp with HTML/XML, but DDocs syntax seems to be
pretty
straightforward
It's also more supported by editors. I forgot a closing parentheses on
one tag, and it screwed up the entire page. I had to find it by hand,
whereas an HTML editor could red-flag a tag without a closing tag, or
you could run it through an XML verifier (if it's xhtml).
Good points. And XML is not going to disappear anytime soon, so there
will
always be a lot of people familiar with it, as wall as tool for it.
So I think it would be reasonable to have <tag/> syntax and HTML tags
like <B>, <I> etc.
Also, for example, what if I want to put extra ')' paren into $(D text)?
I think there is (simple) solution, but that is one more thing to learn.
In the end it's just markup language and I don't see much use in
learning
more then one of them.
One reason of it I can think of: parsing speed and ambiguities (same as
with <templates>)
Anyway, when D will take over the world, they will have to change HTML
syntax to fit what everyone already knows )
One reason is why HTML is not used directly is that you could output
the documentation in other formats than HTML, like PDF. A second
reason to use macros (i.e. $(B arg)) instead of HTML is that this
allows you to have the macro expand into something like this <span
class="bold">arg</span> instead of <b>arg<b>. Of course one could
define a language in XML to use instead of the macros.
Does ddoc output in pdf? And besides, most of the tags *are* html tags,
they're even the same tag name. I can't imagine there's no htmltopdf
program that would do exactly that.
Regarding the <span class="bold"> thing, can't you just do this in css:
b {
whatever;
}
Many/some of the "style" tags have been deprecated in XHTML/HTML5. Now,
apparently "b" wasn't one of them as I first thought.
and override what <b> does? There are probably macros which do other
things that xhtml/css cannot do, but I don't think we should use macros
for every html element. For example, the $(V1) and $(V2) tags. We need a
good solution for that, and I think having dmd work those out is fine. I
also don't mind using the macros for more dynamic stuff. I just think
the formatting stuff can remain html, and all the macros should be
defined/documented somewhere.
I like this explanation from Alexander:
In the end it's just markup language and I don't see much use in
learning more then one of them.
It's just a thought, it might be blowing out of proportion a bit.
Granted I think I would have felt more comfortable using html directly,
but it wasn't that hard to learn, and I was able to work through the
issues. I just wish I had some editor help...
-Steve
Would it be better to write in XML that then converts it to the output
format?
--
/Jacob Carlborg
