DLang Spec rewrite (?)

[H. S. Teoh]

On Sun, May 26, 2013 at 05:33:58PM -0700, Jonathan M Davis wrote:
> On Sunday, May 26, 2013 13:20:41 H. S. Teoh wrote:
> > On Sat, May 25, 2013 at 10:34:30PM -0700, Jonathan M Davis wrote:
> > [...]
> > 
> > > My main complaint about ddoc is actually not a complaint about
> > > ddoc but about html. I find it very annoying to have to put $(P )
> > > around every paragraph. Stuff like LaTeX does that automatically
> > > based on blank lines, which is way better IMHO, but if you're
> > > targetting HTML, then unfortunately, you need to mark paragraphs.
> > > The only way to fix that with regards to ddoc would be to make it
> > > so that ddoc understood that blank lines meant new paragraphs and
> > > inserted <p></p> appropriately, when generating html, but that
> > > would make it so that ddoc was less general, and there might be
> > > other negatives to that I haven't thought of. So, we just get to
> > > deal with $(P ) I guess.
> > 
> > [...]
> > 
> > Wait, why not just make DDoc wrap it in $(P ) instead of <p></p>?
> > That way, output formats that don't care can simply define $(P) to
> > be the text followed by a line break, and you're done.
> 
> I don't follow. The issue is that right now I have to do
> 
> --------
> $(P Here is my paragraph.)
> 
> $(P Here is another paragraph.)
> --------
> 
> Whereas in something like latex, I'd just do
> 
> --------
> Here is my paragraph.
> 
> Here is another paragraph.
> --------

Well, yes, this is exactly what I was talking about.


> When ddoc is run, the $(P content) gets translated to <p>content</p>
> in html, and into my second example for latex. But what I want to be
> able to do is write the second example and have html end up with
> <p>content</p>. And _that_ doesn't work, because it would require that
> dmd know about <p> and insert it for me instead of ddoc just being
> pure macros.

But right now, Ddoc already translates blank lines to $(BLANKLINE) (or
something like that). I'm just saying that paragraphs in the input
should be recognized as such, and automatically wrapped in $(P ...).
Then you can either define P=<p>$0</p> for HTML, or P=$0\n for LaTeX.


> It would be simple enough to run a program over the .dd file before
> running it through dmd in order to add the $(P) macros were
> appropriate, but then I have to worry about getting the logic right on
> that, and things like code examples could screw with that (you
> wouldn't want to insert $(P) into code examples).

That's easy: code examples are delimited by ----. Ddoc already treats
those differently from normal running text, so I don't see why it would
be a problem to say that paragraphs in normal text will automatically be
wrapped in $(P).


> So, while it's quite feasible, I'm just putting up with $(P) for now.
> But we can't have a general ddoc solution for this without changing
> how ddoc works in a way that makes it so that it's not just a macro
> system anymore.  Without another program to massage the ddoc in your
> file first, you're stuck with $(P).

Which is ugly. One of those nagging things that detract from my
enjoyment of Ddoc.


[...]
On Sun, May 26, 2013 at 06:32:43PM -0400, Andrei Alexandrescu wrote:
> On 5/26/13 4:20 PM, H. S. Teoh wrote:
> >Wait, why not just make DDoc wrap it in $(P ) instead of<p></p>? That
> >way, output formats that don't care can simply define $(P) to be the
> >text followed by a line break, and you're done.
> 
> I thought it already does that.
> 
> git grep -i '<p>' **/*.{c,h}
> src/doc.c:P =     <p>$0</p>\n\
[...]

But you have to explicitly write $(P ...) around your paragraphs, no?


T

-- 
Skill without imagination is craftsmanship and gives us many useful
objects such as wickerwork picnic baskets.  Imagination without skill
gives us modern art. -- Tom Stoppard