## digitalmars.D - dlangspec.pdf?

Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Now that the issue of documentation came up, I wonder if there's
interest in a high-quality PDF rendering of the language spec (e.g.
similar to the interior design of TDPL itself). Is it worth the effort?

Thanks,

Andrei

Jan 04 2013
=?ISO-8859-1?Q?Alex_R=F8nne_Petersen?= <alex lycus.org> writes:
On 05-01-2013 04:53, Andrei Alexandrescu wrote:
Now that the issue of documentation came up, I wonder if there's
interest in a high-quality PDF rendering of the language spec (e.g.
similar to the interior design of TDPL itself). Is it worth the effort?

Thanks,

Andrei

I would love to have that.

--
Alex Rønne Petersen
alex alexrp.com / alex lycus.org
http://lycus.org

Jan 04 2013
Jordi Sayol <g.sayol yahoo.es> writes:
Al 05/01/13 04:53, En/na Andrei Alexandrescu ha escrit:
Now that the issue of documentation came up, I wonder if there's interest in a
high-quality PDF rendering of the language spec (e.g. similar to the interior
design of TDPL itself). Is it worth the effort?

Thanks,

Andrei

+1000

--
Jordi Sayol

Jan 04 2013
"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Jan 04, 2013 at 10:53:13PM -0500, Andrei Alexandrescu wrote:
Now that the issue of documentation came up, I wonder if there's
interest in a high-quality PDF rendering of the language spec (e.g.
similar to the interior design of TDPL itself). Is it worth the
effort?

[...]

Is it ready for finalization, or are major changes (like UDA) still
going to take place? If major changes are still going to take place
(and, in the long run, I hope D will keep improving), then we should
have a version system for the spec, so that we don't end up in the
situation where somebody with a copy of the older spec thinks feature X
is one way, and the latest implementation according to a newer spec
implements it a different way, but there's no indication of which spec
is supposed to be the correct one.

T

--
Lawyer: (n.) An innocence-vending machine, the effectiveness of which depends
on how much money is inserted.

Jan 04 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/5/13 1:04 AM, H. S. Teoh wrote:
On Fri, Jan 04, 2013 at 10:53:13PM -0500, Andrei Alexandrescu wrote:
Now that the issue of documentation came up, I wonder if there's
interest in a high-quality PDF rendering of the language spec (e.g.
similar to the interior design of TDPL itself). Is it worth the
effort?

[...]

Is it ready for finalization, or are major changes (like UDA) still
going to take place? If major changes are still going to take place
(and, in the long run, I hope D will keep improving), then we should
have a version system for the spec, so that we don't end up in the
situation where somebody with a copy of the older spec thinks feature X
is one way, and the latest implementation according to a newer spec
implements it a different way, but there's no indication of which spec
is supposed to be the correct one.

The spec pdf would be just a rendering of the online dox, just like
.mobi is.

Andrei

Jan 04 2013
"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sat, Jan 05, 2013 at 01:20:36AM -0500, Andrei Alexandrescu wrote:
On 1/5/13 1:04 AM, H. S. Teoh wrote:
On Fri, Jan 04, 2013 at 10:53:13PM -0500, Andrei Alexandrescu wrote:
Now that the issue of documentation came up, I wonder if there's
interest in a high-quality PDF rendering of the language spec (e.g.
similar to the interior design of TDPL itself). Is it worth the
effort?

[...]

Is it ready for finalization, or are major changes (like UDA) still
going to take place? If major changes are still going to take place
(and, in the long run, I hope D will keep improving), then we should
have a version system for the spec, so that we don't end up in the
situation where somebody with a copy of the older spec thinks feature
X is one way, and the latest implementation according to a newer spec
implements it a different way, but there's no indication of which
spec is supposed to be the correct one.

The spec pdf would be just a rendering of the online dox, just like
.mobi is.

[...]

OK. Well, to answer your original question, yes I'm interested in a PDF
rendering. I do think we should attach a version to it, though. Or at
least a last-revised date.

T

--
Gone Chopin. Bach in a minuet.

Jan 04 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 5, 2013 at 7:20 AM, Andrei Alexandrescu <
SeeWebsiteForEmail erdani.org> wrote:

The spec pdf would be just a rendering of the online dox, just like .mobi
is.

I'd be interested.

It can also be done in markdown, which we all know now, with github being a
central D repository.
From markdown, it can easily be translated into pdf, html, mobi or epub

(heck, even docx)

Philippe

Jan 05 2013
=?UTF-8?B?QWxleCBSw7hubmUgUGV0ZXJzZW4=?= <alex lycus.org> writes:
On 05-01-2013 09:59, Philippe Sigaud wrote:
On Sat, Jan 5, 2013 at 7:20 AM, Andrei Alexandrescu
<SeeWebsiteForEmail erdani.org <mailto:SeeWebsiteForEmail erdani.org>>
wrote:

The spec pdf would be just a rendering of the online dox, just like
.mobi is.

I'd be interested.

It can also be done in markdown, which we all know now, with github
being a central D repository.
From markdown, it can easily be translated into pdf, html, mobi or epub
(heck, even docx)

Philippe

We just have way too much documentation already written in Ddoc.

But I agree - Markdown would be significantly nicer to write the spec
in... Ddoc has a too HTML-y feel to it for general writing.

--
Alex RÃ¸nne Petersen
alex alexrp.com / alex lycus.org
http://lycus.org

Jan 05 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/5/13 4:17 AM, Alex RÃ¸nne Petersen wrote:
But I agree - Markdown would be significantly nicer to write the spec
in... Ddoc has a too HTML-y feel to it for general writing.

But Markdown seems to have no macros.

Andrei

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 5, 2013 at 2:13 PM, Andrei Alexandrescu <
SeeWebsiteForEmail erdani.org> wrote:

On 1/5/13 4:17 AM, Alex R=C3=B8nne Petersen wrote:

But I agree - Markdown would be significantly nicer to write the spec
in... Ddoc has a too HTML-y feel to it for general writing.

But Markdown seems to have no macros.

Indeed it has none, good point.

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.

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.

Jan 05 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/5/13 10:14 AM, Philippe Sigaud wrote:
On Sat, Jan 5, 2013 at 2:13 PM, Andrei Alexandrescu
<SeeWebsiteForEmail erdani.org <mailto:SeeWebsiteForEmail erdani.org>>
wrote:

On 1/5/13 4:17 AM, Alex RÃ¸nne Petersen wrote:

But I agree - Markdown would be significantly nicer to write the
spec
in... Ddoc has a too HTML-y feel to it for general writing.

But Markdown seems to have no macros.

Indeed it has none, good point.

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.

Yah, those are different beasts as there's a lot of repetitive crap the
typical HTML site needs to carry. For example, the header, footer, and
left-hand side column needs to be copied in all HTML files. Books don't
need such, and to the extent they do (page styling, heading, and
footing) that's easy to take care of. Markdown probably has some simple
mechanism to e.g. set page numbers.

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)

Agreed.

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.

Andrei

Jan 05 2013
Walter Bright <newshound2 digitalmars.com> writes:
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.

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
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 :)

Jan 05 2013
Walter Bright <newshound2 digitalmars.com> writes:
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.

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
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)

Jan 05 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/5/13 5:17 PM, Walter Bright 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.

Example: http://www.stringtemplate.org/

Andrei

Jan 05 2013
Walter Bright <newshound2 digitalmars.com> writes:
On 1/5/2013 7:15 PM, Andrei Alexandrescu wrote:
On 1/5/13 5:17 PM, Walter Bright 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.

Example: http://www.stringtemplate.org/

I like the range method better.

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
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}

Jan 05 2013
Walter Bright <newshound2 digitalmars.com> writes:
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.

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
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 :(  Jan 05 2013 Walter Bright <newshound2 digitalmars.com> writes: 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.

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
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.  Jan 05 2013 Walter Bright <newshound2 digitalmars.com> writes: On 1/5/2013 2:50 PM, Philippe Sigaud wrote: I must be tired, because the only .ddoc file I find is std.ddoc. No .d article on templates, etc: only the .html files. https://github.com/D-Programming-Language/d-programming-language.org  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: On Sun, Jan 6, 2013 at 1:40 AM, Walter Bright <newshound2 digitalmars.com>wrote: On 1/5/2013 2:50 PM, Philippe Sigaud wrote: I must be tired, because the only .ddoc file I find is std.ddoc. No .d article on templates, etc: only the .html files. https://github.com/D-**Programming-Language/d-**programming-language.org<https://github.com/D-Programming-Language/d-programming-language.org> Oh, .dd files! I did not search for those, I didn't even know they existed. Thanks, now I can look how you did some linking and layout.  Jan 05 2013 Jacob Carlborg <doob me.com> writes: 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

Jan 05 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/5/13 4:38 PM, Philippe Sigaud wrote:
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 :(

Yah, I also played with producing LaTeX and hit the same problem. Had to
sed away the first line. Walter, could you please fix that - thanks.

Philippe, please share with me as soon as you have anything significant
done in terms of LaTeX production so we don't overlap work.

Thanks,

Andrei

Jan 05 2013
Walter Bright <newshound2 digitalmars.com> writes:
On 1/5/2013 3:44 PM, Andrei Alexandrescu wrote:
On 1/5/13 4:38 PM, Philippe Sigaud wrote:
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 :(

Yah, I also played with producing LaTeX and hit the same problem. Had to sed
away the first line. Walter, could you please fix that - thanks.

C:>grep DDOC_COMMENT *.c
doc.c:DDOC_COMMENT   = <!-- $0 -->\n\ doc.c: buf.printf("$(DDOC_COMMENT Generated by Ddoc from %s)\n",
srcfile->toChars());

I.e. override the DDOC_COMMENT macro.

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
 Philippe, please share with me as soon as you have anything significant
done in terms of LaTeX production so we don't overlap work.

Nothing significant yet, that's my first dib into macro.
I use these, but have a problem for code highlighting: DMD inserts macros
to colour the code, these don't play well with my usual solutions (package
pygmentize or package listings). The same for \verbatim{} instruction.
Here, I just used a simple \texttt{} instruction, but in this case curly
braces are lost :(

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=\texttt{$0}
DDOC_PSYMBOL = $(U$0)
DDOC_ANCHOR = \label{$1} DDOC_DECL =$(DT $0) XREF =$(REF std_$1.html#$2, $(D std.$1.$2)) CXREF =$(REF core_$1.html#$2, $(D core.$1.$2)) LREF = \hyperref[$1]{$1} DDOC=\documentclass[11pt]{article} \usepackage{color} \usepackage{hyperref} \begin{document} \title{$(TITLE)}
\date{}
\maketitle

$(BODY) \end{document}  Jan 06 2013 "H. S. Teoh" <hsteoh quickfur.ath.cx> writes: On Sun, Jan 06, 2013 at 10:44:27AM +0100, Philippe Sigaud wrote: Philippe, please share with me as soon as you have anything significant done in terms of LaTeX production so we don't overlap work. Nothing significant yet, that's my first dib into macro. I use these, but have a problem for code highlighting: DMD inserts macros to colour the code, these don't play well with my usual solutions (package pygmentize or package listings). The same for \verbatim{} instruction. Here, I just used a simple \texttt{} instruction, but in this case curly braces are lost :( LaTeX has its own syntactic conventions. Curly braces must be escaped with backslash, and certain operators (^ in particular, which also affects ^^) will cause syntax errors, because they are metacharacters with a different meaning. All of them need to be properly escaped. You may be able to use \begin{verbatim} and \end{verbatim} (which doesn't suffer from the trailing brace problem) but you can't use it for inline spans of text. Unless, of course, you drop into low-level TeX hacking to redefine metacharacters so that characters used in D code never collide with them. (It's possible, but not recommended because nobody will be able to read the code and understand what it does! Plus, you'll have to restore LaTeX's original definitions every time you end a block of code so that LaTeX macros will still work -- otherwise you'll get very colorful malfunctions.) T -- Talk is cheap. Whining is actually free. -- Lars Wirzenius  Jan 06 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: On Sun, Jan 6, 2013 at 4:19 PM, H. S. Teoh <hsteoh quickfur.ath.cx> wrote: On Sun, Jan 06, 2013 at 10:44:27AM +0100, Philippe Sigaud wrote: Philippe, please share with me as soon as you have anything significant done in terms of LaTeX production so we don't overlap work. Nothing significant yet, that's my first dib into macro. I use these, but have a problem for code highlighting: DMD inserts macros to colour the code, these don't play well with my usual solutions (package pygmentize or package listings). The same for \verbatim{} instruction. Here, I just used a simple \texttt{} instruction, but in this case curly braces are lost :( LaTeX has its own syntactic conventions. Curly braces must be escaped with backslash, and certain operators (^ in particular, which also affects ^^) will cause syntax errors, because they are metacharacters with a different meaning. All of them need to be properly escaped. Exactly. You may be able to use \begin{verbatim} and \end{verbatim} (which doesn't suffer from the trailing brace problem) but you can't use it for inline spans of text. Damn right. I'll try with the listings package, but I don't have much hope to achieve what I want.  Jan 06 2013 Walter Bright <newshound2 digitalmars.com> writes: On 1/6/2013 9:31 AM, Philippe Sigaud wrote: Exactly. At one point I looked into doing Latex macros for Ddoc, but unfortunately it didn't look like it was doable without some extensive modifications to Ddoc.  Jan 06 2013 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/7/13 2:17 AM, Walter Bright wrote: On 1/6/2013 9:31 AM, Philippe Sigaud wrote: Exactly. At one point I looked into doing Latex macros for Ddoc, but unfortunately it didn't look like it was doable without some extensive modifications to Ddoc. ??? I already have something in progress. Andrei  Jan 06 2013 Walter Bright <newshound2 digitalmars.com> writes: On 1/6/2013 11:35 PM, Andrei Alexandrescu wrote: On 1/7/13 2:17 AM, Walter Bright wrote: On 1/6/2013 9:31 AM, Philippe Sigaud wrote: Exactly. At one point I looked into doing Latex macros for Ddoc, but unfortunately it didn't look like it was doable without some extensive modifications to Ddoc. ??? I already have something in progress. Cool! You know Latex far better than I.  Jan 06 2013 "H. S. Teoh" <hsteoh quickfur.ath.cx> writes: On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote: On 1/7/13 2:17 AM, Walter Bright wrote: On 1/6/2013 9:31 AM, Philippe Sigaud wrote: Exactly. At one point I looked into doing Latex macros for Ddoc, but unfortunately it didn't look like it was doable without some extensive modifications to Ddoc. I think the simplest way would be to allow the definition of some kind of post-processing filter that escapes LaTeX metacharacters with their appropriate substitutions. It can be as easy as a ddoc macro (or list of macros) that translates a given character into its LaTeX equivalent, with the default of no-op. So to adapt ddoc output to a particular format, you just have to override that particular set of metacharacters, and leave everything else as pass-through. ??? I already have something in progress. [...] Curious ears want to hear what that something is. :-) T -- Arise, you prisoners of Windows / Arise, you slaves of Redmond, Wash, / The day and hour soon are coming / When all the IT folks say "Gosh!" / It isn't from a clever lawsuit / That Windowsland will finally fall, / But thousands writing open source code / Like mice who nibble through a wall. -- The Linux-nationale by Greg Baker  Jan 07 2013 "Adam D. Ruppe" <destructionator gmail.com> writes: On Monday, 7 January 2013 at 17:32:33 UTC, H. S. Teoh wrote: I think the simplest way would be to allow the definition of some kind of post-processing filter that escapes LaTeX metacharacters with their appropriate substitutions. Believe it or not, but dmd already has the beginnings of this code! There's a ddoc escapes table. from doc.c: ESCAPES = /</&lt;/\n />/&gt;/\n /&/&amp;/\n And there's code to parse it, but it isn't actually used. I did a dmd pull request a while ago to bring in this functionality but it didn't pass reviews. (A consequence of proper escaping would be that inline HTML, outside of macros, would no longer be permitted, because <b> etc would be properly escaped instead of printed out verbatim. This is far, far, far superior to the status quo, but it does break a lot of phobos documentation.)  Jan 07 2013 "H. S. Teoh" <hsteoh quickfur.ath.cx> writes: On Mon, Jan 07, 2013 at 06:40:36PM +0100, Adam D. Ruppe wrote: On Monday, 7 January 2013 at 17:32:33 UTC, H. S. Teoh wrote: I think the simplest way would be to allow the definition of some kind of post-processing filter that escapes LaTeX metacharacters with their appropriate substitutions. Believe it or not, but dmd already has the beginnings of this code! There's a ddoc escapes table. from doc.c: ESCAPES = /</&lt;/\n />/&gt;/\n /&/&amp;/\n This is exactly what's needed to produce proper LaTeX output. And there's code to parse it, but it isn't actually used. I did a dmd pull request a while ago to bring in this functionality but it didn't pass reviews. (A consequence of proper escaping would be that inline HTML, outside of macros, would no longer be permitted, because <b> etc would be properly escaped instead of printed out verbatim. This is far, far, far superior to the status quo, but it does break a lot of phobos documentation.) Inline HTML should not be allowed in ddoc, because it completely defeats the purpose of the ddoc macro system allowing the same documentation to be rendered for multiple target formats. We need to go through all instances of such errors in Phobos and fix 'em all. T -- Don't get stuck in a closet---wear yourself out.  Jan 07 2013 "Era Scarecrow" <rtcvb32 yahoo.com> writes: On Monday, 7 January 2013 at 18:07:51 UTC, H. S. Teoh wrote: Inline HTML should not be allowed in ddoc, because it completely defeats the purpose of the ddoc macro system allowing the same documentation to be rendered for multiple target formats. We need to go through all instances of such errors in Phobos and fix 'em all. Depends on what HTML was used (and can extend to BBCode as well). If I were to add anything, it most likely would be bold/italic/underline & bullets. Those should be acceptable and overall easy to convert (or I would think so anyways).  Jan 07 2013 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/7/13 9:30 AM, H. S. Teoh wrote: On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote: ??? I already have something in progress. [...] Curious ears want to hear what that something is. :-) A set of ddoc macros that convert to LaTeX starting from Philippe's macros. The one systemic issue I encountered so far is tables, which in LaTeX must set the number of columns in advance. Andrei  Jan 07 2013 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/7/13 10:23 AM, Andrei Alexandrescu wrote: On 1/7/13 9:30 AM, H. S. Teoh wrote: On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote: ??? I already have something in progress. [...] Curious ears want to hear what that something is. :-) A set of ddoc macros that convert to LaTeX starting from Philippe's macros. The one systemic issue I encountered so far is tables, which in LaTeX must set the number of columns in advance. Andrei Heh, here's the first thing that I actually got to compile error-free from spec.dd and lex.dd: http://erdani.com/d/dlangspec.pdf. Had to fudge a few macros and some stuff doesn't expand to what it should, but from here the path is relatively easy. Andrei  Jan 07 2013 Jordi Sayol <g.sayol yahoo.es> writes: Al 07/01/13 20:19, En/na Andrei Alexandrescu ha escrit: On 1/7/13 10:23 AM, Andrei Alexandrescu wrote: On 1/7/13 9:30 AM, H. S. Teoh wrote: On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote: ??? I already have something in progress. [...] Curious ears want to hear what that something is. :-) A set of ddoc macros that convert to LaTeX starting from Philippe's macros. The one systemic issue I encountered so far is tables, which in LaTeX must set the number of columns in advance. Andrei Heh, here's the first thing that I actually got to compile error-free from spec.dd and lex.dd: http://erdani.com/d/dlangspec.pdf. Had to fudge a few macros and some stuff doesn't expand to what it should, but from here the path is relatively easy. Andrei "htmldoc" converts html files into pdf, generating a toc. In this sample I've removed original toc and "htmldoc" generated a toc with 2 levels. http://d-packages.googlecode.com/files/dlangspec.pdf Unfortunately "htmldoc" do not support css. -- Jordi Sayol  Jan 07 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes:  Heh, here's the first thing that I actually got to compile error-free from spec.dd and lex.dd: http://erdani.com/d/dlangspec.**pdf<http://erdani.com/d/dlangspec.pdf>. Had to fudge a few macros and some stuff doesn't expand to what it should, but from here the path is relatively easy. I tried to find all the macros that created those ugly <a = href... thingies before posting, but it looks like there are still some wandering around :)  Jan 07 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes:  "htmldoc" converts html files into pdf, generating a toc. In this sample I've removed original toc and "htmldoc" generated a toc with 2 levels. http://d-packages.googlecode.com/files/dlangspec.pdf Nice looking doc. Having 'dmd -D latex.ddoc spec.dd' generate that will be our first goal :) (the second one would to get it as nice as TDPL)  Jan 07 2013 Jordi Sayol <g.sayol yahoo.es> writes: Al 07/01/13 20:19, En/na Andrei Alexandrescu ha escrit: On 1/7/13 10:23 AM, Andrei Alexandrescu wrote: On 1/7/13 9:30 AM, H. S. Teoh wrote: On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote: ??? I already have something in progress. [...] Curious ears want to hear what that something is. :-) A set of ddoc macros that convert to LaTeX starting from Philippe's macros. The one systemic issue I encountered so far is tables, which in LaTeX must set the number of columns in advance. Andrei Heh, here's the first thing that I actually got to compile error-free from spec.dd and lex.dd: http://erdani.com/d/dlangspec.pdf. Had to fudge a few macros and some stuff doesn't expand to what it should, but from here the path is relatively easy. Andrei wkhtmltopdf v0.11.0 (static) https://code.google.com/p/wkhtmltopdf/ Converts html files into pdf, generating a toc index, and accepts css! An example built in Linux 64-bit: http://d-packages.googlecode.com/files/dlangspec-2.pdf -- Jordi Sayol  Jan 07 2013 "Era Scarecrow" <rtcvb32 yahoo.com> writes: On Tuesday, 8 January 2013 at 03:45:36 UTC, Jordi Sayol wrote: wkhtmltopdf v0.11.0 (static) https://code.google.com/p/wkhtmltopdf/ Converts html files into pdf, generating a toc index, and accepts css! An example built in Linux 64-bit: http://d-packages.googlecode.com/files/dlangspec-2.pdf Glanced it over and it looks nice. :)  Jan 07 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: On Tue, Jan 8, 2013 at 5:02 AM, Era Scarecrow <rtcvb32 yahoo.com> wrote: On Tuesday, 8 January 2013 at 03:45:36 UTC, Jordi Sayol wrote: wkhtmltopdf v0.11.0 (static) https://code.google.com/p/**wkhtmltopdf/<https://code.google.com/p/wkhtmltopdf/> Converts html files into pdf, generating a toc index, and accepts css! An example built in Linux 64-bit: http://d-packages.googlecode.**com/files/dlangspec-2.pdf<http://d-packages.googlecode.com/files/dlangspec-2.pdf> Glanced it over and it looks nice. :) It indeed looks very nice. If the entire content is here, it should be made downloadable, as the .mobi version.  Jan 07 2013 Jordi Sayol <g.sayol yahoo.es> writes: Al 07/01/13 20:19, En/na Andrei Alexandrescu ha escrit: On 1/7/13 10:23 AM, Andrei Alexandrescu wrote: On 1/7/13 9:30 AM, H. S. Teoh wrote: On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote: ??? I already have something in progress. [...] Curious ears want to hear what that something is. :-) A set of ddoc macros that convert to LaTeX starting from Philippe's macros. The one systemic issue I encountered so far is tables, which in LaTeX must set the number of columns in advance. Andrei Heh, here's the first thing that I actually got to compile error-free from spec.dd and lex.dd: http://erdani.com/d/dlangspec.pdf. Had to fudge a few macros and some stuff doesn't expand to what it should, but from here the path is relatively easy. Andrei "dlangspec" in Electronic Publication (epub) e-book file format, generated with "calibre".$ ebook-convert dlangspec.html .epub \
--authors "dlang.org" \
--comments "The specification of the D programming language" \
--language en \
--level1-toc "//h:h1" \
--level2-toc "//*[name()='h2' or name()='h3']" \
--level3-toc "//h:h4" \
--page-breaks-before / \
--cover dlangspec.png

EPUB example built on Linux 64-bit with calibre v0.3.38:

--
Jordi Sayol

Jan 08 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Mon, Jan 7, 2013 at 7:23 PM, Andrei Alexandrescu <
SeeWebsiteForEmail erdani.org> wrote:

On 1/7/13 9:30 AM, H. S. Teoh wrote:

On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote:

??? I already have something in progress.

[...]

Curious ears want to hear what that something is. :-)

A set of ddoc macros that convert to LaTeX starting from Philippe's
macros. The one systemic issue I encountered so far is tables, which in
LaTeX must set the number of columns in advance.

Same here. The two systems do not see tables in the same way.

Did you find a way to get syntax-highlighted code?

Jan 07 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/7/13 2:36 PM, Philippe Sigaud wrote:
Did you find a way to get syntax-highlighted code?

Listings package.

Andrei

Jan 07 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 5, 2013 at 10:17 AM, Alex R=C3=B8nne Petersen <alex lycus.org> =
wrote:

We just have way too much documentation already written in Ddoc.

But I agree - Markdown would be significantly nicer to write the spec
in... Ddoc has a too HTML-y feel to it for general writing.

Don't tempt me. I'm playing with the idea of writing a Ddoc <-> Markdown
converter. Something like Pandoc, but lighter.
The format and the perimeter needed are relatively limited: Ddoc, md, (a
subset of) html, maybe a subset of LaTeX.

Jan 05 2013
"Nicolas Sicard" <dransic gmail.com> writes:
On Saturday, 5 January 2013 at 14:10:38 UTC, Philippe Sigaud
wrote:
Don't tempt me. I'm playing with the idea of writing a Ddoc <->
Markdown
converter. Something like Pandoc, but lighter.

Couldn't a .ddoc file with redefined macros produce Markdown
output?

Jan 05 2013
On Saturday, 5 January 2013 at 17:13:07 UTC, Nicolas Sicard wrote:
On Saturday, 5 January 2013 at 14:10:38 UTC, Philippe Sigaud
wrote:
Don't tempt me. I'm playing with the idea of writing a Ddoc
<-> Markdown
converter. Something like Pandoc, but lighter.

Couldn't a .ddoc file with redefined macros produce Markdown
output?

This seems a bit backwards â€“ the point of Markdown is precisely
to be easy to read and write in *source* form, so using it as an
intermediate format doesn't make much sense, at least to me.

David

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 5, 2013 at 7:12 PM, David Nadlinger <see klickverbot.at> wrote:

On Saturday, 5 January 2013 at 17:13:07 UTC, Nicolas Sicard wrote:

On Saturday, 5 January 2013 at 14:10:38 UTC, Philippe Sigaud wrote:

Don't tempt me. I'm playing with the idea of writing a Ddoc <-> Markdow=

n
converter. Something like Pandoc, but lighter.

Couldn't a .ddoc file with redefined macros produce Markdown output?

In theory, yes.

This seems a bit backwards =E2=80=93 the point of Markdown is precisely to=
be easy
to read and write in *source* form, so using it as an intermediate format
doesn't make much sense, at least to me.

I concur.

Jan 05 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/5/13 12:13 PM, Nicolas Sicard wrote:
On Saturday, 5 January 2013 at 14:10:38 UTC, Philippe Sigaud wrote:
Don't tempt me. I'm playing with the idea of writing a Ddoc <-> Markdown
converter. Something like Pandoc, but lighter.

Couldn't a .ddoc file with redefined macros produce Markdown output?

Yes, that would be the better route. But then if we want to generate
good quality PDF, we better generate LaTeX.

Andrei

Jan 05 2013
"Nicolas Sicard" <dransic gmail.com> writes:
On Saturday, 5 January 2013 at 08:59:32 UTC, Philippe Sigaud
wrote:
From markdown, it can easily be translated into pdf, html, mobi
or epub

(heck, even docx)

Philippe

I was wondering: do you use Pandoc to do that (e.g. for your
D-template tutorial)?

Nicolas

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 5, 2013 at 10:33 AM, Nicolas Sicard <dransic gmail.com> wrote:

On Saturday, 5 January 2013 at 08:59:32 UTC, Philippe Sigaud wrote:

From markdown, it can easily be translated into pdf, html, mobi or epub

(heck, even docx)

Philippe

I was wondering: do you use Pandoc to do that (e.g. for your D-template
tutorial)?

Yes. Nice piece of Haskell software. I discovered it a few weeks ago and
spent the holidays converting 200 pages of text :)

The only thing I miss with Markdown is the ability to link to internal
reference in the text: titles are anchors with Pandoc, but I don't know how
to get an equivalent of LaTeX \label => \ref.

Jan 05 2013
"alex" <info alexanderbothe.com> writes:
On Saturday, 5 January 2013 at 14:08:00 UTC, Philippe Sigaud
wrote:
to get an equivalent of LaTeX \label => \ref.

Regarding LaTex..why not LaTex? I mean, pdf and all other
container derivatives aren't a problem then (anymore)

Jan 05 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Sat, Jan 5, 2013 at 3:42 PM, alex <info alexanderbothe.com> wrote:

On Saturday, 5 January 2013 at 14:08:00 UTC, Philippe Sigaud wrote:

to get an equivalent of LaTeX \label => \ref.

Regarding LaTex..why not LaTex? I mean, pdf and all other container
derivatives aren't a problem then (anymore)

LaTeX could be a possible target, at least as an intermediate stage for
pdf.

But it's monstrously difficult to parse it in full, so only the concerned
subset would be available as input: header markup, emphasis, the usual
stuff. That makes for 90% of tex files out there, but general LaTeX
commands are quite another beast.
Of course, since we are talking about documentation, the need for markup is
quite restricted.

Jan 05 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/4/13 7:53 PM, Andrei Alexandrescu wrote:
Now that the issue of documentation came up, I wonder if there's
interest in a high-quality PDF rendering of the language spec (e.g.
similar to the interior design of TDPL itself). Is it worth the effort?

Thanks,

Andrei

I just pushed the first passable PDF documentation generated via LaTeX
with ddoc: http://goo.gl/QIP4t. For now I'm only rendering the TOC and
lex.dd, but at this time we have enough seed for anyone interested to
convert other files.

Take a look at the generated PDF: http://erdani.com/d/dlangspec.pdf

Andrei

Jan 08 2013
Walter Bright <newshound2 digitalmars.com> writes:
On 1/8/2013 2:51 PM, Andrei Alexandrescu wrote:
I just pushed the first passable PDF documentation generated via LaTeX with
ddoc: http://goo.gl/QIP4t. For now I'm only rendering the TOC and lex.dd, but
at
this time we have enough seed for anyone interested to convert other files.

Take a look at the generated PDF: http://erdani.com/d/dlangspec.pdf

Andrei

Looks good to me.

It's also good to keep in mind that when I prepared the kindle version, which
has a small screen, I had to rather ruthlessly pare down the length of
preformatted lines like the code examples.

Jan 08 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Wed, Jan 9, 2013 at 12:12 AM, Walter Bright
<newshound2 digitalmars.com> wrote:
Take a look at the generated PDF: http://erdani.com/d/dlangspec.pdf

Looks good to me.

Yes, that has indeed quite a palatable appearance. I see you defined 2
or 3-cols tables, that's a good idea. Too bad DDoc macros do not
accept numerical arguments :) I guess in the end a 4-cols version will
be necessary, if only for the big tables in std.algorithm.

I also like your use of the listings package. How did you 'disable'
the automatic colouring DMD insert in code samples?

It's also good to keep in mind that when I prepared the kindle version,
which has a small screen, I had to rather ruthlessly pare down the length of
preformatted lines like the code examples.

Same here. I have a big tutorial on templates on github. Following
your advice, Walter, I found ways to convert it into .epub or .mobi (I
converted it from LaTex to Markdown). And, indeed, even 60-chars lines
tend to be too long for these screens. That's a pretty harsh limit! I
still have to scan the entire doc to find the longest lines.

Maybe I can start converting it to a big Ddoc file...

Jan 08 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/8/13 3:31 PM, Philippe Sigaud wrote:
On Wed, Jan 9, 2013 at 12:12 AM, Walter Bright
<newshound2 digitalmars.com>  wrote:
Take a look at the generated PDF: http://erdani.com/d/dlangspec.pdf

Looks good to me.

Yes, that has indeed quite a palatable appearance. I see you defined 2
or 3-cols tables, that's a good idea. Too bad DDoc macros do not
accept numerical arguments :) I guess in the end a 4-cols version will
be necessary, if only for the big tables in std.algorithm.

Yah, though note that these macros were only necessary because I was
doing unusual stuff subheadings for TABLE_3ROWS and multiline paragraph
for TABLE_2ROWS. If special stuff is not required you can use TABLE2 for
up to 10 columns.

I also like your use of the listings package. How did you 'disable'
the automatic colouring DMD insert in code samples?

I defined these guys:

D_COMMENT=$0 D_STRING=$0
D_KEYWORD=$0 It's also good to keep in mind that when I prepared the kindle version, which has a small screen, I had to rather ruthlessly pare down the length of preformatted lines like the code examples. Same here. I have a big tutorial on templates on github. Following your advice, Walter, I found ways to convert it into .epub or .mobi (I converted it from LaTex to Markdown). And, indeed, even 60-chars lines tend to be too long for these screens. That's a pretty harsh limit! I still have to scan the entire doc to find the longest lines. Maybe I can start converting it to a big Ddoc file... I reached a sort of weird conclusion that ddoc is a redoubtable documentation source format. (I'm not sure whether it's better than Markdown or not as I'm not very fluent with Markdown.) One great thing about ddoc is that macros are infinitely flexible, and the expansion rules are not as weird as other macro systems such as M4. The table use case is telling - as soon as I needed a special table form I could just encode that as a macro. I think with Markdown you get to generate one kind of table but if you want to fine-tune any particular table you just can't. Andrei  Jan 08 2013 Walter Bright <newshound2 digitalmars.com> writes: On 1/8/2013 3:57 PM, Andrei Alexandrescu wrote: One great thing about ddoc is that macros are infinitely flexible, and the expansion rules are not as weird as other macro systems such as M4. I had one great advantage in it being the fifth text macro processor I'd designed :-) I'd still like to see it done as a phobos module. Maybe an enhancement request?  Jan 08 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: On Wed, Jan 9, 2013 at 2:05 AM, Walter Bright <newshound2 digitalmars.com> wrote: I'd still like to see it done as a phobos module. Maybe an enhancement request? So, this should: - take a .ddoc file for macro definition, or a [name, code] range of pairs. - read an input range - this range can be a standard D file, a .dd or whatever. That means parsing D comments... - find any macro definition - find any$(NAME Args,) call, expand it recursively. Repeat until
nothing changes anymore. This should be done lazily (through the input
range interface), in case the user want to stop before the end.
- output the result as a range.

What I'm not clear about, is: if the input is a D source file, should
the expander strip any D code from it? Should this return a
full-fledged documentation (ie, find the documented symbols...) or
just blindly expand DDoc macros.

Jan 09 2013
Walter Bright <newshound2 digitalmars.com> writes:
On 1/9/2013 2:40 AM, Philippe Sigaud wrote:
On Wed, Jan 9, 2013 at 2:05 AM, Walter Bright
<newshound2 digitalmars.com> wrote:

I'd still like to see it done as a phobos module. Maybe an enhancement
request?

So, this should:

- take a .ddoc file for macro definition, or a [name, code] range of pairs.
- this range can be a standard D file, a .dd or whatever. That
- find any macro definition
- find any $(NAME Args,) call, expand it recursively. Repeat until nothing changes anymore. This should be done lazily (through the input range interface), in case the user want to stop before the end. - output the result as a range. What I'm not clear about, is: if the input is a D source file, should the expander strip any D code from it? Should this return a full-fledged documentation (ie, find the documented symbols...) or just blindly expand DDoc macros. No no no. The module gets its input from an InputRange. Not a file. It gets its macro definitions, which are NAME=VALUE pairs, from an associative array of them.  Jan 09 2013 "H. S. Teoh" <hsteoh quickfur.ath.cx> writes: On Wed, Jan 09, 2013 at 11:01:32AM -0800, Walter Bright wrote: On 1/9/2013 2:40 AM, Philippe Sigaud wrote: On Wed, Jan 9, 2013 at 2:05 AM, Walter Bright <newshound2 digitalmars.com> wrote: I'd still like to see it done as a phobos module. Maybe an enhancement request? So, this should: - take a .ddoc file for macro definition, or a [name, code] range of pairs. - read an input range - this range can be a standard D file, a .dd or whatever. That means parsing D comments... - find any macro definition - find any$(NAME Args,) call, expand it recursively. Repeat until
nothing changes anymore. This should be done lazily (through the
input range interface), in case the user want to stop before the
end.
- output the result as a range.

What I'm not clear about, is: if the input is a D source file, should
the expander strip any D code from it? Should this return a
full-fledged documentation (ie, find the documented symbols...) or
just blindly expand DDoc macros.

No no no. The module gets its input from an InputRange. Not a file.
It gets its macro definitions, which are NAME=VALUE pairs, from an
associative array of them.

I agree, the interface should be as generic as possible. I think it
would be nice to have a separate function for parsing macro definitions.
So the API should look something like this:

Result expandDdocMacros(I,Result)(I inputRange,
string[string] macroDefs)
if (isInputRange!I && isSomeChar!(ElementType!I))
{ ... }

string[string] parseMacroDefs(I)(I inputRange)
if (isInputRange!I && isSomeChar!(ElementType!I))
{ ... }

Then you can use it something like this:

void main() {
auto macrodefs = File(macroFile);
auto inputfile = File(ddocFile);

auto expanded = expandDdocMacros(inputfile.byChar(),
macrodefs.byChar());
static assert(isInputRange!(typeof(expanded)));

stdout.write(expanded);
}

You can also feed it all sorts of stuff, like network input:

string[string] builtinMacros = ...;

// Online Ddoc expander!
void myCgiApp(HttpRequest req, ref HttpResponse resp) {
static assert(isInputRange!(typeof(req.data)) &&
isSomeChar!(ElementType!(typeof(req.data))));

auto result = expandDdocMacros(req.data, builtinMacros);
resp.put(result);
}

Etc., etc.. D ranges are an extremely powerful concept.

T

--
Ð‘ÐµÐ· Ñ‚Ñ€ÑƒÐ´Ð° Ð½Ðµ Ð²Ñ‹Ð»Ð¾Ð²Ð¸ÑˆÑŒ Ð¸ Ñ€Ñ‹Ð±ÐºÑƒ Ð¸Ð· Ð¿Ñ€ÑƒÐ´Ð°.

Jan 09 2013
Walter Bright <newshound2 digitalmars.com> writes:
On 1/9/2013 11:31 AM, H. S. Teoh wrote:
I think it
would be nice to have a separate function for parsing macro definitions.

No. Where the macro definitions come from is a completely separate problem, and
the two should not be conflated.

Jan 09 2013
"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Wed, Jan 09, 2013 at 12:12:02PM -0800, Walter Bright wrote:
On 1/9/2013 11:31 AM, H. S. Teoh wrote:
I think it would be nice to have a separate function for parsing
macro definitions.

No. Where the macro definitions come from is a completely separate
problem, and the two should not be conflated.

I disagree. The macro definitions does not need to (and probably should
not) be in the same place as the input file, but they do have to be
defined somewhere.  Yes you can just construct your own string[string]
and hand that over to the macro expander, but it would be nice to also
have a uniform syntax for defining macros in an external source, which
can be parsed by a standard library function.

It would be kinda disappointing to have a marvellous system for macro
expansion, yet no standard way to define said macros, but everyone cooks
their own syntax and parser for it.

T

--
Why have vacation when you can work?? -- EC

Jan 09 2013
Walter Bright <newshound2 digitalmars.com> writes:
On 1/9/2013 12:34 PM, H. S. Teoh wrote:
It would be kinda disappointing to have a marvellous system for macro
expansion, yet no standard way to define said macros, but everyone cooks
their own syntax and parser for it.

I've developed multiple macro systems. There is no standard way of getting the
macro defs, nor should there be.

Jan 09 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
On Wed, Jan 9, 2013 at 8:01 PM, Walter Bright
<newshound2 digitalmars.com> wrote:

What I'm not clear about, is: if the input is a D source file, should
the expander strip any D code from it? Should this return a
full-fledged documentation (ie, find the documented symbols...) or
just blindly expand DDoc macros.

No no no. The module gets its input from an InputRange. Not a file. It gets
its macro definitions, which are NAME=VALUE pairs, from an associative array
of them.

That's not what I'm talking about, sorry for not being clear. I don't
care for the origin of the data, obviously. I meant a D module, not a
file specifically. My question was if the data is a D module (code +
comments), should it just expand macros? Or should it generate a
documentation?

From this and your other comments, I suppose the module does not

filter out comments specifically: it simply iterate until it finds a
$( pattern.  Jan 09 2013 Walter Bright <newshound2 digitalmars.com> writes: On 1/9/2013 12:03 PM, Philippe Sigaud wrote: That's not what I'm talking about, sorry for not being clear. I don't care for the origin of the data, obviously. I meant a D module, not a file specifically. My question was if the data is a D module (code + comments), should it just expand macros? Or should it generate a documentation? The current ddoc macro system does recognize D code. This should be removed from a generic macro system.  Jan 09 2013 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes: On 1/9/13 12:13 PM, Walter Bright wrote: On 1/9/2013 12:03 PM, Philippe Sigaud wrote: That's not what I'm talking about, sorry for not being clear. I don't care for the origin of the data, obviously. I meant a D module, not a file specifically. My question was if the data is a D module (code + comments), should it just expand macros? Or should it generate a documentation? The current ddoc macro system does recognize D code. This should be removed from a generic macro system. Yah, the "----" etc. I was thinking it would be nice to have some of that functionality, too. Andrei  Jan 09 2013 "H. S. Teoh" <hsteoh quickfur.ath.cx> writes: On Wed, Jan 09, 2013 at 12:16:56PM -0800, Andrei Alexandrescu wrote: On 1/9/13 12:13 PM, Walter Bright wrote: On 1/9/2013 12:03 PM, Philippe Sigaud wrote: That's not what I'm talking about, sorry for not being clear. I don't care for the origin of the data, obviously. I meant a D module, not a file specifically. My question was if the data is a D module (code + comments), should it just expand macros? Or should it generate a documentation? The current ddoc macro system does recognize D code. This should be removed from a generic macro system. Yah, the "----" etc. I was thinking it would be nice to have some of that functionality, too. [...] I think the D-specific parts (or even documentation-specific parts, like the syntax for sections) should be done separately. Maybe something like this: // In the generic macro module R expandMacros(I,R)(I inputRange, string[string] macroDefs) { ...} // In a doc-specific module R extractDocComments(I,R)(I inputRange) { ... } R processDocSections(I,R)(I inputRange) { ... } // In main app R generateDdoc(I,R)(I inputRange, string[string] macroDefs) { // UFCS FTW! return inputRange.extractDocComments() .expandMacros(macroDefs) .processDocSections(); } T -- Your inconsistency is the only consistent thing about you! -- KD  Jan 09 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: On Wed, Jan 9, 2013 at 12:57 AM, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote: Yah, though note that these macros were only necessary because I was doing unusual stuff subheadings for TABLE_3ROWS and multiline paragraph for TABLE_2ROWS. If special stuff is not required you can use TABLE2 for up to 10 columns. Oh, I did not see that, that's good to know. This should cover most needs. I also like your use of the listings package. How did you 'disable' the automatic colouring DMD insert in code samples? I defined these guys: D_COMMENT=$0
D_STRING=$0 D_KEYWORD=$0

Simple and elegant :)

You introduce listingsas a dependency. I guess it's a very common
package, that should not cause problems. Maybe syntax highlighting can
be disabled if LaTeX does not find listings.

I reached a sort of weird conclusion that ddoc is a redoubtable
documentation source format. (I'm not sure whether it's better than Markdown
or not as I'm not very fluent with Markdown.) One great thing about ddoc is
that macros are infinitely flexible, and the expansion rules are not as
weird as other macro systems such as M4.

The thing is, markdown is just a mark-up language: it's 'passive': no
function, no expansion. I agree having some 'programmability' is nice.
LaTeX is showing its age there. Ddoc has the merit of being
wonderfully simple concerning its macro expansion algorithm.
But markdown is widely used, if only for sites like Github or StackOverflow.

I have code somewhere to produce a document using D only. That gave me
access to the entire D power, so it's the other part of the spectrum.

auto doc = document( title("A title"),
section(...),
section(...),
section(...)
);

string latex = doc.as!"LaTeX";
string html = doc.as!"HTML";

and so on. Still embryonic and not a priority for me right now.

And, I'm slowly assembling small D parsers for markdown, xml, (a very
limited subset of) LaTeX for a project I call Dialect, that would
offer limited source-to-source translation for markup languages. Ddoc
is also a target, but you just showed it can fend for itself quite
well :)

The table use case is telling - as soon as I needed a special table form I
could just encode that as a macro. I think with Markdown you get to generate
one kind of table but if you want to fine-tune any particular table you just
can't.

Exactly. It's not a programming language. Maybe people use templates for that.

Jan 09 2013
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/8/13 3:12 PM, Walter Bright wrote:
On 1/8/2013 2:51 PM, Andrei Alexandrescu wrote:
I just pushed the first passable PDF documentation generated via LaTeX
with
ddoc: http://goo.gl/QIP4t. For now I'm only rendering the TOC and
lex.dd, but at
this time we have enough seed for anyone interested to convert other
files.

Take a look at the generated PDF: http://erdani.com/d/dlangspec.pdf

Andrei

Looks good to me.

I should add this is a rather large success story for ddoc. This is the
first time ddoc has been used to generate a format that has nothing to
do with HTML. LaTeX is different enough from HTML and finicky enough so
we can claim if generating this was possible, pretty much any format is
approachable.

It's also good to keep in mind that when I prepared the kindle version,
which has a small screen, I had to rather ruthlessly pare down the
length of preformatted lines like the code examples.

Yah, for this proof of concept I'm using the stock article interior
design. The production version should include beautiful PDFs designed
purposefully for the Kindle.

In fact I just uploaded a Kindle-specialized pdf. I don't have the
Kindle on me so I went blindly. Take a look and let me know!

http://erdani.com/d/dlangspec-kindle.pdf

Formatting code and tables will be a challenge but nothing really difficult.

Andrei

Jan 08 2013
"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Jan 08, 2013 at 02:51:44PM -0800, Andrei Alexandrescu wrote:
On 1/4/13 7:53 PM, Andrei Alexandrescu wrote:
Now that the issue of documentation came up, I wonder if there's
interest in a high-quality PDF rendering of the language spec (e.g.
similar to the interior design of TDPL itself). Is it worth the
effort?

Thanks,

Andrei

I just pushed the first passable PDF documentation generated via
LaTeX with ddoc: http://goo.gl/QIP4t. For now I'm only rendering the
TOC and lex.dd, but at this time we have enough seed for anyone
interested to convert other files.

Take a look at the generated PDF: http://erdani.com/d/dlangspec.pdf

[...]

Those single-column lists that span multiple pages are ugly, though. You
might want to consider defining some LaTeX macros that split it up into
multiple columns, depending on how many items there are. There should be
a way to do this using things like the ifthen module (which AFAIK is
included in standard LaTeX distributions). The macro can go into the doc
preamble, and then the ddoc comment can just reference it.

I'd present an example of such a macro here, but my LaTeX is a bit
rusty, and I'd need to look it up when I get home.

T

--
If a person can't communicate, the very least he could do is to shut up. -- Tom
Lehrer, on people who bemoan their communication woes with their loved ones.

Jan 08 2013