## 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
=?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
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
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
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
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
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 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 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
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
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
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
"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
"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
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.

Unfortunately "htmldoc" do not support css.
--
Jordi Sayol

Jan 07 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
--0016e6d271c953e71204d2ba7442
Content-Type: text/plain; charset=UTF-8

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?

--0016e6d271c953e71204d2ba7442
Content-Type: text/html; charset=UTF-8

<br><br><div class="gmail_quote">On Mon, Jan 7, 2013 at 7:23 PM, Andrei
Alexandrescu <span dir="ltr">&lt;<a href="mailto:SeeWebsiteForEmail erdani.org"
target="_blank">SeeWebsiteForEmail erdani.org</a>&gt;</span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc
solid;padding-left:1ex"><div>On 1/7/13 9:30 AM, H. S. Teoh wrote:<br>
</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px
On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote:<br>
</div><div><blockquote class="gmail_quote" style="margin:0 0 0
??? I already have something in progress.<br>
</blockquote></div>
[...]<div><br>
<br>
Curious ears want to hear what that something is. :-)<br>
</div></blockquote>
<br>
A set of ddoc macros that convert to LaTeX starting from Philippe&#39;s macros.
The one systemic issue I encountered so far is tables, which in LaTeX must set
the number of columns in advance.</blockquote><div><br></div>

<div>Same here. The two systems do not see tables in the same
way.</div><div><br></div><div>Did you find a way to get syntax-highlighted
code?</div></div>

--0016e6d271c953e71204d2ba7442--

Jan 07 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
--20cf3074da5a3ed35204d2ba8ad0
Content-Type: text/plain; charset=UTF-8

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 :)

Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<br><div class=3D"gmail_quote"><blockquote class=3D"gmail_quote" style=3D"m=
argin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Heh, here&#39;s the first thing that I actually got to compile error-free f=
rom spec.dd and lex.dd: <a href=3D"http://erdani.com/d/dlangspec.pdf" targe=
t=3D"_blank">http://erdani.com/d/dlangspec.<u></u>pdf</a>. Had to fudge a f=
ew macros and some stuff doesn&#39;t expand to what it should, but from her=
e the path is relatively easy.</blockquote>
<div><br></div><div>I tried to find all the macros that created those ugly =
&lt;a =3D href... thingies before posting, but it looks like there are stil=
l some wandering around :)</div><div><br></div><div>=C2=A0</div></div>


Jan 07 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
--bcaec51b16d5b26d2f04d2ba93b9
Content-Type: text/plain; charset=UTF-8

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

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)

--bcaec51b16d5b26d2f04d2ba93b9
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<br><div class=3D"gmail_quote"><blockquote class=3D"gmail_quote" style=3D"m=
argin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div cla=
ss=3D"h5">
<br>
</div></div>&quot;htmldoc&quot; converts html files into pdf, generating a =
toc.<br>
<br>
In this sample I&#39;ve removed original toc and &quot;htmldoc&quot; genera=
ted a toc with 2 levels.<br>
lockquote><div><br></div><div>Nice looking doc.=C2=A0</div><div><br></div><=
div>
Having &#39;dmd -D latex.ddoc spec.dd&#39; generate that will be our first =
goal :) (the second one would to get it as nice as TDPL)</div><div><br></di=
v><div>=C2=A0</div></div>

--bcaec51b16d5b26d2f04d2ba93b9--

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)

Converts html files into pdf, generating a toc index, and accepts css!

An example built in Linux 64-bit:

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

Converts html files into pdf, generating a toc index, and
accepts css!

An example built in Linux 64-bit:

Glanced it over and it looks nice. :)

Jan 07 2013
Philippe Sigaud <philippe.sigaud gmail.com> writes:
--047d7b6777f2b4d2df04d2c0797f
Content-Type: text/plain; charset=UTF-8

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)

Converts html files into pdf, generating a toc index, and accepts css!

An example built in Linux 64-bit:

Glanced it over and it looks nice. :)

It indeed looks very nice. If the entire content is here, it should be made

--047d7b6777f2b4d2df04d2c0797f
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<br><br><div class=3D"gmail_quote">On Tue, Jan 8, 2013 at 5:02 AM, Era Scar=
ecrow <span dir=3D"ltr">&lt;<a href=3D"mailto:rtcvb32 yahoo.com" target=3D"=
_blank">rtcvb32 yahoo.com</a>&gt;</span> wrote:<br><blockquote class=3D"gma=
il_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-lef=
t:1ex">
<div class=3D"im">On Tuesday, 8 January 2013 at 03:45:36 UTC, Jordi Sayol w=
rote:<br>
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
wkhtmltopdf v0.11.0 (static)<br>
<br>
Converts html files into pdf, generating a toc index, and accepts css!<br>
<br>
An example built in Linux 64-bit:<br>
a><br>
</blockquote>
<br></div>
=C2=A0Glanced it over and it looks nice. :)<br></blockquote><div><br></div>=
<div>It indeed looks very nice. If the entire content is here, it should be=

--047d7b6777f2b4d2df04d2c0797f--

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 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 "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. 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: --047d7b6774d07272c204d2a21648 Content-Type: text/plain; charset=UTF-8 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. 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 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. --047d7b6774d07272c204d2a21648 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sun, Jan 6, 2013 at 4:19 PM, H. S. Te= oh <span dir=3D"ltr">&lt;<a href=3D"mailto:hsteoh quickfur.ath.cx" target= =3D"_blank">hsteoh quickfur.ath.cx</a>&gt;</span> wrote:<br><blockquote cla= ss=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;pa= dding-left:1ex"> <div class=3D"im">On Sun, Jan 06, 2013 at 10:44:27AM +0100, Philippe Sigaud= wrote:<br> &gt; &gt; Philippe, please share with me as soon as you have anything signi= ficant<br> &gt; &gt; done in terms of LaTeX production so we don&#39;t overlap work.<b= r> &gt; &gt;<br> &gt; &gt;<br> &gt; Nothing significant yet, that&#39;s my first dib into macro.<br> &gt; I use these, but have a problem for code highlighting: DMD inserts mac= ros<br> &gt; to colour the code, these don&#39;t play well with my usual solutions = (package<br> &gt; pygmentize or package listings). The same for \verbatim{} instruction.= <br> &gt; Here, I just used a simple \texttt{} instruction, but in this case cur= ly<br> &gt; braces are lost :(<br> <br> </div>LaTeX has its own syntactic conventions. Curly braces must be escaped= <br> with backslash, and certain operators (^ in particular, which also<br> affects ^^) will cause syntax errors, because they are metacharacters<br> with a different meaning. All of them need to be properly escaped.<br></blo= ckquote><div><br></div><div>Exactly.</div><div>=C2=A0</div><blockquote clas= s=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;pad= ding-left:1ex"> <br> You may be able to use \begin{verbatim} and \end{verbatim} (which<br> doesn&#39;t suffer from the trailing brace problem) but you can&#39;t use i= t for<br> inline spans of text.<br></blockquote><div><br></div><div>Damn right.</div>= <div><br></div><div>I&#39;ll try with the listings package, but I don&#39;t= have much hope to achieve what I want.</div></div> --047d7b6774d07272c204d2a21648--  Jan 06 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: --047d7bfcf91adbc02104d286cfc1 Content-Type: text/plain; charset=UTF-8 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 Philippe --047d7bfcf91adbc02104d286cfc1 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On Sat, Jan 5, 2013 at 7:20 AM, Andrei Alexandrescu <span dir=3D"ltr">&lt;<= a href=3D"mailto:SeeWebsiteForEmail erdani.org" target=3D"_blank">SeeWebsit= eForEmail erdani.org</a>&gt;</span> wrote:<br><div class=3D"gmail_quote"><b= lockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px = #ccc solid;padding-left:1ex"> <div class=3D"im"><br></div> The spec pdf would be just a rendering of the online dox, just like .mobi i= s.</blockquote><div><br></div><div>I&#39;d be interested.</div><div><br></d= iv><div>It can also be done in markdown, which we all know now, with github= being a central D repository.</div> <div>From markdown, it can easily be translated into pdf, html, mobi or epu= b (heck, even docx)</div><div><br></div><div><br></div><div>Philippe</div><= div>=C2=A0</div></div> --047d7bfcf91adbc02104d286cfc1--  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 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: --20cf30334419f0b8a804d28b1e4c Content-Type: text/plain; charset=UTF-8 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 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. --20cf30334419f0b8a804d28b1e4c Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 10:33 AM, Nicolas= Sicard <span dir=3D"ltr">&lt;<a href=3D"mailto:dransic gmail.com" target= =3D"_blank">dransic gmail.com</a>&gt;</span> wrote:<br><blockquote class=3D= "gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding= -left:1ex"> <div class=3D"im">On Saturday, 5 January 2013 at 08:59:32 UTC, Philippe Sig= aud wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"><blockquote class=3D"gmail_quote" style=3D"m= argin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> From markdown, it can easily be translated into pdf, html, mobi or epub<br> (heck, even docx)<br> <br> Philippe<br> </blockquote> <br></div> I was wondering: do you use Pandoc to do that (e.g. for your D-template tut= orial)?</blockquote><div><br></div><div>Yes. Nice piece of Haskell software= . I discovered it a few weeks ago and spent the holidays converting 200 pag= es of text :)</div> <div><br></div><div>The only thing I miss with Markdown is the ability to l= ink to internal reference in the text: titles are anchors with Pandoc, but = I don&#39;t know how to get an equivalent of LaTeX \label =3D&gt; \ref.</di= v> <div><br></div><div>=C2=A0=C2=A0</div></div> --20cf30334419f0b8a804d28b1e4c--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --047d7bea3e269006c104d28b28ad Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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. --047d7bea3e269006c104d28b28ad Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 10:17 AM, Alex R= =C3=B8nne Petersen <span dir=3D"ltr">&lt;<a href=3D"mailto:alex lycus.org" = target=3D"_blank">alex lycus.org</a>&gt;</span> wrote:<br><blockquote class= =3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padd= ing-left:1ex"> <div class=3D"im"><br></div> We just have way too much documentation already written in Ddoc.<br> <br> 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.</blockquote><div><br= </div><div>Don&#39;t tempt me. I&#39;m playing with the idea of writing a = (a subset of) html, maybe a subset of LaTeX.</div><div><br></div></div> --047d7bea3e269006c104d28b28ad--  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: --20cf30334c5b3bde8604d28bf29a Content-Type: text/plain; charset=UTF-8 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. --20cf30334c5b3bde8604d28bf29a Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 3:42 PM, alex <sp= an dir=3D"ltr">&lt;<a href=3D"mailto:info alexanderbothe.com" target=3D"_bl= ank">info alexanderbothe.com</a>&gt;</span> wrote:<br><blockquote class=3D"= gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-= left:1ex"> <div class=3D"im">On Saturday, 5 January 2013 at 14:08:00 UTC, Philippe Sig= aud wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> to get an equivalent of LaTeX \label =3D&gt; \ref.<br> </blockquote> <br></div> Regarding LaTex..why not LaTex? I mean, pdf and all other container derivat= ives aren&#39;t a problem then (anymore)<br> </blockquote></div><br><div>LaTeX could be a possible target, at least as a= n intermediate stage for pdf.=C2=A0</div><div><br></div><div>But it&#39;s m= onstrously difficult to parse it in full, so only the concerned subset woul= d be available as input: header markup, emphasis, the usual stuff. That mak= es for 90% of tex files out there, but general LaTeX commands are quite ano= ther beast.</div> <div>Of course, since we are talking about documentation, the need for mark= up is quite restricted.</div> --20cf30334c5b3bde8604d28bf29a--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --047d7bea3e266d5ce704d28c0e63 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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. --047d7bea3e266d5ce704d28c0e63 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 2:13 PM, Andrei A= lexandrescu <span dir=3D"ltr">&lt;<a href=3D"mailto:SeeWebsiteForEmail erda= ni.org" target=3D"_blank">SeeWebsiteForEmail erdani.org</a>&gt;</span> wrot= e:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"><div class=3D"im">On 1/5/13 4:17 AM, Alex R= =C3=B8nne Petersen wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> But I agree - Markdown would be significantly nicer to write the spec<br> in... Ddoc has a too HTML-y feel to it for general writing.<br> </blockquote> <br></div> But Markdown seems to have no macros.</blockquote><div><br></div><div>Indee= d it has none, good point.</div><div><br></div><div>Since I just remade a 1= 80-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.</div> <div><br></div><div>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 co= mpulsion (some macros are a bit obscure for me when I read documentation in= raw form)</div> <div><br></div><div>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.</div></div> --047d7bea3e266d5ce704d28c0e63--  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 "David Nadlinger" <see klickverbot.at> writes: 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: --20cf3074b0f2ac38e104d28f0193 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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= converter. Something like Pandoc, but lighter. Couldn't a .ddoc file with redefined macros produce Markdown output? 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. --20cf3074b0f2ac38e104d28f0193 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 7:12 PM, David Na= dlinger <span dir=3D"ltr">&lt;<a href=3D"mailto:see klickverbot.at" target= =3D"_blank">see klickverbot.at</a>&gt;</span> wrote:<br><blockquote class= =3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padd= ing-left:1ex"> <div class=3D"HOEnZb"><div class=3D"h5">On Saturday, 5 January 2013 at 17:1= 3:07 UTC, Nicolas Sicard wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> On Saturday, 5 January 2013 at 14:10:38 UTC, Philippe Sigaud wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> Don&#39;t tempt me. I&#39;m playing with the idea of writing a Ddoc &lt;-&g= t; Markdown<br> converter. Something like Pandoc, but lighter.<br> </blockquote> <br> Couldn&#39;t a .ddoc file with redefined macros produce Markdown output?<br= </blockquote></div></div></blockquote><div><br></div><div>In theory, yes.<= e=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> <div class=3D"HOEnZb"><div class=3D"h5"><blockquote class=3D"gmail_quote" s= tyle=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> </blockquote> </div></div>This seems a bit backwards =E2=80=93 the point of Markdown is p= recisely to be easy to read and write in *source* form, so using it as an i= ntermediate format doesn&#39;t make much sense, at least to me.</blockquote= <div> --20cf3074b0f2ac38e104d28f0193--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --047d7bea3e26c626a704d291536a Content-Type: text/plain; charset=UTF-8 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. does this quite well. Of course, having std.parse and std.lex would be a godsend :) --047d7bea3e26c626a704d291536a Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 10:11 PM, Walter = Bright <span dir=3D"ltr">&lt;<a href=3D"mailto:newshound2 digitalmars.com" = target=3D"_blank">newshound2 digitalmars.com</a>&gt;</span> wrote:<br><bloc= kquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #cc= c solid;padding-left:1ex"> <div class=3D"im">On 1/5/2013 11:30 AM, Andrei Alexandrescu wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> I learned with time that ddoc&#39;s macro system is quite coherent and well= designed.<br> </blockquote> <br></div> I&#39;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.<br> <br> </blockquote></div><br><div>What should it be? Some module to define text t= ransformations? std.regex does this quite well.</div><div><br></div><div>Of= course, having std.parse and std.lex would be a godsend :)</div><div> <br></div> --047d7bea3e26c626a704d291536a--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --0050450166d9a10dd904d29169a8 Content-Type: text/plain; charset=UTF-8 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

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 :(

--0050450166d9a10dd904d29169a8
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On Sat, Jan 5, 2013 at 10:09 PM, Walter Bright <span dir=3D"ltr">&lt;<a hre=
f=3D"mailto:newshound2 digitalmars.com" target=3D"_blank">newshound2 digita=
lmars.com</a>&gt;</span> wrote:<br><div class=3D"gmail_quote"><blockquote c=
lass=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;=
<div class=3D"im">On 1/5/2013 7:14 AM, Philippe Sigaud wrote:<br>
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
Since I just remade a 180-pages tutorial on D templates in markdown without=
much<br>
trouble, I guess documentation and tutorial are different beasts. I felt no=
need<br>
for macros, really, but I can see how they are useful for Ddoc pages.<br>
</blockquote>
<br></div>
Having macros in Ddoc have been a godsend for improving productivity. For e=
xample, some bits need to be added or removed for generating an ebook - mac=
ros handle that in an ideal fashion. They&#39;re great for adding boilerpla=
te, when urls need to be mass changed, etc. It just goes on.<br>
</blockquote><div><br></div><div>I see that. But see below.</div><div>=C2=
=A0</div><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;borde=
tyle=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class=3D"im"><br></div><div class=3D"im">
You know, I always felt Ddoc was a strange sublanguage bolted onto D. An el=
egant<br>
solution would be to have macros be D code, but I have nothing to propose h=
ere.<br>
</div></blockquote>
<br>
It is a strange sublanguage. It has its problems, but compared to what D do=
cumentation was like before Ddoc, it is a HUGE and incalculable leap forwar=
d. </blockquote><div><br></div><div>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&#39;= m entering another land =C2=A0when I have to use it.=C2=A0</div> <div><br></div><div>=C2=A0</div><blockquote class=3D"gmail_quote" style=3D"= margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">The Phobos d= ocumentation, for example, before Ddoc was complete and utter garbage that = rarely had any correspondence to what the code actually was and did.<br> <br> And, btw, I have published on Amazon a couple of non-tech ebooks. I used Dd= oc for them, and there is no html feel to the result. They look like any ot= her ebook.<br> <br> </blockquote></div>Do you have any macro to present? They could be used by = other people, as an example of Ddoc power.<div><br></div><div>Also, it woul= d be nice to present the article from the website as .d files with Ddoc mac= ros. They are only accessible as HTML (that&#39;s the end goal, yes, but ha= ving them as .d files would be good).</div> <div>Also, Phobos/index.d is sadly in HTML, not in Ddoc.</div><div><br></di= v><div><br></div><div>Btw, I just played a bit with macros and defined a sm= all bunch of LaTex-producing macros. I&#39;ll post that.</div><div><br> </div><div>It doesn&#39;t help that DMD inserts a HTML comment at the begin= ning:</div><div><br></div><div>&lt;!-- Generated by Ddoc from filename.d --= &gt;</div><div><br></div><div>HTML hardwired into the final result, whateve= r the doc says :(</div> <div><br></div><div><br></div> --0050450166d9a10dd904d29169a8--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --20cf3074b0f281299204d291cb2e Content-Type: text/plain; charset=UTF-8 On Sat, Jan 5, 2013 at 8:30 PM, Andrei Alexandrescu < SeeWebsiteForEmail erdani.org> wrote: 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. 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} --20cf3074b0f281299204d291cb2e Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 8:30 PM, Andrei Alexa= ndrescu <span dir=3D"ltr">&lt;<a href=3D"mailto:SeeWebsiteForEmail erdani.o= rg" target=3D"_blank">SeeWebsiteForEmail erdani.org</a>&gt;</span> wrote:<b= r><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:= 1px #ccc solid;padding-left:1ex"> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"><div class=3D"h5"><br></div></blockquote><di= v class=3D"im"><br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> You know, I always felt Ddoc was a strange sublanguage bolted onto D. An<br= to propose here.<br> </blockquote> <br></div> I learned with time that ddoc&#39;s macro system is quite coherent and well= designed.<span class=3D"HOEnZb"><font color=3D"#888888"><br> <br></font></span></blockquote><div><br></div><div>Here is my first try for= a LaTeX-generating list of Ddoc macros. I&#39;m sure a LaTeX guru would fi= nd some of these quite dangerous :)</div><div>The final, global, appearance= should be mostly defined in the DDOC macro.</div> <div><br></div><div>I wonder how to have ddoc produce code highlighting tha= t&#39;s compatible with LaTex.=C2=A0</div><div><br></div><div>- Curly brace= s are a bit special in LaTex, hence using \texttt{} does not work well.</di= v> <div>- But using \begin{verbatim} \end{verbatim} disable the coloring code = produced by Ddoc.</div><div><br></div><div>For my own docs, I use pygmentiz= e... Else I suppose the listings could also work.</div><div><br></div><div> I gather some hypothesis (namely, that the end output will be HTML) are a b= it hardwired in Ddoc.</div><div><br></div><div>Anyway:</div><div><br></div>= <div>B=3D\textbf{$0}</div><div>I=3D\textit{$0}</div><div>U=3D\underline{$0}=
</div>
<div>P=3D $0</div><div><br></div><div>DL=3D\begin{description}</div><div>$0=
</div><div>\end{description}</div><div>DT=3D\item[$0]</div><div>DD=3D$0</di=
v><div>TABLE=3D\begin{tabular}[2]{l|l}</div><div>$0</div><div>\end{tabular}= </div> <div>TR=3D$0 \\</div><div>TH=3D$0 &amp;</div><div>TD=3D$0</div><div>OL=3D\b=
egin{enumerate}</div><div>$0</div><div>\end{enumerate}</div><div>UL=3D\begi= n{itemize}</div><div>$0</div><div>\end{itemize}</div><div>LI=3D\item $0</di= v><div>BIG=3D\large{$0}</div>
<div>SMALL=3D\small{$0}</div><div>BR=3D\newline</div><div>LINK=3D\url{$0}</=
div><div>LINK2=3D\href{$1}{$+}</div><div>RED=3D{\color{red}$0}</div><div>BL= UE=3D{\color{blue}$0}</div><div>GREEN=3D{\color{green}$0}</div><div>YELLOW= =3D{\color{yellow}$0}</div>
<div>BLACK=3D{\color{black}$0}</div><div>WHITE=3D{\color{white}$0}</div><di=
v>D_CODE=3D\begin{verbatim}</div><div>$0</div><div>\end{verbatim}</div><div= DDOC=3D\documentclass[11pt]{article}</div><div>\usepackage{color}</div><di= </div><div>\usepackage{hyperref}</div><div>\begin{document}</div><div>\titl= e{$(TITLE)}</div><div>\date{}</div><div>\maketitle</div><div><br></div><div=
$(BODY)</div><div>\end{document}</div><div><br></div></div> --20cf3074b0f281299204d291cb2e--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --001636eef8bacbede604d29265b9 Content-Type: text/plain; charset=UTF-8 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) --001636eef8bacbede604d29265b9 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sat, Jan 5, 2013 at 11:17 PM, Walter = Bright <span dir=3D"ltr">&lt;<a href=3D"mailto:newshound2 digitalmars.com" = target=3D"_blank">newshound2 digitalmars.com</a>&gt;</span> wrote:<br><bloc= kquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #cc= c solid;padding-left:1ex"> <div class=3D"im">On 1/5/2013 1:32 PM, Philippe Sigaud wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> What should it be? Some module to define text transformations? std.regex do= es<br> this quite well.<br> </blockquote> <br> <br></div> A text macro system is not std.regex at all. What std.textmacro should be i= s a range that takes a text input stream, an associative array of NAME=3DVA= LUE pairs, and it outputs a text range with the macros having been expanded= .<br> </blockquote><div><br></div><div>OK, that&#39;s doable. It looks like a map= -flatten action.</div><div>(map the first element, it might contain new mac= ros, expand these again, etc)</div><div><br></div><div><br></div><div>=C2= =A0</div> </div><br> --001636eef8bacbede604d29265b9--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --20cf303344196dc1e204d2926dc0 Content-Type: text/plain; charset=UTF-8 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.

--20cf303344196dc1e204d2926dc0
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On Sat, Jan 5, 2013 at 11:20 PM, Walter Bright <span dir=3D"ltr">&lt;<a hre=
f=3D"mailto:newshound2 digitalmars.com" target=3D"_blank">newshound2 digita=
lmars.com</a>&gt;</span> wrote:<br><div class=3D"gmail_quote"><blockquote c=
lass=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;=
<div class=3D"im">On 1/5/2013 1:38 PM, Philippe Sigaud wrote:<br>
</div><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-l=
=C2=A0 =C2=A0 It is a strange sublanguage. It has its problems, but compare=
d to what D<br>
=C2=A0 =C2=A0 documentation was like before Ddoc, it is a HUGE and incalcul=
able leap forward.<br>
<br>
<br></div><div class=3D"im">
I was just wondering if there was a way to make it a bit more D-ish. The $(= NAME<br> arg, arg) syntax feels like I&#39;m entering another land =C2=A0when I have= to use it.<br> </div></blockquote> <br> You are entering another land with it. Text processing is totally different= , and it should be different.<br></blockquote><div><br></div><div>I&#39;m n= ot convinced, but that&#39;s not really important.</div><blockquote class= =3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padd= ing-left:1ex"> <br> They aren&#39;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.</blockquote><div><br></div><blockquote class= =3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padd= ing-left:1ex"> <div class=3D"im"><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .= 8ex;border-left:1px #ccc solid;padding-left:1ex">Also, Phobos/index.d is sa= dly in HTML, not in Ddoc.<br> </blockquote> <br></div> All those source files are on github.<br></blockquote><div><br></div><div>I= must be tired, because the only .ddoc file I find is std.ddoc.=C2=A0No .d = article on templates, etc: only the .html files.=C2=A0</div><div><br></div>= <div> <br></div></div><br> --20cf303344196dc1e204d2926dc0--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --20cf3074da5ae2cc9404d299dcd4 Content-Type: text/plain; charset=UTF-8 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. --20cf3074da5ae2cc9404d299dcd4 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <br><br><div class=3D"gmail_quote">On Sun, Jan 6, 2013 at 1:40 AM, Walter B= right <span dir=3D"ltr">&lt;<a href=3D"mailto:newshound2 digitalmars.com" t= arget=3D"_blank">newshound2 digitalmars.com</a>&gt;</span> wrote:<br><block= quote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc= solid;padding-left:1ex"> <div class=3D"im">On 1/5/2013 2:50 PM, Philippe Sigaud wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> I must be tired, because the only .ddoc file I find is std.ddoc. No .d arti= cle<br> on templates, etc: only the .html files.<br> </blockquote> <br> </div><a href=3D"https://github.com/D-Programming-Language/d-programming-la= nguage.org" target=3D"_blank">https://github.com/D-<u></u>Programming-Langu= age/d-<u></u>programming-language.org</a><br> </blockquote></div><br><div>Oh, .dd files! I did not search for those, I di= dn&#39;t even know they existed.</div><div><br></div><div>Thanks, now I can= look how you did some linking and layout.</div> --20cf3074da5ae2cc9404d299dcd4--  Jan 05 2013 Philippe Sigaud <philippe.sigaud gmail.com> writes: --001636eef8ba00097c04d29b8f7a Content-Type: text/plain; charset=UTF-8 Philippe, please share with me as soon as you have anything significant done in terms of LaTeX production so we don't overlap work. 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}

--001636eef8ba00097c04d29b8f7a
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<br><div class=3D"gmail_quote"><blockquote class=3D"gmail_quote" style=3D"m=
argin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Philippe, please share with me as soon as you have anything significant don=
e in terms of LaTeX production so we don&#39;t overlap work.<br>
<br>
</blockquote></div><br><div>Nothing significant yet, that&#39;s my first di=
b into macro.</div><div>I use these, but have a problem for code highlighti=
ng: DMD inserts macros to colour the code, these don&#39;t play well with m=
y usual solutions (package pygmentize or package listings). The same for \v=
erbatim{} instruction. Here, I just used a simple \texttt{} instruction, bu=
t in this case curly braces are lost :(</div>
<div><br></div><div><br></div><div><div>B=3D\textbf{$0}</div><div>I=3D\text= it{$0}</div><div>U=3D\underline{$0}</div><div>P=3D$0</div><div>DL=3D\begin=
{description}</div><div>$0</div><div>\end{description}</div><div>DT=3D\item= [$0]</div>
<div>DD=3D$0</div><div>TABLE=3D\begin{tabular}[2]{l|l}</div><div>$0</div><d=
iv>\end{tabular}</div><div>TR=3D$0 \\</div><div>TH=3D$0 &amp;</div><div>TD=
=3D$0</div><div>OL=3D\begin{enumerate}</div><div>$0</div><div>\end{enumerat=
e}</div><div>
UL=3D\begin{itemize}</div><div>$0</div><div>\end{itemize}</div><div>LI=3D\i= tem$0</div><div>BIG=3D\large{$0}</div><div>SMALL=3D\small{$0}</div><div>BR=
=3D\newline</div><div>LINK=3D\url{$0}</div><div>LINK2=3D\href{$1}{$+}</div>= <div>RED=3D{\color{red}$0}</div>
<div>BLUE=3D{\color{blue}$0}</div><div>GREEN=3D{\color{green}$0}</div><div>=
YELLOW=3D{\color{yellow}$0}</div><div>BLACK=3D{\color{black}$0}</div><div>W=
HITE=3D{\color{white}$0}</div><div>D_CODE=3D\texttt{$0}</div><div>DDOC_PSYM=
BOL =3D $(U$0)</div>
<div>DDOC_ANCHOR =3D \label{$1}</div><div>DDOC_DECL =C2=A0=3D$(DT $0)</div= <div>XREF =3D$(REF std_$1.html#$2, $(D std.$1.$2))</div><div>CXREF =3D$(=

/div><div>DDOC=3D\documentclass[11pt]{article}</div>
<div>\usepackage{color}</div><div><br></div><div>\usepackage{hyperref}</div=
<div>\begin{document}</div><div>\title{$(TITLE)}</div><div>\date{}</div><d= v> </div> --001636eef8ba00097c04d29b8f7a--  Jan 06 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 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 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
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 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 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 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: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 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
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 "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
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

\$( pattern.

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