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). 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. 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. 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. 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? 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? These are just a few of the observations that I have. As I said in the other threads, my ePUB effort has ground to a halt because I find that I'm fighting to read the spec sources rather than figuring out how to produce clean and pretty HTML5 code that can get compiled into an ePUB.
