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.


> Note that markdown was crafted to be readable by itself, even though its final
> goal is to be rendered in HTML. Ddoc has no such compulsion (some macros are a
> bit obscure for me when I read documentation in raw form)
>
> 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. 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.

On 1/5/2013 11:30 AM, Andrei Alexandrescu wrote:
> I learned with time that ddoc's macro system is quite coherent and well designed.

I've often thought that that macro system should be put in Phobos as a module such that it could be used with any text file.

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

> On 1/5/2013 11:30 AM, Andrei Alexandrescu wrote:
>
>> I learned with time that ddoc's macro system is quite coherent and well designed.
>>
>
> I've often thought that that macro system should be put in Phobos as a module such that it could be used with any text file.
>
>
What should it be? Some module to define text transformations? std.regex does this quite well.

Of course, having std.parse and std.lex would be a godsend :)

On Sat, Jan 5, 2013 at 10:09 PM, Walter Bright <newshound2@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 :(

On Sat, Jan 5, 2013 at 8:30 PM, Andrei Alexandrescu < SeeWebsiteForEmail@erdani.org> wrote:

>
>>
>  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.
>>
>
> I learned with time that ddoc's macro system is quite coherent and well designed.
>
>
Here is my first try for a LaTeX-generating list of Ddoc macros. I'm sure a
LaTeX guru would find some of these quite dangerous :)
The final, global, appearance should be mostly defined in the DDOC macro.

I wonder how to have ddoc produce code highlighting that's compatible with LaTex.

- Curly braces are a bit special in LaTex, hence using \texttt{} does not
work well.
- But using \begin{verbatim} \end{verbatim} disable the coloring code
produced by Ddoc.

For my own docs, I use pygmentize... Else I suppose the listings could also work.

I gather some hypothesis (namely, that the end output will be HTML) are a
bit hardwired in Ddoc.

Anyway:

B=\textbf{$0}
I=\textit{$0}
U=\underline{$0}
P= $0

DL=\begin{description}
$0
\end{description}
DT=\item[$0]
DD=$0
TABLE=\begin{tabular}[2]{l|l}
$0
\end{tabular}
TR=$0 \\
TH=$0 &
TD=$0
OL=\begin{enumerate}
$0
\end{enumerate}
UL=\begin{itemize}
$0
\end{itemize}
LI=\item $0
BIG=\large{$0}
SMALL=\small{$0}
BR=\newline
LINK=\url{$0}
LINK2=\href{$1}{$+}
RED={\color{red}$0}
BLUE={\color{blue}$0}
GREEN={\color{green}$0}
YELLOW={\color{yellow}$0}
BLACK={\color{black}$0}
WHITE={\color{white}$0}
D_CODE=\begin{verbatim}
$0
\end{verbatim}
DDOC=\documentclass[11pt]{article}
\usepackage{color}

\usepackage{hyperref}
\begin{document}
\title{$(TITLE)}
\date{}
\maketitle

$(BODY)
\end{document}

On 1/5/2013 1:32 PM, Philippe Sigaud wrote:
> What should it be? Some module to define text transformations? std.regex does
> this quite well.


A text macro system is not std.regex at all. What std.textmacro should be is a range that takes a text input stream, an associative array of NAME=VALUE pairs, and it outputs a text range with the macros having been expanded.

On 1/5/2013 1:38 PM, Philippe Sigaud wrote:
>     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.

You are entering another land with it. Text processing is totally different, and it should be different.

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

They aren't really much different from the website macros. In fact, the D ebook is created out of the same source files the website is. The macros to do it are all in github.

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

All those source files are on github.

On Sat, Jan 5, 2013 at 11:17 PM, Walter Bright <newshound2@digitalmars.com>wrote:

> On 1/5/2013 1:32 PM, Philippe Sigaud wrote:
>
>> What should it be? Some module to define text transformations? std.regex
>> does
>> this quite well.
>>
>
>
> A text macro system is not std.regex at all. What std.textmacro should be is a range that takes a text input stream, an associative array of NAME=VALUE pairs, and it outputs a text range with the macros having been expanded.
>

OK, that's doable. It looks like a map-flatten action.
(map the first element, it might contain new macros, expand these again,
etc)

On Sat, Jan 5, 2013 at 11:20 PM, Walter Bright <newshound2@digitalmars.com>wrote:

> On 1/5/2013 1:38 PM, Philippe Sigaud wrote:
>
>>     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.
>>
>
> You are entering another land with it. Text processing is totally different, and it should be different.
>

I'm not convinced, but that's not really important.

>
> They aren't really much different from the website macros. In fact, the D ebook is created out of the same source files the website is. The macros to do it are all in github.


Also, Phobos/index.d is sadly in HTML, not in Ddoc.
>>
>
> All those source files are on github.
>

I must be tired, because the only .ddoc file I find is std.ddoc. No .d article on templates, etc: only the .html files.

On 2013-01-05 22:38, Philippe Sigaud wrote:

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

Just do what PHP, Ruby and other similar languages do:

<% /* arbitrary D code */ %>

some text

<% /* more D code */ %>

Ruby has got Erb (Embedded Ruby). It's most often used to embed Ruby, like above, in HTML but it's possible to to for any output format.

-- 
/Jacob Carlborg