On 5/26/13 4:02 PM, H. S. Teoh wrote:
> On Sun, May 26, 2013 at 03:03:30AM -0400, Andrei Alexandrescu wrote:
>> ESCAPES has been recently defined to partially fix that.
>
> Is it working now?

Yes.

> Oh? I thought TeX already had the capability. Well, at least, you could
> redefine the default escape character "\" to be basically anything,
> including a letter, so you can achieve strange things that way. I'm not
> saying that's a good design though.

I think you can configure things that way, but by default most characters are not active.

> What I'm more concerned with was how to write DDocs that targets output
> formats with incompatible metacharacters or different foreign character
> encodings. For example, if the docs contained a character like é, I'd
> like to be able to specify that it should be translated to \'e when
> targeting LaTeX, and left as-is in HTML, for example. I *could* define a
> macro $(EACUTE) for this purpose, of course, but it makes writing DDocs
> rather painful (why should I resort to $(EACUTE) if the DDoc input is
> already UTF-8 and can already represent such a character directly?).

Agreed.

> Another annoyance, that somebody else already mentioned, is how to wrap
> paragraphs in $(P ...) correctly, as is required for (X)HTML. Currently
> we only have linebreaks, which does not reliably translate to<p>  and
> </p>  with the correct nesting. I've tried to hack around that but still
> cannot get it working correctly in all possible cases. This is rather
> disappointing, since DDoc itself already defines what a paragraph is (or
> at least claims to), yet it doesn't easily lend itself to correct<p>
> nesting. One shouldn't have to dictate the manual use of $(P) in code
> docs in order to generate correct output.

Yah, paragraph breaks are special. LaTeX dedicates them a lot of attention (inserts \parbreak for two \n\n, collapses several consecutive \parbreak occurrences into one etc). Probably ddoc could do better at paragraphs.

> So in short, DDoc as it stands is quite a nice, clean, well-designed
> macro expansion system, but it falls a bit short of being a nice
> *documentation* generation system.

Agreed.


Andrei

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.


T

-- 
Today's society is one of specialization: as you grow, you learn more and more about less and less. Eventually, you know everything about nothing.

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\


Andrei

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.
--------

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. 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). 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).

- Jonathan m Davis

Before we get too off topic in this thread, is there demand for an xhtml5.ddoc file? If so, I'd like to make some changes to the other DDoc files as to minimise code reuse and minimise ambiguity in 'inherited' macro definitions. I'm willing to put in the time but I can't do it alone.

If there's no demand, that's OK, too, and I'll put the matter to rest.

On Mon, May 27, 2013 at 03:04:44AM +0200, Borden wrote:
> Before we get too off topic in this thread, is there demand for an xhtml5.ddoc file? If so, I'd like to make some changes to the other DDoc files as to minimise code reuse and minimise ambiguity in 'inherited' macro definitions. I'm willing to put in the time but I can't do it alone.
> 
> If there's no demand, that's OK, too, and I'll put the matter to rest.

I'm interested in something that will make Ddoc produce properly-nested tags for paragraphs. I'm not *too* concerned whether it will be HTML or XHTML, but I do care that it should be possible to correctly nest things without needing to manually do that with explicit macros in doc comments.


T

-- 
Why is it that all of the instruments seeking intelligent life in the universe are pointed away from Earth? -- Michael Beibl

On 5/26/13 8:33 PM, Jonathan M Davis wrote:
> 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.

I totally think we can. All ddoc has to do is insert some macro call automatically under certain conditions. That wouldn't make it less general because you get to define macros anyway you wanna.

Andrei

On 5/26/13 9:04 PM, Borden wrote:
> Before we get too off topic in this thread, is there demand for an
> xhtml5.ddoc file? If so, I'd like to make some changes to the other DDoc
> files as to minimise code reuse and minimise ambiguity in 'inherited'
> macro definitions. I'm willing to put in the time but I can't do it alone.
>
> If there's no demand, that's OK, too, and I'll put the matter to rest.

I think it would be great. In particular, an ebook format would be good.

You may want to wait until https://github.com/D-Programming-Language/dlang.org/pull/271 is in. It systematizes macros a lot and it may offer answers to many of your questions.

Andrei

On Sunday, May 26, 2013 22:08:44 Andrei Alexandrescu wrote:
> On 5/26/13 8:33 PM, Jonathan M Davis wrote:
> > 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.
> 
> I totally think we can. All ddoc has to do is insert some macro call automatically under certain conditions. That wouldn't make it less general because you get to define macros anyway you wanna.

Well, if we can do it, great. I hate having to use $(P). But it does involve dmd inserting stuff on its own based on the format for the text rather than using macro expansion (much as what it inserts would presumably be macros to expand). However, as long as we can do that, it should be quite feasible.

- Jonathan M Davis

On 5/26/13 10:12 PM, Jonathan M Davis wrote:
> On Sunday, May 26, 2013 22:08:44 Andrei Alexandrescu wrote:
>> On 5/26/13 8:33 PM, Jonathan M Davis wrote:
>>> 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.
>>
>> I totally think we can. All ddoc has to do is insert some macro call
>> automatically under certain conditions. That wouldn't make it less
>> general because you get to define macros anyway you wanna.
>
> Well, if we can do it, great. I hate having to use $(P). But it does involve
> dmd inserting stuff on its own based on the format for the text rather than
> using macro expansion (much as what it inserts would presumably be macros to
> expand). However, as long as we can do that, it should be quite feasible.

Already does that on ---- as noted. True, that makes ddoc less simple.

Andrei