some changes to ddoc

[adamdruppe]

Here's some details:
http://forum.dlang.org/thread/igiihgtmsaptfvfbtozz@forum.dlang.org

These are breaking changes, but everyone I've asked has thought
they are good ideas, and it is pretty easy to fix what it breaks.

There's two things in here:

1. change PSYMBOL to give both toChars() and toPrettyChars(), for better anchor generation

2. kill the embedded html feature, since it is more trouble than its worth. Instead, we'll use the ESCAPES system to encode input in a user defined fashion and macros to output html.

Aside from the expected breakage, it seems to work very well.

[WalterBright]

I have no idea what this comment means.

[adamdruppe]

On Sun, Mar 18, 2012 at 08:01:23PM -0700, Walter Bright wrote:

I have no idea what this comment means.

I think I was talking to myself...

The idea is to do the special character encoding right
before macro expansion.

This way, everything the user typed in their doc comment
gets encoded properly*, but the macros can still be used
to output raw HTML.

• if you type

/// A < B

The proper output for html is

A < B

So the user sees in their browser the same text you typed here.

[brad-anderson]

1. change PSYMBOL to give both toChars() and toPrettyChars(), for better anchor generation

A recent thread in D.learn reminded me of this. Any chance you could break just this change out into a separate pull request? This hits users all the time.

[andralex]

Not sure this has enough design behind it; I fear one day we'll find other stuff that's "almost" doable with tables but not quite. Anyhow, PSYMBOL seems noncontroversial and useful as @eco mentioned. @adamdruppe, any chance you could extricate that one into a separate diff?

[adamdruppe]

On Tue, Sep 25, 2012 at 08:45:25AM -0700, Andrei Alexandrescu wrote:

Not sure this has enough design behind it; I fear one day we'll find other stuff that's "almost" doable with tables but not quite.

This needs a solution, so perhaps we should start discussing the
problem again.

The status quo makes documenting an XML library with examples extremely
painful and doing varied output types with macros outright impossible, as different
outputs have different special characters that need escaping....

We need to find something that works. The character table is a pretty good solution,
and combined with macros I can't think of a document format where it wouldn't work...

Anyhow, PSYMBOL seems noncontroversial and useful as @eco mentioned. @ adamdruppe, any chance you could extricate that one into a separate diff?

Yeah, I should start it over since it's been a long time and I forgot
how this works.

Let's close this one and make a new pull later.

[ntrel]

Inspired by this DDOC_PSYMBOL change, I made pull #1174. The implementation is somewhat different, but it solves the same problem.