• "H. S. Teoh" <hsteoh quickfur.ath.cx> May 26 2013

"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:

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