## digitalmars.D - dlangspec.pdf?

• Andrei Alexandrescu (5/5) Jan 04 2013 Now that the issue of documentation came up, I wonder if there's
• =?ISO-8859-1?Q?Alex_R=F8nne_Petersen?= (6/11) Jan 04 2013 I would love to have that.
• Jordi Sayol (4/10) Jan 04 2013 +1000
• H. S. Teoh (13/17) Jan 04 2013 [...]
• Andrei Alexandrescu (4/18) Jan 04 2013 The spec pdf would be just a rendering of the online dox, just like
• H. S. Teoh (8/27) Jan 04 2013 [...]
• Philippe Sigaud (7/10) Jan 05 2013 I'd be interested.
• =?UTF-8?B?QWxleCBSw7hubmUgUGV0ZXJzZW4=?= (8/19) Jan 05 2013 We just have way too much documentation already written in Ddoc.
• Andrei Alexandrescu (3/5) Jan 05 2013 But Markdown seems to have no macros.
• Philippe Sigaud (13/18) Jan 05 2013 Indeed it has none, good point.
• Andrei Alexandrescu (11/30) Jan 05 2013 Yah, those are different beasts as there's a lot of repetitive crap the
• Walter Bright (3/4) Jan 05 2013 I've often thought that that macro system should be put in Phobos as a m...
• Philippe Sigaud (5/11) Jan 05 2013 What should it be? Some module to define text transformations? std.regex
• Walter Bright (4/6) Jan 05 2013 A text macro system is not std.regex at all. What std.textmacro should b...
• Philippe Sigaud (61/68) Jan 05 2013 Here is my first try for a LaTeX-generating list of Ddoc macros. I'm sur...
• Walter Bright (11/19) Jan 05 2013 Having macros in Ddoc have been a godsend for improving productivity. Fo...
• Philippe Sigaud (16/42) Jan 05 2013 I see that. But see below.
• Walter Bright (7/20) Jan 05 2013 You are entering another land with it. Text processing is totally differ...
• Philippe Sigaud (6/25) Jan 05 2013 I'm not convinced, but that's not really important.
• Walter Bright (2/4) Jan 05 2013 https://github.com/D-Programming-Language/d-programming-language.org
• Philippe Sigaud (3/9) Jan 05 2013 Oh, .dd files! I did not search for those, I didn't even know they exist...
• Jacob Carlborg (9/12) Jan 05 2013 Just do what PHP, Ruby and other similar languages do:
• Andrei Alexandrescu (7/12) Jan 05 2013 Yah, I also played with producing LaTeX and hit the same problem. Had to...
• Walter Bright (6/17) Jan 05 2013 C:>grep DDOC_COMMENT *.c
• Philippe Sigaud (55/57) Jan 06 2013 Nothing significant yet, that's my first dib into macro.
• H. S. Teoh (18/28) Jan 06 2013 LaTeX has its own syntactic conventions. Curly braces must be escaped
• Philippe Sigaud (5/24) Jan 06 2013 Damn right.
• Walter Bright (3/4) Jan 06 2013 At one point I looked into doing Latex macros for Ddoc, but unfortunatel...
• Andrei Alexandrescu (3/8) Jan 06 2013 ??? I already have something in progress.
• Walter Bright (2/10) Jan 06 2013 Cool! You know Latex far better than I.
• H. S. Teoh (17/25) Jan 07 2013 I think the simplest way would be to allow the definition of some kind
• Adam D. Ruppe (14/17) Jan 07 2013 Believe it or not, but dmd already has the beginnings of this
• H. S. Teoh (10/30) Jan 07 2013 Inline HTML should not be allowed in ddoc, because it completely defeats
• Era Scarecrow (5/11) Jan 07 2013 Depends on what HTML was used (and can extend to BBCode as
• Andrei Alexandrescu (5/9) Jan 07 2013 A set of ddoc macros that convert to LaTeX starting from Philippe's
• Andrei Alexandrescu (6/16) Jan 07 2013 Heh, here's the first thing that I actually got to compile error-free
• Jordi Sayol (7/25) Jan 07 2013 "htmldoc" converts html files into pdf, generating a toc.
• Philippe Sigaud (3/7) Jan 07 2013 I tried to find all the macros that created those ugly
• Philippe Sigaud (3/7) Jan 07 2013 Nice looking doc.
• Jordi Sayol (8/26) Jan 07 2013 wkhtmltopdf v0.11.0 (static)
• Era Scarecrow (2/8) Jan 07 2013 Glanced it over and it looks nice. :)
• Philippe Sigaud (3/13) Jan 07 2013 It indeed looks very nice. If the entire content is here, it should be m...
• Jordi Sayol (15/33) Jan 08 2013 "dlangspec" in Electronic Publication (epub) e-book file format, generat...
• Philippe Sigaud (4/17) Jan 07 2013 Same here. The two systems do not see tables in the same way.
• Philippe Sigaud (6/9) Jan 05 2013 Don't tempt me. I'm playing with the idea of writing a Ddoc <-> Markdown
• Nicolas Sicard (4/7) Jan 05 2013 Couldn't a .ddoc file with redefined macros produce Markdown
• David Nadlinger (5/12) Jan 05 2013 This seems a bit backwards â€“ the point of Markdown is precisely
• Andrei Alexandrescu (4/8) Jan 05 2013 Yes, that would be the better route. But then if we want to generate
• Nicolas Sicard (5/9) Jan 05 2013 I was wondering: do you use Pandoc to do that (e.g. for your
• Philippe Sigaud (6/15) Jan 05 2013 Yes. Nice piece of Haskell software. I discovered it a few weeks ago and
• alex (4/5) Jan 05 2013 Regarding LaTex..why not LaTex? I mean, pdf and all other
• Philippe Sigaud (9/14) Jan 05 2013 LaTeX could be a possible target, at least as an intermediate stage for
• Andrei Alexandrescu (7/12) Jan 08 2013 I just pushed the first passable PDF documentation generated via LaTeX
• Walter Bright (5/10) Jan 08 2013 Looks good to me.
• Philippe Sigaud (14/19) Jan 08 2013 Yes, that has indeed quite a palatable appearance. I see you defined 2
• Andrei Alexandrescu (19/38) Jan 08 2013 Yah, though note that these macros were only necessary because I was
• Walter Bright (4/7) Jan 08 2013 I had one great advantage in it being the fifth text macro processor I'd...
• Philippe Sigaud (16/18) Jan 09 2013 So, this should:
• Walter Bright (3/21) Jan 09 2013 No no no. The module gets its input from an InputRange. Not a file. It g...
• H. S. Teoh (33/63) Jan 09 2013 I agree, the interface should be as generic as possible. I think it
• Walter Bright (3/5) Jan 09 2013 No. Where the macro definitions come from is a completely separate probl...
• H. S. Teoh (13/19) Jan 09 2013 I disagree. The macro definitions does not need to (and probably should
• Walter Bright (3/6) Jan 09 2013 I've developed multiple macro systems. There is no standard way of getti...
• Philippe Sigaud (9/18) Jan 09 2013 That's not what I'm talking about, sorry for not being clear. I don't
• Walter Bright (3/8) Jan 09 2013 The current ddoc macro system does recognize D code. This should be remo...
• Philippe Sigaud (28/47) Jan 09 2013 Oh, I did not see that, that's good to know. This should cover most need...
• Andrei Alexandrescu (14/30) Jan 08 2013 I should add this is a rather large success story for ddoc. This is the
• H. S. Teoh (14/30) Jan 08 2013 [...]
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: http://d-packages.googlecode.com/files/dlangspec.epub -- 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. - 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. 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
[...] Not bad. 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