View mode: basic / threaded / horizontal-split · Log in · Help
January 05, 2013
Re: dlangspec.pdf?
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.
January 05, 2013
Re: dlangspec.pdf?
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.
January 05, 2013
Re: dlangspec.pdf?
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 :)
January 05, 2013
Re: dlangspec.pdf?
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 :(
January 05, 2013
Re: dlangspec.pdf?
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}
January 05, 2013
Re: dlangspec.pdf?
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.
January 05, 2013
Re: dlangspec.pdf?
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.
January 05, 2013
Re: dlangspec.pdf?
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)
January 05, 2013
Re: dlangspec.pdf?
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.
January 05, 2013
Re: dlangspec.pdf?
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
1 2 3 4 5 6 7
Top | Discussion index | About this forum | D home