subject:"Improving ddoc"

2015-01-02 Thread Joseph Rushton Wakeling via Digitalmars-d


On 1/2/2015 1:06 AM, Andrei Alexandrescu wrote:

Maybe not even *bold*. Good documentation uses bold sparingly, and most uses of
bold in dlang.org should actually be code. -- Andrei


I agree. Excessive use of bold is like shouting at people - it's wearying to 
read. Pull any programming book off the shelf and flip through it. There's very 
little use of bold.

Re: Improving ddoc


On 02/01/15 22:40, Adam D. Ruppe via Digitalmars-d wrote:

On Friday, 2 January 2015 at 21:23:52 UTC, Joseph Rushton Wakeling via
Digitalmars-d wrote:

Er, I believe I posted an example of just that :-)


error stray paren :) Uh oh, another one!

It actually is kinda a pity to me that it is such a common character.


/**
  You know the worst thing?  I can't use emoticons
  in my ddoc ;-)

  This makes me very sad, and I can't even express
  my sadness without generating another warning. :-(

  Although I can, speaking tongue in cheek, see how some
  people might consider that a bonus. :-P
 */


Imagine if macros were: ¤“name ‗ argument ‗ arg2”!


But I don't suppose we can ask people to map hotkeys to conveniently write the
docs either :(


Seriously: how feasible could it be to address the issue by delineating the 
start and end of macros by a _pair_ of characters, reducing the chance of ambiguity?


$(NEW_MACRO this would be the new macro system)$

Re: Improving ddoc

2015-01-02 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:

On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote:

Please show some context where that frequently happens for you.

I see some instances in Phobos, but they are all of the form:

   [x .. y$(RPAREN)

which would be better coded as:

   $(INTERVAL x .. y)

   INTERVAL=[$0$(RPAREN)


See, this is my point.  $(INTERVAL x .. y) is, to my mind, less clear to
read _in the source_ than [x, y).

If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval
between x and y.  But is it the closed interval [x, y], one of the
half-open intervals (x, y] or [x, y) or the open one (x, y) ... ?

I need that kind of precision to document the kind of code I'm writing
(including phobos contributions), and I would like to be able to read
and write with that precision explicitly in the source.  If I need to
use a macro definition, then the reader has to look up that definition,
and you just _know_ that people are going to use those macros
incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people
will use it in circumstances where they mean [x, y] or (x, y) or whatever.

Yes, I could use a right-bracket UTF8 character, but that's finnicky and
annoying (and potentially runs into other problems for readers, e.g.
what if someone copy-pastes my ddoc source into a non-UTF8 email?).  And
yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more
specialist and likely to be confusing to readers.

I'm sorry, but I can't see it as anything other than a serious flaw of
ddoc that a super-common character in both code and mathematics has
problems being used, as itself, inside the documentation markup :-)


Serious flaw sounds like a serious exaggeration. The notation [x, y) 
has unpaired parens. Any tool relying on pairing parens is going to have 
difficulty with it.


This is exactly the kind of argument that diminishes the value of an 
otherwise great notion - that ddoc needs improvements addressing pain 
points with it.



Andrei

Re: Improving ddoc

2015-01-02 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 7:01 AM, Ary Borenszweig wrote:

1. Add * foo syntax for lists


Currently ddoc ignores leading * so we'd need another character if at all.


2. Add **bold** and __bold__


How necessary are these?


3. Add *italic* and _italic_


Maybe these would be more often useful.


4. Make `some text` automatically link to other D code. For example
`std.algorithm.any` would automatically link to
http://dlang.org/phobos/std_algorithm.html#.any . This must work for
types, functions, etc. If it doesn't resolve to a symbol, just put it
inside code.../code


Nice.


5. Make [text](url) denote a link.


Nice.


6. Remove macros.


We probably can't do that.

Thanks!


Andrei

Re: Improving ddoc

2015-01-02 Thread Jacob Carlborg via Digitalmars-d


On 2015-01-02 10:40, Andrei Alexandrescu wrote:


* A list of summary with all symbols should be automatically generated
for a module


Shouldn't we leave that to postprocessing?


No, why would we do that? I want be able to easily generate good 
documentation. If something requires an extra step to make it better it 
will not be as easy.


I also think it will be easier for Ddoc to do this than doing it in a 
postprocess step:


* Ddoc will already have all the information available

* The postprocessing tool will need to parse the output to get this 
information


* If Ddoc is supposed to be designed for multiple output formats the 
postprocessing tool need to be able to handle that as well.


Also, it should be possible to disable this if it's not desired.


* A nice tree view with all packages and modules with filter for all
symbols


This seems like a matter of styling, not functionality.


I don't see how this can be a matter of styling if it should support 
filtering.


I'm thinking of something like the Scala documentation I linked to [1]. 
It has something more like a flat list with different sections. It 
doesn't matter if you call it styling of functionality ;) I still would 
like to see it in the default output.


[1] http://www.scala-lang.org/api/current/#scala.collection.Iterable

--
/Jacob Carlborg

Re: Improving ddoc

2015-01-02 Thread via Digitalmars-d


On Thursday, 1 January 2015 at 22:38:05 UTC, Jacob Carlborg wrote:
That are just a couple of suggestions. Just take a look at some 
existing documentation for other language and see what's 
missing [1], [2].


[1] 
http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html


[2] 
http://www.scala-lang.org/api/current/#scala.collection.Iterable


To me Ddoc documentation is different from javadoc-flavored 
documentation and rightfully so. Ddoc is module centered with 
some nice introduction at the top and includes helpful unittest 
examples, too. Where OO-centered reference documentation puts 
comments to all classes and methods, Ddoc allows (and encourages) 
documentation that can be read to learn about the module. You 
know, I am your average troll, spending my time reading 
documentation. Pure reference documents are no fun to read.

Re: Improving ddoc

2015-01-02 Thread Jacob Carlborg via Digitalmars-d


On 2015-01-02 02:31, ketmar via Digitalmars-d wrote:


i think that in most cases you can use `r...` instead. and if you
really want backticks, you can use dedicated code block for that.


One really good use case for backticks is when the string contains 
double quotes.


--
/Jacob Carlborg

Re: Improving ddoc

2015-01-02 Thread Jacob Carlborg via Digitalmars-d


On 2015-01-02 10:10, Andrei Alexandrescu wrote:

On 1/1/15 7:01 AM, Ary Borenszweig wrote:

1. Add * foo syntax for lists


Currently ddoc ignores leading * so we'd need another character if at all.


A dash.

--
/Jacob Carlborg

Re: Improving ddoc

2015-01-02 Thread Steven Schveighoffer via Digitalmars-d


On 1/1/15 4:39 AM, Walter Bright wrote:

On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:

On 12/31/14 1:12 PM, Dicebot wrote:

I don't feel like any small change in DDOC will make me like/use it.


I'm envisioning quite an interesting possibility in which certain
constructs are
automatically converted to macros:

`hello world` -- $(BACKQUOTED hello world)
hello world -- $(QUOTED hello world)
'hello world' -- $(SQUOTED hello world)
_hello world_ -- $(UNDERLINED hello world)
*hello world* -- $(STARRED hello world)

... and such. Then generating nice formatting for each of these
constructs is
achieved by simply defining these macros appropriately.


 and ` naturally come in pairs, but *, _ and ' do not.



What about #[{( anything inside here can use markdown )}]#

I'm half joking about the brackets, but some method of saying in here, 
I permit markdown would make this both backwards compatible, and not 
inflict too much damage to readability of ddoc.


In fact, if you did something like:

/**[[
   ... comments with markdown
]]*/

or something like this at the beginning of each ddoc comment, it would 
be almost unnoticeable.


I'd also suggest giving a toggling mechanism, something like:

/**
  $(MARKDOWN true/false)
**/

Which allows one to set the default for the enclosed ddocs.

That's my contribution to the project :) I wish I could actually code it...

-Steve

Re: Improving ddoc

2015-01-02 Thread Steven Schveighoffer via Digitalmars-d


On 1/1/15 4:46 AM, ketmar via Digitalmars-d wrote:

On Thu, 01 Jan 2015 01:30:58 -0800
Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com
wrote:


On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote:

sorry about you, though, as you didn't seem to tell anything like that
except some messages that (it seems) just trying to stop the flamefest.
mea culpa.


It would be awesome indeed if the civil atmosphere in this forum would
be restored. I very much hope in your help with this. -- Andrei


i'm trying to do my best. honestly! ;-) i'm deleting first two or three
variants of many replies. so my answers looks perfectly calm for me...
until i see them posted. yet i'll try to improve than situation in this
year. maybe deleting first ten variants, i don't know... ;-)



This is a frequent habit of mine, I always re-read my posts until I feel 
comfortable that I wouldn't mind reading it (most of the time, it takes 
at least 2 reviews).


Anything especially antagonistic usually gets extra scrutiny :)

If NNTP posted replies as I typed them, I would be banned for sure...

-Steve

Re: Improving ddoc

2015-01-02 Thread via Digitalmars-d


On Thursday, 1 January 2015 at 20:15:55 UTC, Walter Bright wrote:
A lot of the complaints about Ddoc clearly stem from people not 
realizing they can create their own macros. It's like not


On the contrary, the complaint is that you can create your own 
macros and loose the semantics of the markup.


I looked at the possibility to create a high quality javascript 
based front end to phobos documentation last year and the messy 
macro-markup/generated html killed the project before it got 
started.


Math notation uses a ton of special characters, it's one of the 
reasons why Unicode was invented. Limiting yourself to 
non-Markdown ascii is extremely limiting. Heck, look at this:


https://www.google.com/search?q=latex+math+symbolsbiw=1282bih=897tbm=ischtbo=usource=univsa=Xei=pqqlVLbcM5TkoATv9oGABgsqi=2ved=0CDQQsAQ


LaTeX is not a standard. It is a quick'n'dirty macro-hack over 
TeX.


If you want to mark up math, use HTML5's MathML and use MathJax 
for browsers that don't fully support it.


http://www.w3.org/Math/

http://www.mathjax.org/sponsors/

Re: Improving ddoc


On 1/2/2015 1:34 AM, Andrei Alexandrescu wrote:

On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:

I do however still think that using $( ) to delineate start and end of
macro blocks is a bad choice given the prevalence of ( ) in code.


s/think/believe/ seeing as you bring awfully little evidence to back that up. --
Andrei


The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an 
issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it).


Grep the Phobos sources, the only stray paren issue in it is the use of [..) in 
a few places in the documentation. I know it's irritating for you, but it simply 
is not prevalent.

Re: Improving ddoc

2015-01-02 Thread Joseph Rushton Wakeling via Digitalmars-d


On 1/2/2015 1:42 PM, Adam D. Ruppe wrote:

On Friday, 2 January 2015 at 21:36:52 UTC, Walter Bright wrote:

I agree. Excessive use of bold is like shouting at people - it's wearying to
read. Pull any programming book off the shelf and flip through it. There's
very little use of bold.


Aye, my opinion now is that `code` is the only really important one. I can live
without the others.

List, table, and link might be nice, but totally non-essential in my eyes; plain
ASCII or recursive macros look good enough to me.


I agree. I was telling Andrei last night what a good idea you'd had.

Re: Improving ddoc


On 03/01/15 01:11, Walter Bright via Digitalmars-d wrote:

An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of a
rather simple piece of code.


Very much so, and your point elsewhere in this thread about how valuable it is 
to have a built-in documentation tool is absolutely spot-on.  A story to 
illustrate this ...


A few days ago I had a go at building and installing the rust compiler (no, I'm 
not jumping ship, I just decided it was about time I started getting some proper 
hands-on understanding of some of the alternative design approaches out 
there:-).  This uses pandoc to generate documentation, which in turn evokes 
pdflatex, xelatex or lualatex, with the last of these being the preferred option.


One ./configure  make later, and after quite a bit of compilation, the 
compiler itself was built -- at which point, the makefile tried to go on and 
build the documentation, and failed, for reasons I still don't understand (it 
was the lualatex command that was failing, but the error message was not very 
clear in conveying what the actual problem was).


OK, well, the compiler is built, right?  So let's try 'make install' ... oh no, 
the first thing it tries to do is to complete the 'make all' target and build 
the docs, and of course that fails, so it doesn't install anything. :-\


Now, full credit to the rust community: they were immediately friendly and 
helpful in advising me how to deal with this (you can pass a flag to the 
./configure command to request not to build the docs).  And of course you can 
see this as primarily a fault in how the build system defines its targets and 
their dependencies.  But the simple fact is, had documentation generation been 
built in rather than relying on 3rd-party tools, it would never have been an 
issue, _and_ I'd have ended up having the documentation as well as just the 
compiler executable and libraries.

Re: Improving ddoc

2015-01-02 Thread Tobias Müller via Digitalmars-d

Joseph Rushton Wakeling via Digitalmars-d digitalmars-d@puremagic.com
wrote: 
 Three things I'm not sure about: (i) does it allow definitions of custom
 macros as with Ddoc (although I'm not sure how necessary that is in
 practice); (ii) I have a nasty feeling its @keyword markup syntax (e.g.
 @return @param etc.) might not play nice with D code examples; (iii) I
 suspect we'd have to do some integration work getting D support into
 Doxygen in order to enjoy the best of all its features.

AFAIK @keyword is javadoc style (but supported by doxygen) and original
doxygen style uses \keyword.

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d


On 1/2/2015 1:23 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:

I can live with you not addressing my irritation :-)  But since we're discussing
how to improve Ddoc, I thought it best to make sure that my issues with it were
well described and understood.



I like to think I do understand the issue :-) even if I don't agree with many 
conclusions.


An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of a 
rather simple piece of code.

Re: Improving ddoc

On 01/01/15 21:15, Walter Bright via Digitalmars-d wrote:

My point is there's ALWAYS going to be some sort of escaping mechanism, and it
is ALWAYS going to interfere with the look of anyone who wants to use the full
character set on the keyboard, which IS going to happen whenever you write math
text.

Yes, I accept that. I'm just pointing out what I find problematic with this
particular escaping mechanism, given the documentation needs of the code I'm
involved with.

I do however still think that using $( ) to delineate start and end of macro
blocks is a bad choice given the prevalence of ( ) in code.

Before I reply to the rest of your email, I think I should point out two things:

* I understand that ddoc is a macro system, I understand what that
means and how flexible and powerful it can be (I've used LaTeX for
years, and I have created my own custom ddoc macros). I'm not
trying to persuade you to give that up.

* I'm not trying to advocate for you to start supporting markdown,
although I do understand why some people are.

* LaTeX maths notation on the other hand ... ;-)
- actually I'm mostly raising this last point to
tease you, but there is a serious side; I'll
explain later in the email.

Anyway, to some details ...

You don't have to call it INTERVAL. You can write your own macro to name it
whatever works for you. I do it all the time. You can even then change the
definition of the macro and, for example, have it styled differently (like use a
different font, different font weight, different color, etc.) I find that very
handy.

Yes, I understand that I can write different macros to mean different things.
But surely you can understand my point from the previous email, that having 4
different macros to indicate the different types of intervals, is much less nice
from a reading/writing point of view than just being able to write, in ASCII,
[x, y], (x, y], [x, y) and (x, y).

It's not just maths notation either -- this will trigger the 'Stray )' warning
too:

Example:

auto u = uniform![)(0.0, 1.0);

I think we can achieve that simplicity of reading, not just for these two
examples, but for potentially quite a bit more maths and code, without
sacrificing any of the things you're interested in keeping.

A lot of the complaints about Ddoc clearly stem from people not realizing they
can create their own macros. It's like not realizing that C code can contain
custom written functions.

Here's one example that was brought up in the discussion:

https://github.com/D-Programming-Language/phobos/pull/2828

A custom macro made all the difference. Not only that, it is now easy to switch
it from a table to a definition list, or have custom styling for it, all without
messing anything else up. This cannot be done with Markdown.

You might ask why would we want custom styling? Turns out that that example is
a nice one for why not use it.

Yes, and nothing I say here should be taken as denying the usefulness or
desirability of being able to do that.

BTW talking of custom macros and custom styling, that file has something I
consider to be a horrendous violation of good styling design in it:

MYREF = font face='Consolas, Bitstream Vera Sans Mono, Andale Mono,
Monaco, DejaVu Sans Mono, Lucida Console, monospace'a
href=#.$1$1/anbsp;/font

Math notation uses a ton of special characters, it's one of the reasons why
Unicode was invented. Limiting yourself to non-Markdown ascii is extremely
limiting. Heck, look at this:

https://www.google.com/search?q=latex+math+symbolsbiw=1282bih=897tbm=ischtbo=usource=univsa=Xei=pqqlVLbcM5TkoATv9oGABgsqi=2ved=0CDQQsAQ

Sure, but even with unicode, there's a limit to how sanely you can represent a
complex formula in plain-text. Personally, this is the point where I'd rather
be able to use inline LaTeX formulas, because I think most people interested in
complex formulas will be able to understand that.

Please don't dismiss this idea out of hand: I think there are some handy tools
we could use to integrate this very well into our documentation system. Using
the MathJax javascript makes it pretty easy to embed LaTeX formulas into an HTML
document:

http://www.mathjax.org/

... and obviously when outputting to LaTeX, it becomes much easier to just hand
on LaTeX formulas as they are.

If we could do something like,

$(MATH F(x) = \int_{0}^{10} f(x) dx )

then it would be very nice. Obviously this won't work notationally quite as-is,
but I don't see why it shouldn't be possible to find something similar that is
workable.

(N.B. this is a definite Dream Wishlist item, so please don't see it as the
main concern of my email; if it isn't workable, just tell me that and move on to
the end of the email, where there is the point I really would like your feedback
on.)

Isn't * a super common math character? and |? and +? All of which are markdown
characters.

Re: Improving ddoc


On 2015-01-01 14:28, Andrej Mitrovic via Digitalmars-d wrote:


The wxWidgets developers maintain a hand-written set of doxygen
interface files because doxygen actually crashes when trying to parse
the C++ code directly.

As a result the documentation is frequently out of date. I remember
filing numerous patches to fix their docs (over 100 of them), it was
blatantly out of date[1].

We would have the same problem with D. Any time there were syntax
changes in D we would have to fix doxygen to be able to parse D code
again.


I'm pretty sure I read on the Clang mailing list that someone wants to 
use Clang to extract doxygen comments.


--
/Jacob Carlborg

Re: Improving ddoc


On 2015-01-01 01:21, Rikki Cattermole wrote:


Following this, we could extend this one altogether.
AST entry points. Read only (later maybe not) full access to dmd-fe AST.


So we're back at AST macros :). I don't mind but I don't think it's the 
right solution in this case.


--
/Jacob Carlborg

Re: Improving ddoc


On 2015-01-01 01:44, Rikki Cattermole wrote:


The AST stuff would guaranteed be a DIP (second to last CTFE
implementation type, well as I define it anyway).


http://wiki.dlang.org/DIP50 ;)

--
/Jacob Carlborg

Re: Improving ddoc


On 2014-12-31 20:50, Andrei Alexandrescu wrote:


One simple starter would be to allow one escape character, e.g. the
backtick (`), as a simple way to expand macros: instead of $(MACRO arg1,
arg2) one can write `MACRO arg1, arg2`.


I don't see how that would improve anything, at all.

--
/Jacob Carlborg

Re: Improving ddoc


On 2015-01-01 16:09, Dicebot wrote:

My top list of md shortcuts for casual documentation:

1. `code`

2. * lists

headers
3. ===


I prefer the hashtag syntax:

# header

## header

--
/Jacob Carlborg

Re: Improving ddoc


On 1/1/2015 7:09 AM, Dicebot wrote:

headers
3. ===


   headers:

Re: Improving ddoc

On Thu, 01 Jan 2015 11:57:37 -0800
Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote:

 Is also hard to read. Yes, I'm being facetious, but take a look at those 
 examples posted here about how ugly Ddoc is - they're of that category.
and you know why? 'cause nobody cares to make 'em human readable, as
it's almost impossible with Ddoc. so why someone should waste his time
on that?

on contrary, human-readable markup tend to be formatted to be actually
human-readable.

yet i will not argue anymore, as you seem to ignore the fact that most
people don't want to do DTP in API documentation.

this is very easy to judge: just preapprove markdown-like parser for
documentation (without throwing off Ddoc) and then see what people will
use most of the time. i bet you know the answer.


signature.asc
Description: PGP signature

Re: Improving ddoc

On Thu, 01 Jan 2015 15:40:30 +0100
Joseph Rushton Wakeling via Digitalmars-d digitalmars-d@puremagic.com
wrote:

 On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
  Again those are: *bold* and `code`.
 
 I would be inclined to prefer ``code`` or ```code```, simply because it's 
 valid 
 D syntax to have,
 
  auto someString = `Some great big string`;
 
i think that in most cases you can use `r...` instead. and if you
really want backticks, you can use dedicated code block for that.


signature.asc
Description: PGP signature

Re: Improving ddoc

On Thu, 01 Jan 2015 21:51:06 +0100
Jacob Carlborg via Digitalmars-d digitalmars-d@puremagic.com wrote:

 On 2015-01-01 16:09, Dicebot wrote:
  My top list of md shortcuts for casual documentation:
 
  1. `code`
 
  2. * lists
 
  headers
  3. ===
 
 I prefer the hashtag syntax:
 
 # header
 
 ## header

there is nothing wrong in supporting both. ;-)


signature.asc
Description: PGP signature

Re: Improving ddoc

On Thu, 01 Jan 2015 01:07:37 -0800
Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote:

 And lastly, the general problem users have with documentation in Phobos is 
 not 
 that it is written in Ddoc. That has NOTHING to do with it, it's an excuse. 
 Nobody has yet taken me up on my offer to take their text documentation and 
 add 
 markup for them. Few people being willing to write good content is the 
 problem. 
 No documentation tool can fix that. Non-existent documentation can be not 
 written using any tool.
Adam already told that people who can write good documentation is
rarely need it. so they just DON'T HAVE that documentation written in
the way it can be useful for others. so the only way to make such
people write something is to make documentation formatting unintrusive.
Ddoc IS intrusive.

i can fix something if i can read it, and i can't read that Ddoc mess.
so i'm going to dlang.org to look at the dox instead of looking it
right in the Phobos sources. and if i see something that can/should be
fixed on dlang.org... ah, well, i have to drop the thing i was doing,
open another terminal, go to Phobos source directory, find the file
with the dox, then find the place to fix... screw it, i was looking at
documentation for doing completely different things!

but see, if Phobos documentation is human-readable without
preprocessing, it's WAY EASIER for me to just open Phobos source file
and look there. and guess what i'll do if i'll see that something needs
fixing there? yep, i'll fix that, 'cause i'm already at the place that
needs fixing. the process is not distractive. and then i can do 'git
diff' and send a patch.

the whole point is that Ddoc is *not* *human* *readable*. so why i
should look to Phobos sources and try to decipher it? and i don't want
to drop whatever i was doing to go from the site to Phobos. and when i
done with my task, i already forgot what requires fixing (or exhausted
and don't want to do it).

i understand that D is your child, and you are working on it with
passion. but for me D is the tool to solve my tasks. i'm ready to help
improving that tool, but only if that's as easy as possible for me.
when i done with my task, i already know what i wanted to know, so
there is little sense in fixing that. i'm done with it, now i remember
it. or at least remember in which of my source files i should look
when i need to refresh my memory (yep, i'm looking for usage samples
and patterns in my sources if i can, 'cause it's way easier to open
another source file for me than to go to some webpage, even local one).

that's why i'm advocating human-readable markup. it's easier to read.
it's easier to write. it's easier to fix. it can be used without
preprocessor. any decent IDE (and even my patched mcedit) can open
source file with function definition in one or two clicks.

i can't fix it inplace -- i will not fix it. i can't do 'git diff' with
it -- i will not fix it. i can't read it -- i will not fix it. and all
this is solvable, even without sacrificing your beloved Ddoc: we can
have BOTH markdown-like and Ddoc simultaneously. do that and see what
language people will prefer to use.


signature.asc
Description: PGP signature

Re: Improving ddoc


On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:

On 12/31/14 1:12 PM, Dicebot wrote:

I don't feel like any small change in DDOC will make me like/use it.


I'm envisioning quite an interesting possibility in which certain constructs are
automatically converted to macros:

`hello world` -- $(BACKQUOTED hello world)
hello world -- $(QUOTED hello world)
'hello world' -- $(SQUOTED hello world)
_hello world_ -- $(UNDERLINED hello world)
*hello world* -- $(STARRED hello world)

... and such. Then generating nice formatting for each of these constructs is
achieved by simply defining these macros appropriately.


 and ` naturally come in pairs, but *, _ and ' do not.

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 1:34 AM, ketmar via Digitalmars-d wrote:

i can fix something if i can read it, and i can't read that Ddoc mess.
so i'm going to dlang.org to look at the dox instead of looking it
right in the Phobos sources. and if i see something that can/should be
fixed on dlang.org... ah, well, i have to drop the thing i was doing,
open another terminal, go to Phobos source directory, find the file
with the dox, then find the place to fix... screw it, i was looking at
documentation for doing completely different things!

but see, if Phobos documentation is human-readable without
preprocessing, it's WAY EASIER for me to just open Phobos source file
and look there. and guess what i'll do if i'll see that something needs
fixing there? yep, i'll fix that, 'cause i'm already at the place that
needs fixing. the process is not distractive. and then i can do 'git
diff' and send a patch.


All you need is a mail client seeing as Walter offered you twice to 
email him any fixes you have and he'll integrate them for you. (Not to 
mention you refuse to use github etc.) Honestly if someone would pass 
similarly constructed arguments by you, would you put any weight on 
their opinion? I find your posts oddly awesome. Such cognitive 
dissonance is the stuff of legends. -- Andrei

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote:

sorry about you, though, as you didn't seem to tell anything like that
except some messages that (it seems) just trying to stop the flamefest.
mea culpa.


It would be awesome indeed if the civil atmosphere in this forum would 
be restored. I very much hope in your help with this. -- Andrei

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 12/31/14 10:17 PM, Manu via Digitalmars-d wrote:

On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d
digitalmars-d@puremagic.com wrote:

Hello,


In wake of the recent discussions on improving ddoc syntax we're looking at
doing something about it. Please discuss any ideas you might have here.
Thanks!

One simple starter would be to allow one escape character, e.g. the backtick
(`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one
can write `MACRO arg1, arg2`.


I don't really have any particular opinions on this topic, but the
only feeling I've really had in the past is, why is it so different
from doxygen?
Most people are already familiar with doxygen.

Why is doxygen insufficient? Is there a reason ddoc was invented
rather than supporting the practically-industry-standard doxygen
format from the start?


No particular system was clearly dominant when Walter invented ddoc. 
Also I might be frequenting the wrong circles; most people I know and 
myself aren't fluent at all with doxygen. -- Andrei

Re: Improving ddoc


On 12/31/2014 3:19 PM, ketmar via Digitalmars-d wrote:
 Walter and Andrei seems to be sure that Ddoc is human-readable,

It doesn't help  matters when the examples posted to show how unreadable Ddoc 
is are both misuse of Ddoc and extremely poor whitespace formatting, comparing 
it with carefully formatted Markdown.


I've seen this repeatedly in that thread, by multiple authors, including you. It 
is not compelling any more than if I tried to show D was better than C++ by 
showing sloppy and incompetently written C++ code.




 anything less
powerful than Ddoc will be rejected with arbitrary reason (see Walter
posts about escaping in markdown, for example).


The complaint was made about needing escaping in Ddoc, and then it is arbitrary 
when I point out that all markup languages need escaping, including Markdown?



And lastly, the general problem users have with documentation in Phobos is not 
that it is written in Ddoc. That has NOTHING to do with it, it's an excuse. 
Nobody has yet taken me up on my offer to take their text documentation and add 
markup for them. Few people being willing to write good content is the problem. 
No documentation tool can fix that. Non-existent documentation can be not 
written using any tool.


Some have been recently stepping up to create PRs to fix documentation in 
Phobos. That's what we need, and I thank the people doing it: aldacron, 
AndrejMitrovic, JakobOvrum, quickfur, ntrel, andralex, klickverbot, kiith-sa, 
Dicebot, schveiguy to name some.

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 1:39 AM, Walter Bright wrote:

On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:

On 12/31/14 1:12 PM, Dicebot wrote:

I don't feel like any small change in DDOC will make me like/use it.


I'm envisioning quite an interesting possibility in which certain
constructs are
automatically converted to macros:

`hello world` -- $(BACKQUOTED hello world)
hello world -- $(QUOTED hello world)
'hello world' -- $(SQUOTED hello world)
_hello world_ -- $(UNDERLINED hello world)
*hello world* -- $(STARRED hello world)

... and such. Then generating nice formatting for each of these
constructs is
achieved by simply defining these macros appropriately.


 and ` naturally come in pairs, but *, _ and ' do not.


Stars and underlines are popular due to markdown. There'd be 
limitations, e.g. pairs occurring across a ddoc parent won't be 
considered for expansion etc. Also the defaults can be written to be 
idempotent. (Below I am removing the single quote because indeed it's 
not fitting):


BACKQUOTED=`$0`
QUOTED=$0
UNDERLINED=_$0_
STARRED=*$0*

So essentially we get to start 100% backward compatible and figure out 
under what circumstances the macros expand. I think we can get this working.



Andrei

Re: Improving ddoc

On Thu, 01 Jan 2015 01:30:58 -0800
Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com
wrote:

 On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote:
  sorry about you, though, as you didn't seem to tell anything like that
  except some messages that (it seems) just trying to stop the flamefest.
  mea culpa.
 
 It would be awesome indeed if the civil atmosphere in this forum would 
 be restored. I very much hope in your help with this. -- Andrei

i'm trying to do my best. honestly! ;-) i'm deleting first two or three
variants of many replies. so my answers looks perfectly calm for me...
until i see them posted. yet i'll try to improve than situation in this
year. maybe deleting first ten variants, i don't know... ;-)


signature.asc
Description: PGP signature

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 12/31/14 10:00 PM, ketmar via Digitalmars-d wrote:

On Thu, 1 Jan 2015 05:50:18 + (UTC)
Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com
wrote:


That's unfair. You wouldn't us to give in to emotional arguments that lack
reason. Make good points and they'll be minded. -- Andrei


After you refused my offer to add in the Ddoc for you, saying you
weren't going to write documentation regardless, it's hard to put
much weight on your opinion about it.


Sadly indeed that muffles any point you're trying to make around here. 
Time for a New Year Resolution? :o) -- Andrei

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 12/31/14 1:12 PM, Dicebot wrote:

I don't feel like any small change in DDOC will make me like/use it.


I'm envisioning quite an interesting possibility in which certain 
constructs are automatically converted to macros:


`hello world` -- $(BACKQUOTED hello world)
hello world -- $(QUOTED hello world)
'hello world' -- $(SQUOTED hello world)
_hello world_ -- $(UNDERLINED hello world)
*hello world* -- $(STARRED hello world)

... and such. Then generating nice formatting for each of these 
constructs is achieved by simply defining these macros appropriately.



Andrei

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d

On Thu, 01 Jan 2015 01:43:13 -0800
Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com
wrote:

 On 1/1/15 1:34 AM, ketmar via Digitalmars-d wrote:
  i can fix something if i can read it, and i can't read that Ddoc mess.
  so i'm going to dlang.org to look at the dox instead of looking it
  right in the Phobos sources. and if i see something that can/should be
  fixed on dlang.org... ah, well, i have to drop the thing i was doing,
  open another terminal, go to Phobos source directory, find the file
  with the dox, then find the place to fix... screw it, i was looking at
  documentation for doing completely different things!
 
  but see, if Phobos documentation is human-readable without
  preprocessing, it's WAY EASIER for me to just open Phobos source file
  and look there. and guess what i'll do if i'll see that something needs
  fixing there? yep, i'll fix that, 'cause i'm already at the place that
  needs fixing. the process is not distractive. and then i can do 'git
  diff' and send a patch.
 
 All you need is a mail client seeing as Walter offered you twice to 
 email him any fixes you have and he'll integrate them for you. (Not to 
 mention you refuse to use github etc.) Honestly if someone would pass 
 similarly constructed arguments by you, would you put any weight on 
 their opinion? I find your posts oddly awesome. Such cognitive 
 dissonance is the stuff of legends. -- Andrei

you seem to miss my point completely. i'm *not* doing any fixes at all.
if Phobos documentation will be human-readable, i will not go to
dlang.org ever, i will use Phobos sources instead. i.e. i will look for
documentation right in the Phobos sources, not on some website. and
surely, it's easy to fix something if the file where it must be fixed
is already open in your editor, and exatly on the place which needs
fixing. but going from website all way down to Phobos src, and then
struggling with Ddoc... no, thanks. i'm not reading that dox for fun
and enjoyment. if i'm reading dox it means that i got some problem that
i need to solve, and distracting me for too long from that problem is
destructive for my workflow. fixing something that is already before my
eyes and ready to be edited is ok. dropping my work to fix something
that is both far away and requires to grasp non-readable formatting is
no-no.

having human-readable formatting for documentation solves that problem.
it's still possible to generate standalone dox with it, but it's now
possible to read dox without generating anything, just in place where
that dox was created. and most existing dox can be magically converted
to human-readable format too.


signature.asc
Description: PGP signature

Re: Improving ddoc


On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:

No particular system was clearly dominant when Walter invented ddoc. Also I
might be frequenting the wrong circles; most people I know and myself aren't
fluent at all with doxygen. -- Andrei


It is really trivial to learn and quite effective.  I used it years ago for a 
C/C++ project; when I encountered Ddoc my reaction was, OK, it's basically a 
custom and slightly weirder-looking variant of Doxygen...


It has some _very_ nice features such as the easy inclusion of LaTeX formulas 
into documentation, and in my experience Doxygen markup is much more 
readable-in-source than Ddoc.


Three things I'm not sure about: (i) does it allow definitions of custom macros 
as with Ddoc (although I'm not sure how necessary that is in practice); (ii) I 
have a nasty feeling its @keyword markup syntax (e.g. @return @param etc.) might 
not play nice with D code examples; (iii) I suspect we'd have to do some 
integration work getting D support into Doxygen in order to enjoy the best of 
all its features.

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 2:10 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:

On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote:

But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
but the fact that doc comments can *only* be processed by ddoc. If there
was a way to get the raw text out, the people who dislike ddoc can pipe
it to the formatter of their own choice, and they would be happy. People
who are indifferent will get ddoc by default, which, despite its flaws,
isn't really *that* horrible.


That's pretty much the very charter of ddoc- most misunderstood tool
ever.
Luckily I'll send some pull requests that simplify generation - some time
next year :o)


My problem is very much the opposite: it's not that only ddoc can
process ddoc syntax, it's that raw ddoc syntax is, often, not very
human-readable.  For me it's very important that the documentation
should be trivially comprehensible _when browsing source code_, and too
often Ddoc markup prevents that.


Got it. I think auto-macroizing would help with that. -- Andrei

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d


On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote:

But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
but the fact that doc comments can *only* be processed by ddoc. If there
was a way to get the raw text out, the people who dislike ddoc can pipe
it to the formatter of their own choice, and they would be happy. People
who are indifferent will get ddoc by default, which, despite its flaws,
isn't really *that* horrible.


That's pretty much the very charter of ddoc- most misunderstood tool ever.
Luckily I'll send some pull requests that simplify generation - some time
next year :o)


My problem is very much the opposite: it's not that only ddoc can process ddoc 
syntax, it's that raw ddoc syntax is, often, not very human-readable.  For me 
it's very important that the documentation should be trivially comprehensible 
_when browsing source code_, and too often Ddoc markup prevents that.

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:

On 31/12/14 20:50, Andrei Alexandrescu via Digitalmars-d wrote:

One simple starter would be to allow one escape character, e.g. the
backtick
(`), as a simple way to expand macros: instead of $(MACRO arg1, arg2)
one can
write `MACRO arg1, arg2`.


Would that be accompanied by deprecation and removal of the $(MACRO
arg1, arg2) syntax?


No.


I ask because for me, one of the biggest annoyances of Ddoc (in terms of
source readability of the docs) is having to use $(RPAREN) in order to
avoid Ddoc accidentally seeing a macro where there is none.


cd code/d/phobos
git grep RPAREN | wc -l
  28

RPAREN is indeed more frequent in dlang.org:

cd code/d/phobos
git grep RPAREN | wc -l
  589

Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The 
majority are in changelog.dd; I guess a couple of macros might help there.



Andrei

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:

On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:

No particular system was clearly dominant when Walter invented ddoc.
Also I
might be frequenting the wrong circles; most people I know and myself
aren't
fluent at all with doxygen. -- Andrei


It is really trivial to learn and quite effective.


Totally. I did use it briefly a few years ago and I'm sure I can relearn it.

My point here was to give context for ddoc's history. FWIW switching 
dlang and phobos now to doxygen would be a major effort and I'm not sure 
we'd be in a better place even after assuming perfect execution.



Andrei

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d


On 31/12/14 20:50, Andrei Alexandrescu via Digitalmars-d wrote:

One simple starter would be to allow one escape character, e.g. the backtick
(`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can
write `MACRO arg1, arg2`.


Would that be accompanied by deprecation and removal of the $(MACRO arg1, arg2) 
syntax?


I ask because for me, one of the biggest annoyances of Ddoc (in terms of source 
readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc 
accidentally seeing a macro where there is none.

Re: Improving ddoc

On Thu, 01 Jan 2015 01:47:27 -0800
Andrei Alexandrescu via Digitalmars-d digitalmars-d@puremagic.com
wrote:

 Stars and underlines are popular due to markdown.
we were using that long before markdown was invented. FIDOnet,
newsgroups with UUCP, you name it.


signature.asc
Description: PGP signature

Re: Improving ddoc


On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote:

Stars and underlines are popular due to markdown. There'd be limitations, e.g.
pairs occurring across a ddoc parent won't be considered for expansion etc. Also
the defaults can be written to be idempotent. (Below I am removing the single
quote because indeed it's not fitting):

BACKQUOTED=`$0`
QUOTED=$0
UNDERLINED=_$0_
STARRED=*$0*

So essentially we get to start 100% backward compatible and figure out under
what circumstances the macros expand. I think we can get this working.


Ddoc assumes ( ) nests. But this would require that these characters nest, too:

   *abc_def * _i

for example, which is stretching things a bit because they do not naturally 
nest.

Re: Improving ddoc

On Thursday, 1 January 2015 at 10:16:01 UTC, Andrei Alexandrescu 
wrote:
My point here was to give context for ddoc's history. FWIW 
switching dlang and phobos now to doxygen would be a major 
effort and I'm not sure we'd be in a better place even after 
assuming perfect execution.


I don't think the current documentation of phobos is affecting 
(professional) D adoption much, although it can improve a lot. 
Adoption is a language/compiler/runtime/tooling issue.


On the other hand, if converting phobos' Ddoc into Doxygen cannot 
be automated, then that suggests that there is a fundamental 
problem with how Ddoc is used as a markup tool.


Adopting Doxygen would give you some benefits:

- it makes D look less weird

- it makes it easier to use existing formatting/presentation 
solutions


- it is more motivating to learn Doxygen than figuring out Ddoc 
since you can use it for non-D projects


The Doxygen front page advertises the following:

«it also supports other popular programming languages such as C, 
Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and 
UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent 
D.»


D would look better without the to some extend and you might 
get the Doxygen community to help out with Doxygen relevant 
tooling issues if it is the default D documentation tool. 
Basically an opportunity for synergy.

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d


On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote:

Why is doxygen insufficient? Is there a reason ddoc was invented
rather than supporting the practically-industry-standard doxygen
format from the start?


There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2 or 3 
people used it.


The problem was Doxygen was some add on tool. It was not part of the 
downloadable D package. It couldn't be. Anyone wanting to use Doxygen was going 
to have to:


1. pray a version exists on the platform they have that D is installed on.
2. pray that version was the one the D docs were expecting.
3. buy Doxygen.
4. download and install Doxygen successfully.
5. Doxygen is a large and complex tool - lots of work to understand it.
6. expect the D community to provide tech support with Doxygen is not working 
on my D documents.


The end result was, essentially nobody used Doxygen. In fact, nobody used any 
sort of documentation system, and we know what the result looked like - your 
typical out-of-date, totally wrong, or non-existent normally found with C and 
C++ projects.


Ddoc, being:

1. always there
2. always the correct version
3. Ddoc is trivial to learn and use

revolutionized the D documentation. And that's an understatement.

Re: Improving ddoc


On 01/01/15 11:21, Andrei Alexandrescu via Digitalmars-d wrote:

cd code/d/phobos
git grep RPAREN | wc -l
   28


It's a bugbear for std.random because I find myself writing things like:

/**
$(D uniform01) offers a faster generation of random variates than
the equivalent $(D uniform![$(RPAREN)(0.0, 1.0)) and so may be
preferred for some applications.

Returns:
Floating-point random variate of type $(D T) drawn from the uniform
distribution across the half-open interval [0, 1$(RPAREN).
 */

With respect to my other remarks in this thread, the example above is one of the 
single most annoying human-unreadable things I encounter: I would really, really 
like mathematics and inline code examples in the docs to not need escaping in 
this manner, so that it's as easy as possible to compare and contrast docs and 
code in the source file.


I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-(

Re: Improving ddoc


On Thursday, 1 January 2015 at 00:44:33 UTC, Adam D. Ruppe wrote:
I'd actually prefer to focus more on ddoc's unique strengths - 
that it understands the compiler's scoping rules.


If I understand this correctly, it seems very compelling to me. 
Would it be an option to


1. Work on ddoc (as it is now) to be even closer to the compiler 
(e.g. scoping rules)
2. Add a carefully selected markdown on top of proper ddoc (e.g. 
use ddoc instead of html as fallback)

3. Provide ddoc macro definitions to generate all kinds of output

This would help in several ways

1. The fully functional ddoc system that can do books remains 
available. There is use for it.
2. The code documentation could be much more lightweight (but 
still have the full ddoc macros available if needed)
3. Generating to pandoc or the like. There are converters out 
there.


If any of this is of any value, I am happy to help to make it 
happen.

Re: Improving ddoc

On 1/1/2015 3:09 AM, Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= 
ola.fosheim.grostad+dl...@gmail.com wrote:

Adopting Doxygen would give you some benefits:


Doxygen is developed under Mac OS X and Linux, but is set-up to be highly 
portable. As a result, it runs on most other Unix flavors as well. Furthermore, 
executables for Windows are available.


  -- http://www.stack.nl/~dimitri/doxygen/

There are no packages for FreeBSD, for example.

Doxygen is GPL, but appears to be supported by only one person.


There is also nothing stopping anyone from using Doxygen if they prefer it.

Re: Improving ddoc


On 1/1/2015 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:

I ask because for me, one of the biggest annoyances of Ddoc (in terms of source
readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc
accidentally seeing a macro where there is none.


Please show some context where that frequently happens for you.

I see some instances in Phobos, but they are all of the form:

  [x .. y$(RPAREN)

which would be better coded as:

  $(INTERVAL x .. y)

  INTERVAL=[$0$(RPAREN)

Re: Improving ddoc


On 1/1/2015 3:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:

I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-(


Other than the:

  $(INTERVAL 0, 1)

macro, you can use:

  rparen;

or the unicode rbbrk; which looks like a right ) :

  [0, 1❳

You can also use:

  [0, 1[

which is actually an international standard notation:

  http://en.wikipedia.org/wiki/ISO_31-11#Sets

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d


On 1/1/2015 2:21 AM, Andrei Alexandrescu wrote:

Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The
majority are in changelog.dd; I guess a couple of macros might help there.


There are also things in the language spec documentation like:

  $(B $(LPAREN) $(RPAREN))

which are simply unnecessary. Instead:

  $(B ( ))

Re: Improving ddoc


On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote:

Please show some context where that frequently happens for you.

I see some instances in Phobos, but they are all of the form:

   [x .. y$(RPAREN)

which would be better coded as:

   $(INTERVAL x .. y)

   INTERVAL=[$0$(RPAREN)


See, this is my point.  $(INTERVAL x .. y) is, to my mind, less clear to read 
_in the source_ than [x, y).


If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x 
and y.  But is it the closed interval [x, y], one of the half-open intervals (x, 
y] or [x, y) or the open one (x, y) ... ?


I need that kind of precision to document the kind of code I'm writing 
(including phobos contributions), and I would like to be able to read and write 
with that precision explicitly in the source.  If I need to use a macro 
definition, then the reader has to look up that definition, and you just _know_ 
that people are going to use those macros incorrectly, e.g. if we suppose that 
INTERVAL is [x, y), then people will use it in circumstances where they mean [x, 
y] or (x, y) or whatever.


Yes, I could use a right-bracket UTF8 character, but that's finnicky and 
annoying (and potentially runs into other problems for readers, e.g. what if 
someone copy-pastes my ddoc source into a non-UTF8 email?).  And yes, I could 
use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely 
to be confusing to readers.


I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that 
a super-common character in both code and mathematics has problems being used, 
as itself, inside the documentation markup :-)

Re: Improving ddoc

2015-01-01 Thread Andrej Mitrovic via Digitalmars-d

On 1/1/15, Andrei Alexandrescu via Digitalmars-d
digitalmars-d@puremagic.com wrote:
 Totally. I did use it briefly a few years ago and I'm sure I can relearn
 it.

The wxWidgets developers maintain a hand-written set of doxygen
interface files because doxygen actually crashes when trying to parse
the C++ code directly.

As a result the documentation is frequently out of date. I remember
filing numerous patches to fix their docs (over 100 of them), it was
blatantly out of date[1].

We would have the same problem with D. Any time there were syntax
changes in D we would have to fix doxygen to be able to parse D code
again.

Anyway, maybe we can do something about ddoc and make it easier to
use. I'm just saying the grass isn't necessarily greener on the other
side.

[1]: http://trac.wxwidgets.org/search?ticket=onq=dreypage=13noquickjump=1

Re: Improving ddoc

On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:
My problem is very much the opposite: it's not that only ddoc 
can process ddoc syntax, it's that raw ddoc syntax is, often, 
not very human-readable.


Yeah. The enormous irony is the #1 ddoc justification - and one 
of the big reasons doxygen or xml wasn't used IIRC - is


1. It looks good as embedded documentation, not just after it is 
extracted and processed.


2. It's easy and natural to write, i.e. minimal reliance on 
tags and other clumsy forms one would never see in a finished 
document.


http://dlang.org/ddoc.html

blargh :(

Re: Improving ddoc

2015-01-01 Thread Piotrek via Digitalmars-d

On Thursday, 1 January 2015 at 13:28:39 UTC, Andrej Mitrovic via 
Digitalmars-d wrote:


Anyway, maybe we can do something about ddoc and make it easier 
to use. I'm just saying the grass isn't necessarily greener

on the other side.


+1. Every documentation tool has its problems. IMO, changing 
documentation system from the dedicated one would be a step 
backwards.


Piotrek

Re: Improving ddoc

2015-01-01 Thread ponce via Digitalmars-d


On Thursday, 1 January 2015 at 14:16:05 UTC, Adam D. Ruppe wrote:
On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:
My problem is very much the opposite: it's not that only ddoc 
can process ddoc syntax, it's that raw ddoc syntax is, often, 
not very human-readable.


Yeah. The enormous irony is the #1 ddoc justification - and one 
of the big reasons doxygen or xml wasn't used IIRC - is


1. It looks good as embedded documentation, not just after it 
is extracted and processed.


2. It's easy and natural to write, i.e. minimal reliance on 
tags and other clumsy forms one would never see in a finished 
document.


http://dlang.org/ddoc.html

blargh :(


I actually like DDoc as it is, and finds it readable.
Markdown is readable and all but the specifications are just 
insane.

http://commonmark.org/

Re: Improving ddoc


On Thursday, 1 January 2015 at 11:33:25 UTC, Walter Bright wrote:
Ddoc assumes ( ) nests. But this would require that these 
characters nest, too:


   *abc_def * _i

for example, which is stretching things a bit because they do 
not naturally nest.


I think someone who writes *long bold text

like this*

is in error anyway; I lose track of what those stars are supposed 
to me. (BTW the gmail html to text converter does this, making 
emails unreadable to me!)



I would say the pattern to match would be \w\*[a-zA-Z0-9]+\*\w.


Honestly, I think _foo_ and /foo/ are both not worth supporting 
in this context. *bold* is the only one we really need - the most 
common, and the least ambiguous.


We do NOT want it to think *a = *b; is supposed to be bolding. We 
do NOT want it to think _object._method is supposed to be 
underlined. We do NOT want it to think /bin/bash is supposed to 
be italic. (Granted, those might be in code blocks anyway, but 
still, no point making this harder than it has to be.)


But when would you write *a* = foo in code? Never, I don't think 
that's ever valid. So making that a $(STARRED) macro should just 
work in pretty much all circumstances.



And we can always fall back on $(B bold) and $(I italic) when we 
do need them.





I just think shooting for an 80% solution is more reasonable than 
a 99 or 100% solution - just do the easiest, least ambiguous 
shortcuts and use macros for the rest of them. It'll probably go 
a LONG way.


Again those are: *bold* and `code`.

Re: Improving ddoc

On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:
I would be inclined to prefer ``code`` or ```code```, simply 
because it's valid D syntax to have,


auto someString = `Some great big string`;


Eh, that breaks my habit from stack overflow. How often do you 
write an inline `raw string` anyway? It'd still just work inside 
---\ncode\n--- blocks, and you could still do $(D_CODE auto s = 
`code`;) if you wanted to.

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d


On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote:

I actually like DDoc as it is, and finds it readable.


You know, if $(D_CODE) escaped the code properly and `code` was a 
shortcut to it... that'd actually solve my big complaints with 
the ddoc language itself and make it convenient.


Really, those are the two things I want, I don't really care 
about the rest of the argument. Maybe it is PR time.

Re: Improving ddoc


On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:

Again those are: *bold* and `code`.


I would be inclined to prefer ``code`` or ```code```, simply because it's valid 
D syntax to have,


auto someString = `Some great big string`;

Re: Improving ddoc

2015-01-01 Thread Ary Borenszweig via Digitalmars-d


On 12/31/14 4:50 PM, Andrei Alexandrescu wrote:

Hello,


In wake of the recent discussions on improving ddoc syntax we're looking
at doing something about it. Please discuss any ideas you might have
here. Thanks!

One simple starter would be to allow one escape character, e.g. the
backtick (`), as a simple way to expand macros: instead of $(MACRO arg1,
arg2) one can write `MACRO arg1, arg2`.


Andrei


1. Add * foo syntax for lists
2. Add **bold** and __bold__
3. Add *italic* and _italic_
4. Make `some text` automatically link to other D code. For example 
`std.algorithm.any` would automatically link to 
http://dlang.org/phobos/std_algorithm.html#.any . This must work for 
types, functions, etc. If it doesn't resolve to a symbol, just put it 
inside code.../code

5. Make [text](url) denote a link.
6. Remove macros. Walter said: Oh, Markdown can't be used to change the 
typography, generate TOCs, etc.?. Well, you don't need to do those 
things. Changing the typography will make it look ugly. You need a TOC? 
That's the job of the documentation tool (the binary), not the 
documentation syntax.


Basically, use Markdown :-)

Keep DDoc as it is now. Use it for your website if you want, to write 
books or whatever. But for documentation don't use it as it is. There's 
no need for macros. There's no need to generate JSON, XML, YAML, PDF or 
anything other than HTML, which is quite universal and accessible now.


I repeat: keep DDoc, enhance it, use it as dog food for your websites, 
books, etc. Use something simpler and less powerful for documenting 
types and functions.

Re: Improving ddoc

2015-01-01 Thread ponce via Digitalmars-d

On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:

On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:

Again those are: *bold* and `code`.


I would be inclined to prefer ``code`` or ```code```, simply 
because it's valid D syntax to have,


auto someString = `Some great big string`;


Github, Stack Overflow, trac and others use one single escape 
quote.

Re: Improving ddoc

2015-01-01 Thread Dicebot via Digitalmars-d


My top list of md shortcuts for casual documentation:

1. `code`

2. * lists

   headers
3. ===

   --
4. | tables | that are  |
   --
   | pretty | in source |
   --

Re: Improving ddoc

On 1 January 2015 at 19:33, Andrei Alexandrescu via Digitalmars-d
digitalmars-d@puremagic.com wrote:
 On 12/31/14 10:17 PM, Manu via Digitalmars-d wrote:

 On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d

 digitalmars-d@puremagic.com wrote:

 Hello,


 In wake of the recent discussions on improving ddoc syntax we're looking
 at
 doing something about it. Please discuss any ideas you might have here.
 Thanks!

 One simple starter would be to allow one escape character, e.g. the
 backtick
 (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one
 can write `MACRO arg1, arg2`.


 I don't really have any particular opinions on this topic, but the
 only feeling I've really had in the past is, why is it so different
 from doxygen?
 Most people are already familiar with doxygen.

 Why is doxygen insufficient? Is there a reason ddoc was invented
 rather than supporting the practically-industry-standard doxygen
 format from the start?


 No particular system was clearly dominant when Walter invented ddoc.

Okay.

 Also I might be frequenting the wrong circles; most people I know and myself 
 aren't
 fluent at all with doxygen. -- Andrei

What do you tend to use instead?

I miss doxygen's '\' tags. For instance, '\a argName' to refer to a
function argument argName, which will be formatted appropriately and
all that. I find it a lot less visually distracting.
It might also be interesting to note that doxygen implemented markdown
support quite some time back, so I think there's precedent for people
expecting that markdown be available for use in their documentation.

Re: Improving ddoc

On 1 January 2015 at 20:02, Joseph Rushton Wakeling via Digitalmars-d
digitalmars-d@puremagic.com wrote:
 On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:

 No particular system was clearly dominant when Walter invented ddoc. Also
 I
 might be frequenting the wrong circles; most people I know and myself
 aren't
 fluent at all with doxygen. -- Andrei


 It is really trivial to learn and quite effective.  I used it years ago for
 a C/C++ project; when I encountered Ddoc my reaction was, OK, it's
 basically a custom and slightly weirder-looking variant of Doxygen...

 It has some _very_ nice features such as the easy inclusion of LaTeX
 formulas into documentation, and in my experience Doxygen markup is much
 more readable-in-source than Ddoc.

 Three things I'm not sure about: (i) does it allow definitions of custom
 macros as with Ddoc (although I'm not sure how necessary that is in
 practice); (ii) I have a nasty feeling its @keyword markup syntax (e.g.
 @return @param etc.) might not play nice with D code examples; (iii) I
 suspect we'd have to do some integration work getting D support into Doxygen
 in order to enjoy the best of all its features.

Doxygen supports both @param and \param.
It would be really good if doxygen supported D comprehensively. I
often port C code to D which already has doxygen commentary. I never
port the doxygen docs to ddoc though.

Re: Improving ddoc

On 1 January 2015 at 20:16, Andrei Alexandrescu via Digitalmars-d
digitalmars-d@puremagic.com wrote:
 On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:

 On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:

 No particular system was clearly dominant when Walter invented ddoc.
 Also I
 might be frequenting the wrong circles; most people I know and myself
 aren't
 fluent at all with doxygen. -- Andrei


 It is really trivial to learn and quite effective.


 Totally. I did use it briefly a few years ago and I'm sure I can relearn it.

 My point here was to give context for ddoc's history. FWIW switching dlang
 and phobos now to doxygen would be a major effort and I'm not sure we'd be
 in a better place even after assuming perfect execution.

I was thinking more along the lines of letting doxygen inspire
enhancements to ddoc, since as far as I can see, it's pretty much the
standard these days, and people already know it.

Re: Improving ddoc


On Thursday, 1 January 2015 at 15:09:22 UTC, Dicebot wrote:

My top list of md shortcuts for casual documentation:

1. `code`


https://github.com/D-Programming-Language/dmd/pull/4228


That's by far my #1 syntax-wise, and since my implementation uses 
the existing code, it will be relevant semantically too at some 
point - when the code examples get cross-referencing, inline bits 
will too, so we can link with that too (probably*).


The others aren't even really important to me at all; $(HEADER 
foo) or Foo: both look good enough for me. Tables might be nice, 
but overall aren't that big of a deal to me.



* A potential problem running it through that D highlighter is 
not all `code` is necessarily D code. But most of it is and the 
rest still seems to work well enough - my xml tag test passed - 
so I think it is the biggest win for ddoc.

Re: Improving ddoc


On Thursday, 1 January 2015 at 12:05:03 UTC, Walter Bright wrote:
There is also nothing stopping anyone from using Doxygen if 
they prefer it.


Sure, but there is a big advantage in having a the same tech doc 
format for all libraries for the same language/group of languages.


I've spent way too much time learning new essential languages, so 
learning a new one for a fringe activity like writing tech docs 
is not going to happen.


Picking a common subset of an existing markup language will 
reduce resistance to learning the one D is using. Doxygen syntax 
is a good candidate if you want people to write uniform docs for 
D libraries. Especially if D is going to continue to focus on C++ 
integration.

Re: Improving ddoc

2015-01-01 Thread Dicebot via Digitalmars-d


On Thursday, 1 January 2015 at 15:21:40 UTC, ponce wrote:
On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:

On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:

Again those are: *bold* and `code`.


I would be inclined to prefer ``code`` or ```code```, simply 
because it's valid D syntax to have,


   auto someString = `Some great big string`;


Github, Stack Overflow, trac and others use one single escape 
quote.


And such snippet is much more likely to go into dedicated code 
block:


```
auto someString = `Some great big string`;
```

than as an inline snippet.

Re: Improving ddoc

On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig 
wrote:
it is. There's no need for macros. There's no need to generate 
JSON, XML, YAML, PDF or anything other than HTML, which is 
quite universal and accessible now.


You only need to generate XML with high quality semantic markup 
for programming languages. From XML to other formats there are 
more options than this thread can handle...


The semantics of HTML is too weak to build high quality 
cross-library-indexing and precise search rankings.

Re: Improving ddoc

On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig 
wrote:
What's cross-library-indexing? You mean show documentation for 
many libraries at once?


Yes, many libraries, source code with builtin links, links to 
github with line numbers, docs for other languages when D 
wrappers are provided. The ideal is to propagate as much useful 
information as possible to a normalized universal format that 
makes it easy to build intelligent information systems using some 
kind of deduction. You should generate a database, not a document.


HTML is underpowered and assumes that domain specific semantical 
information is encoded in a different layer like RDF, but that 
leads to solutions that are overly complicated compared to a 
domain specific XML format.

Re: Improving ddoc

2015-01-01 Thread Joseph Rushton Wakeling via Digitalmars-d

On 1 January 2015 at 21:51, Walter Bright via Digitalmars-d
digitalmars-d@puremagic.com wrote:
 On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote:

 Why is doxygen insufficient? Is there a reason ddoc was invented
 rather than supporting the practically-industry-standard doxygen
 format from the start?


 There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2
 or 3 people used it.

 The problem was Doxygen was some add on tool. It was not part of the
 downloadable D package. It couldn't be. Anyone wanting to use Doxygen was
 going to have to:

 1. pray a version exists on the platform they have that D is installed on.
 2. pray that version was the one the D docs were expecting.
 3. buy Doxygen.
 4. download and install Doxygen successfully.
 5. Doxygen is a large and complex tool - lots of work to understand it.
 6. expect the D community to provide tech support with Doxygen is not
 working on my D documents.

 The end result was, essentially nobody used Doxygen. In fact, nobody used
 any sort of documentation system, and we know what the result looked like -
 your typical out-of-date, totally wrong, or non-existent normally found with
 C and C++ projects.

 Ddoc, being:

 1. always there
 2. always the correct version
 3. Ddoc is trivial to learn and use

 revolutionized the D documentation. And that's an understatement.

I'm not arguing that it wasn't an excellent decision to include a doc
parser in DMD, but I don't think any of those advantages are
attributed to the ddoc syntax specifically so much as just including
it in the compiler.
I'm sure the ddoc syntax is fine. It's just noisy and hard to read, as
I think we've established to be the popular opinion.

I'm just suggesting that DMD could also parse some useful subset of
doxygen as ddoc shorthand. I don't think parsing doxygen would be
particularly difficult. Basically all the suggestions here so far,
like the markdown bits are valid doxygen.

Re: Improving ddoc

2015-01-01 Thread H. S. Teoh via Digitalmars-d

On Thu, Jan 01, 2015 at 01:19:06AM -0800, Andrei Alexandrescu via Digitalmars-d 
wrote:
 On 12/31/14 1:12 PM, Dicebot wrote:
 I don't feel like any small change in DDOC will make me like/use it.
 
 I'm envisioning quite an interesting possibility in which certain
 constructs are automatically converted to macros:
 
 `hello world` -- $(BACKQUOTED hello world)
 hello world -- $(QUOTED hello world)
 'hello world' -- $(SQUOTED hello world)
 _hello world_ -- $(UNDERLINED hello world)
 *hello world* -- $(STARRED hello world)
 
 ... and such. Then generating nice formatting for each of these
 constructs is achieved by simply defining these macros appropriately.
[...]

Nice idea, but I think _..._ will have to be left out, due to the
prevalence of special meanings of _ currently in use. For example, _abc
currently means abc without any automatic highlighting (e.g., if abc
were a parameter or function name); _abc: at the beginning of a line
means a literal word abc where otherwise abc: would mean a section
heading abc; and abc_def: means a section heading with two words abc
def.

I anticipate that overloading _ to do even more than this will only lead
to a nasty mess where it's impossible for the non-expert to figure out
what it actually means.


T

-- 
The early bird gets the worm. Moral: ewww...

Re: Improving ddoc

2015-01-01 Thread Ary Borenszweig via Digitalmars-d

On 1/1/15 1:23 PM, Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= 
ola.fosheim.grostad+dl...@gmail.com wrote:

On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig wrote:

it is. There's no need for macros. There's no need to generate JSON,
XML, YAML, PDF or anything other than HTML, which is quite universal
and accessible now.


You only need to generate XML with high quality semantic markup for
programming languages. From XML to other formats there are more options
than this thread can handle...

The semantics of HTML is too weak to build high quality
cross-library-indexing and precise search rankings.


What's cross-library-indexing? You mean show documentation for many 
libraries at once?

Re: Improving ddoc


On 01/01/15 17:16, Manu via Digitalmars-d wrote:

Doxygen supports both @param and \param.


Ah yes, I'd forgotten that.  It's been a while :-\


It would be really good if doxygen supported D comprehensively. I
often port C code to D which already has doxygen commentary. I never
port the doxygen docs to ddoc though.


Did you ever try preserving the docs and continuing to use doxygen to generate 
them?  If so, how did it go?  Or is that an outright impossibility?

Re: Improving ddoc

2015-01-01 Thread Ary Borenszweig via Digitalmars-d

On 1/1/15 2:35 PM, Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= 
ola.fosheim.grostad+dl...@gmail.com wrote:

On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig wrote:

What's cross-library-indexing? You mean show documentation for many
libraries at once?


Yes, many libraries, source code with builtin links, links to github
with line numbers, docs for other languages when D wrappers are
provided. The ideal is to propagate as much useful information as
possible to a normalized universal format that makes it easy to build
intelligent information systems using some kind of deduction. You should
generate a database, not a document.

HTML is underpowered and assumes that domain specific semantical
information is encoded in a different layer like RDF, but that leads to
solutions that are overly complicated compared to a domain specific XML
format.


I really don't understand why you say that.

I just started writing a documentation generator for the Crystal 
programming language.


http://crystal-lang.org/api/

You can read about its features here:

http://crystal-lang.org/2014/12/31/crystal-0.5.6-release.html

Now, I go here

http://dlang.org/phobos/std_file.html

and I can't believe that after 10+ years of development, D documentation 
still doesn't have a basic feature like inter-linking between types (I 
even once submitted a PR but it wasn't accepted because other code was 
written on top of it and then the merge was hard to do). For example:


http://dlang.org/phobos/std_file.html#.timeLastModified

I should be able to click SysTime and go to that type definition.

But, DDoc can generate Latex.

Then, take a look at Rust. Guess what they use for their documentation? 
Markdown! Here's a web framework called Iron:


http://ironframework.io/

Here are the API docs:

http://ironframework.io/doc/iron/

Let's take a look at enum.Method:

http://ironframework.io/doc/iron/method/enum.Method.html

See that red String text? Click it and it takes you here:

http://doc.rust-lang.org/nightly/collections/string/struct.String.html

Wow! It took you to the String definition in an entirely different host!

Back to Crystal's docs, below every method there's a View Source link 
that takes you to that code in GitHub. No such thing in D.


Note that all of this was done with just Markdown (HTML) and by making 
the documentation generator understand and use the language as much as 
possible, something with DDoc doesn't do. I once submitted a PR to fix 
that, but it was ignored.


I would suggest D to use a simple language to write the documentation, 
and then a powerful tool that understands the semantics of the language 
and allows you to generate good looking, easily browsable documentation. 
Neither JSON, XML, YAML or macros are needed for that.

Re: Improving ddoc

2015-01-01 Thread JN via Digitalmars-d

On Thursday, 1 January 2015 at 18:15:10 UTC, Ary Borenszweig 
wrote:
and I can't believe that after 10+ years of development, D 
documentation still doesn't have a basic feature like 
inter-linking between types (I even once submitted a PR but it 
wasn't accepted because other code was written on top of it and 
then the merge was hard to do). For example:


http://dlang.org/phobos/std_file.html#.timeLastModified

I should be able to click SysTime and go to that type 
definition.


Don't know why it's not working for Phobos, but vibe.d 
documentation seems to have clickable types 
(http://vibed.org/api/)

Re: Improving ddoc


On Thursday, 1 January 2015 at 14:37:31 UTC, Adam D. Ruppe wrote:

On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote:

I actually like DDoc as it is, and finds it readable.


You know, if $(D_CODE) escaped the code properly and `code` was 
a shortcut to it... that'd actually solve my big complaints 
with the ddoc language itself and make it convenient.


For a preview how this might look like:

perl -p -e 's/\$\(D 
([^\$()]*+(\((?:[^\$()]*+|(?1))*\))*[^\$()]*)\)/`$1`/g' 
std/algorithm.d | less

Re: Improving ddoc

2015-01-01 Thread Andrei Alexandrescu via Digitalmars-d


On 1/1/15 3:32 AM, Walter Bright wrote:

On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote:

Stars and underlines are popular due to markdown. There'd be
limitations, e.g.
pairs occurring across a ddoc parent won't be considered for expansion
etc. Also
the defaults can be written to be idempotent. (Below I am removing the
single
quote because indeed it's not fitting):

BACKQUOTED=`$0`
QUOTED=$0
UNDERLINED=_$0_
STARRED=*$0*

So essentially we get to start 100% backward compatible and figure out
under
what circumstances the macros expand. I think we can get this working.


Ddoc assumes ( ) nests. But this would require that these characters
nest, too:

*abc_def * _i

for example, which is stretching things a bit because they do not
naturally nest.


No nesting. Again I'm talking simple rules. They should get us a ton of 
mileage. -- Andrei

Re: Improving ddoc