dlangspec.pdf?

[Philippe Sigaud]

On Sat, Jan 5, 2013 at 10:09 PM, Walter Bright
<newshound2 at digitalmars.com>wrote:

> On 1/5/2013 7:14 AM, Philippe Sigaud wrote:
>
>> Since I just remade a 180-pages tutorial on D templates in markdown
>> without much
>> trouble, I guess documentation and tutorial are different beasts. I felt
>> no need
>> for macros, really, but I can see how they are useful for Ddoc pages.
>>
>
> Having macros in Ddoc have been a godsend for improving productivity. For
> example, some bits need to be added or removed for generating an ebook -
> macros handle that in an ideal fashion. They're great for adding
> boilerplate, when urls need to be mass changed, etc. It just goes on.
>

I see that. But see below.


>
>> You know, I always felt Ddoc was a strange sublanguage bolted onto D. An
>> elegant
>> solution would be to have macros be D code, but I have nothing to propose
>> here.
>>
>
> It is a strange sublanguage. It has its problems, but compared to what D
> documentation was like before Ddoc, it is a HUGE and incalculable leap
> forward.


I was just wondering if there was a way to make it a bit more D-ish. The
$(NAME arg, arg) syntax feels like I'm entering another land  when I have
to use it.



> The Phobos documentation, for example, before Ddoc was complete and utter
> garbage that rarely had any correspondence to what the code actually was
> and did.
>
> And, btw, I have published on Amazon a couple of non-tech ebooks. I used
> Ddoc for them, and there is no html feel to the result. They look like any
> other ebook.
>
> Do you have any macro to present? They could be used by other people, as
an example of Ddoc power.

Also, it would be nice to present the article from the website as .d files
with Ddoc macros. They are only accessible as HTML (that's the end goal,
yes, but having them as .d files would be good).
Also, Phobos/index.d is sadly in HTML, not in Ddoc.


Btw, I just played a bit with macros and defined a small bunch of
LaTex-producing macros. I'll post that.

It doesn't help that DMD inserts a HTML comment at the beginning:

<!-- Generated by Ddoc from filename.d -->

HTML hardwired into the final result, whatever the doc says :(
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20130105/0f21d1d5/attachment.html>