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

=?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

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

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

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

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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sat, Jan 5, 2013 at 7:20 AM, Andrei Alexandrescu <
SeeWebsiteForEmail erdani.org> wrote:

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


I'd be interested.

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

(heck, even docx)


Philippe

=?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

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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sat, Jan 5, 2013 at 2:13 PM, Andrei Alexandrescu <
SeeWebsiteForEmail erdani.org> wrote:

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

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

 But Markdown seems to have no macros.


Indeed it has none, good point.

Since I just remade a 180-pages tutorial on D templates in markdown without
much trouble, I guess documentation and tutorial are different beasts. I
felt no need for macros, really, but I can see how they are useful for Ddoc
pages.

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

You know, I always felt Ddoc was a strange sublanguage bolted onto D. An
elegant solution would be to have macros be D code, but I have nothing to
propose here.

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

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.

Philippe Sigaud <philippe.sigaud gmail.com> writes:

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

 On 1/5/2013 11:30 AM, Andrei Alexandrescu wrote:

 I learned with time that ddoc's macro system is quite coherent and well
 designed.

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

What should it be? Some module to define text transformations? std.regex
does this quite well.

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

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.

Philippe Sigaud <philippe.sigaud gmail.com> writes:

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

 On 1/5/2013 1:32 PM, Philippe Sigaud wrote:

 What should it be? Some module to define text transformations? std.regex
 does
 this quite well.


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

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

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

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.

Philippe Sigaud <philippe.sigaud gmail.com> writes:

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


  You know, I always felt Ddoc was a strange sublanguage bolted onto D. An
 elegant solution would be to have macros be D code, but I have nothing
 to propose here.

 I learned with time that ddoc's macro system is quite coherent and well
 designed.

Here is my first try for a LaTeX-generating list of Ddoc macros. I'm sure a
LaTeX guru would find some of these quite dangerous :)
The final, global, appearance should be mostly defined in the DDOC macro.

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

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

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

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

Anyway:

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

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

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

$(BODY)
\end{document}

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.

Philippe Sigaud <philippe.sigaud gmail.com> writes:

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

 On 1/5/2013 7:14 AM, Philippe Sigaud wrote:

 Since I just remade a 180-pages tutorial on D templates in markdown
 without much
 trouble, I guess documentation and tutorial are different beasts. I felt
 no need
 for macros, really, but I can see how they are useful for Ddoc pages.

 Having macros in Ddoc have been a godsend for improving productivity. For
 example, some bits need to be added or removed for generating an ebook -
 macros handle that in an ideal fashion. They're great for adding
 boilerplate, when urls need to be mass changed, etc. It just goes on.

I see that. But see below.


 You know, I always felt Ddoc was a strange sublanguage bolted onto D. An
 elegant
 solution would be to have macros be D code, but I have nothing to propose
 here.

 It is a strange sublanguage. It has its problems, but compared to what D
 documentation was like before Ddoc, it is a HUGE and incalculable leap
 forward.


I was just wondering if there was a way to make it a bit more D-ish. The
$(NAME arg, arg) syntax feels like I'm entering another land  when I have
to use it.



 The Phobos documentation, for example, before Ddoc was complete and utter
 garbage that rarely had any correspondence to what the code actually was
 and did.

 And, btw, I have published on Amazon a couple of non-tech ebooks. I used
 Ddoc for them, and there is no html feel to the result. They look like any
 other ebook.

 Do you have any macro to present? They could be used by other people, as

an example of Ddoc power.

Also, it would be nice to present the article from the website as .d files
with Ddoc macros. They are only accessible as HTML (that's the end goal,
yes, but having them as .d files would be good).
Also, Phobos/index.d is sadly in HTML, not in Ddoc.


Btw, I just played a bit with macros and defined a small bunch of
LaTex-producing macros. I'll post that.

It doesn't help that DMD inserts a HTML comment at the beginning:

<!-- Generated by Ddoc from filename.d -->

HTML hardwired into the final result, whatever the doc says :(

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.

Philippe Sigaud <philippe.sigaud gmail.com> writes:

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

 On 1/5/2013 1:38 PM, Philippe Sigaud wrote:

     It is a strange sublanguage. It has its problems, but compared to
 what D
     documentation was like before Ddoc, it is a HUGE and incalculable
 leap forward.


 I was just wondering if there was a way to make it a bit more D-ish. The
 $(NAME
 arg, arg) syntax feels like I'm entering another land  when I have to use
 it.

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

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

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


Also, Phobos/index.d is sadly in HTML, not in Ddoc.

 All those source files are on github.

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

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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sun, Jan 6, 2013 at 1:40 AM, Walter Bright <newshound2 digitalmars.com>wrote:

 On 1/5/2013 2:50 PM, Philippe Sigaud wrote:

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

 https://github.com/D-**Programming-Language/d-**programming-language.org<https://github.com/D-Programming-Language/d-programming-language.org>

Oh, .dd files! I did not search for those, I didn't even know they existed.

Thanks, now I can look how you did some linking and layout.

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

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

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.

Philippe Sigaud <philippe.sigaud gmail.com> writes:

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

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


B=\textbf{$0}
I=\textit{$0}
U=\underline{$0}
P= $0
DL=\begin{description}
$0
\end{description}
DT=\item[$0]
DD=$0
TABLE=\begin{tabular}[2]{l|l}
$0
\end{tabular}
TR=$0 \\
TH=$0 &
TD=$0
OL=\begin{enumerate}
$0
\end{enumerate}
UL=\begin{itemize}
$0
\end{itemize}
LI=\item $0
BIG=\large{$0}
SMALL=\small{$0}
BR=\newline
LINK=\url{$0}
LINK2=\href{$1}{$+}
RED={\color{red}$0}
BLUE={\color{blue}$0}
GREEN={\color{green}$0}
YELLOW={\color{yellow}$0}
BLACK={\color{black}$0}
WHITE={\color{white}$0}
D_CODE=\texttt{$0}
DDOC_PSYMBOL = $(U $0)
DDOC_ANCHOR = \label{$1}
DDOC_DECL  = $(DT $0)


LREF = \hyperref[$1]{$1}
DDOC=\documentclass[11pt]{article}
\usepackage{color}

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

$(BODY)
\end{document}

"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:

On Sun, Jan 06, 2013 at 10:44:27AM +0100, Philippe Sigaud wrote:
 Philippe, please share with me as soon as you have anything significant
 done in terms of LaTeX production so we don't overlap work.

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

LaTeX has its own syntactic conventions. Curly braces must be escaped
with backslash, and certain operators (^ in particular, which also
affects ^^) will cause syntax errors, because they are metacharacters
with a different meaning. All of them need to be properly escaped.

You may be able to use \begin{verbatim} and \end{verbatim} (which
doesn't suffer from the trailing brace problem) but you can't use it for
inline spans of text.

Unless, of course, you drop into low-level TeX hacking to redefine
metacharacters so that characters used in D code never collide with
them. (It's possible, but not recommended because nobody will be able to
read the code and understand what it does! Plus, you'll have to restore
LaTeX's original definitions every time you end a block of code so that
LaTeX macros will still work -- otherwise you'll get very colorful
malfunctions.)


T

-- 
Talk is cheap. Whining is actually free. -- Lars Wirzenius

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sun, Jan 6, 2013 at 4:19 PM, H. S. Teoh <hsteoh quickfur.ath.cx> wrote:

 On Sun, Jan 06, 2013 at 10:44:27AM +0100, Philippe Sigaud wrote:
 Philippe, please share with me as soon as you have anything significant
 done in terms of LaTeX production so we don't overlap work.

 Nothing significant yet, that's my first dib into macro.
 I use these, but have a problem for code highlighting: DMD inserts macros
 to colour the code, these don't play well with my usual solutions

 (package
 pygmentize or package listings). The same for \verbatim{} instruction.
 Here, I just used a simple \texttt{} instruction, but in this case curly
 braces are lost :(

 LaTeX has its own syntactic conventions. Curly braces must be escaped
 with backslash, and certain operators (^ in particular, which also
 affects ^^) will cause syntax errors, because they are metacharacters
 with a different meaning. All of them need to be properly escaped.

Exactly.


 You may be able to use \begin{verbatim} and \end{verbatim} (which
 doesn't suffer from the trailing brace problem) but you can't use it for
 inline spans of text.

Damn right.

I'll try with the listings package, but I don't have much hope to achieve
what I want.

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.

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

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.

"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

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

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

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

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

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

Jordi Sayol <g.sayol yahoo.es> writes:

Al 07/01/13 20:19, En/na Andrei Alexandrescu ha escrit:
 On 1/7/13 10:23 AM, Andrei Alexandrescu wrote:
 On 1/7/13 9:30 AM, H. S. Teoh wrote:
 On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote:
 ??? I already have something in progress.

 [...]

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

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

 Andrei

 
 Heh, here's the first thing that I actually got to compile error-free from
spec.dd and lex.dd: http://erdani.com/d/dlangspec.pdf. Had to fudge a few
macros and some stuff doesn't expand to what it should, but from here the path
is relatively easy.
 
 Andrei
 

"htmldoc" converts html files into pdf, generating a toc.

In this sample I've removed original toc and "htmldoc" generated a toc with 2
levels.
http://d-packages.googlecode.com/files/dlangspec.pdf

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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

 Heh, here's the first thing that I actually got to compile error-free from
 spec.dd and lex.dd:
http://erdani.com/d/dlangspec.**pdf<http://erdani.com/d/dlangspec.pdf>.
 Had to fudge a few macros and some stuff doesn't expand to what it should,
 but from here the path is relatively easy.


I tried to find all the macros that created those ugly <a = href...
thingies before posting, but it looks like there are still some wandering
around :)

Philippe Sigaud <philippe.sigaud gmail.com> writes:

 "htmldoc" converts html files into pdf, generating a toc.

 In this sample I've removed original toc and "htmldoc" generated a toc
 with 2 levels.
 http://d-packages.googlecode.com/files/dlangspec.pdf

Nice looking doc.

Having 'dmd -D latex.ddoc spec.dd' generate that will be our first goal :)
(the second one would to get it as nice as TDPL)

Jordi Sayol <g.sayol yahoo.es> writes:

Al 07/01/13 20:19, En/na Andrei Alexandrescu ha escrit:
 On 1/7/13 10:23 AM, Andrei Alexandrescu wrote:
 On 1/7/13 9:30 AM, H. S. Teoh wrote:
 On Mon, Jan 07, 2013 at 02:35:09AM -0500, Andrei Alexandrescu wrote:
 ??? I already have something in progress.

 [...]

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

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

 Andrei

 
 Heh, here's the first thing that I actually got to compile error-free from
spec.dd and lex.dd: http://erdani.com/d/dlangspec.pdf. Had to fudge a few
macros and some stuff doesn't expand to what it should, but from here the path
is relatively easy.
 
 Andrei
 

wkhtmltopdf v0.11.0 (static)
https://code.google.com/p/wkhtmltopdf/

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

An example built in Linux 64-bit:
http://d-packages.googlecode.com/files/dlangspec-2.pdf

-- 
Jordi Sayol

"Era Scarecrow" <rtcvb32 yahoo.com> writes:

On Tuesday, 8 January 2013 at 03:45:36 UTC, Jordi Sayol wrote:
 wkhtmltopdf v0.11.0 (static)
 https://code.google.com/p/wkhtmltopdf/

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

 An example built in Linux 64-bit:
 http://d-packages.googlecode.com/files/dlangspec-2.pdf

  Glanced it over and it looks nice. :)

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Tue, Jan 8, 2013 at 5:02 AM, Era Scarecrow <rtcvb32 yahoo.com> wrote:

 On Tuesday, 8 January 2013 at 03:45:36 UTC, Jordi Sayol wrote:

 wkhtmltopdf v0.11.0 (static)
 https://code.google.com/p/**wkhtmltopdf/<https://code.google.com/p/wkhtmltopdf/>

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

 An example built in Linux 64-bit:
 http://d-packages.googlecode.**com/files/dlangspec-2.pdf<http://d-packages.googlecode.com/files/dlangspec-2.pdf>

  Glanced it over and it looks nice. :)

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

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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Mon, Jan 7, 2013 at 7:23 PM, Andrei Alexandrescu <
SeeWebsiteForEmail erdani.org> wrote:

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

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

 ??? I already have something in progress.

 [...]


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

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


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

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

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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sat, Jan 5, 2013 at 10:17 AM, Alex R=C3=B8nne Petersen <alex lycus.org> =
wrote:

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

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


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

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

"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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sat, Jan 5, 2013 at 7:12 PM, David Nadlinger <see klickverbot.at> wrote:

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

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

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



n
 converter. Something like Pandoc, but lighter.

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


In theory, yes.


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


I concur.

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

"Nicolas Sicard" <dransic gmail.com> writes:

On Saturday, 5 January 2013 at 08:59:32 UTC, Philippe Sigaud 
wrote:
From markdown, it can easily be translated into pdf, html, mobi 
or epub

 (heck, even docx)

 Philippe

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

Nicolas

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sat, Jan 5, 2013 at 10:33 AM, Nicolas Sicard <dransic gmail.com> wrote:

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

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

 (heck, even docx)

 Philippe

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


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

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

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

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Sat, Jan 5, 2013 at 3:42 PM, alex <info alexanderbothe.com> wrote:

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

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

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

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

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

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

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.

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

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

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?

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.

Walter Bright <newshound2 digitalmars.com> writes:

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

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

 So, this should:

 - take a .ddoc file for macro definition, or a [name, code] range of pairs.
 - read an input range
      - this range can be a standard D file, a .dd or whatever. That
 means parsing D comments...
 - find any macro definition
 - find any $(NAME Args,) call, expand it recursively. Repeat until
 nothing changes anymore. This should be done lazily (through the input
 range interface), in case the user want to stop before the end.
 - output the result as a range.

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

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

"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

-- 
Без труда не выловишь и рыбку из пруда. 

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.

"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

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.

Philippe Sigaud <philippe.sigaud gmail.com> writes:

On Wed, Jan 9, 2013 at 8:01 PM, Walter Bright
<newshound2 digitalmars.com> wrote:

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

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

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

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

filter out comments specifically: it simply iterate until it finds a
$( pattern.

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.

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

"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

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 `listings`as 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.

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

"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:

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

Thanks,

Andrei

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

[...]

Not bad.

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

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


T

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