On Sunday, May 26, 2013 02:44:30 Borden wrote: > On Saturday, 25 May 2013 at 23:28:46 UTC, Jonathan M Davis wrote: > > aside from you, I'm not aware of anyone complaining about it > > any time recently. > > Good evening, Jonathan, > > I'm not sure whether you mean that nobody's complained recently > about the spec being in DDoc lately, because, as in my first > link, I found that more people disliked the macros feature of > DDoc (2 + me) than liked it (0).
AFAIK, your recent posts on ddoc are the first that anyone has complained about it in quite some time. There are plenty of folks who want various improvements to the online documentation, but doesn't necessarily require doing anything to ddoc, and it's rarely the case that someone complains about ddoc itself. > To answer your question, regarding concrete examples, these > issues are in the context of wanting to translate the DLangSpec > pages into HTML5 so that I can compile them into an ePUB document: > > 1) the DLangSpec files (pick any one) use SECTION# macros, where > # is a number. In the DDoc conversion files to HTML, these > SECTION# macros convert to <h#> tags and encase the contents > within them. However, I'm not aware of any facility within DDoc, > short of hand-writing a parser, to allow these SECTION# macros to > be nested in order to take advantage of HTML5's <section> tags. Normally, you'd nest things by nesting macros. e.g. $(NESTED stuff $(NESTED more stuff $(NESTED yet more stuff) $(NESTED other stuff))) But I'm afrad that my understanding of html (and particularly html 5) is limited enough that you would have to give explict code samples for me to see what you can't convert. However, ddoc should allow you to do pretty much anything that involves simply transforming the content of a macro to somethnig else. The macro takes a set of arguments and then creates something new with them by rearranging them and adding stuff around them and the like. So, $(MACRO foo, bar, fiddly) can become <foo><fiddly>bar</fiddly></foo> or foo!bar.fiddly or whatever other combination of textual replacement and reording that you want to do. It's things that require counting what's there or generating something elsewhere in tho document base on macros (such as a table of contents or an index) which it can't do on its own (though it would be trivial to have another program read the ddoc and manipulate it to create sections for table of contents and the like if want to do that with a document that you're writing with ddoc). The exact set of macros used with the online documentation may very well be too specific to html 4, and it may be that the macros will have to be rewritten and moved around in the documentation, but the macro system itself will almost certainly do what you want. > 2) The macros are not self-documenting. For example, consider > $(LNAME2 pointers, Pointers) in arrays.dd. The easiest way, I > know, to figure out what $(LNAME2) means is to read the posix.mak > to see that arrays.dd gets pumped through ddoc.dd. Now, a search > through doc.ddoc to find the declaration LINK2=<a > href="$1">$+</a> at last tells me that argument 1 is the path to > the link and everything that follows that is the text to appear > in the link. The point is that, as I struggle through modifying > the existing .ddoc templates to compile to HTML5, I need to keep > flipping back and forth between the source and the .ddoc to make > sure that anything I'm redefining I'm doing correctly. The same goes for any function name. You frequently have to look them up to see exactly what they do. If they have better names, that helps, but how self- documenting a macro is is completely up to how well it was named. That has nothing to do with ddoc itself. > 3) Again using LINK2, if I were to delete the LINK2= line from > doc.ddoc and forget to readd it, my experience is that dmd -D > will quietly drop instances of $(LINK2) without telling me. Then perhaps dmd should be fixed so that it complains. That's a quality of implementation issue and probably easily fixed. > 4) Again using the same example, if LINK2 gets defined in > multiple DDoc files, how do I know for certain which definition > it calls when dmd runs against the files? Again. That's a QoI issue. We can probably make the compiler give a warning or error in that case. > 5) I find that a lot of the DLangSpec is written from an HTML > point of view, so maybe it just needs rewriting to make the > macros descriptive. For example, consider $(B dmd) and $(B -gc) > on lines 881-882 of abi.dd. By default, these get converted into > <b>dmd</b> and <b>-gc</b> Say I want commands (like dmd) to be > bolded but I want command-line arguments not to be bolded. > There's no way to write B= to single out some $(B)s and not > others. Now, I know the knee-jerk response is "Yes, but HTML > works the exact same way." That's true, but CSS *does* give you a > bunch of selectors to cherry-pick, say, "only the <b> tags of > class X" or "the element with this id." Meaning that all I have > to do is find the Bs I want to change and add a class="" without > having to worry about updating any of the other Bs. Is there a > simple way to do this in DDoc? Ddoc is pure macros. If you want different stuff to be treated differently, you need different macros. But css can be used just fine with the html generated by ddoc, so if css supports what you're looking for, then I would think that you'd be able to do it with css. Regardless, the exact set of macros used with dlang.org are definitely targeted at html, so it's quite possible that we'll need a different set of macros to get it to convert to other formats more easily (though it already translates to one ebook format as well as latex - though Andrei is working on improving the latex stuff). So, my guess is that this not a problem with ddoc but rather a problem with how ddoc is being used. - Jonathan M Davis
