View mode: basic / threaded / horizontal-split · Log in · Help
January 05, 2013
Re: dlangspec.pdf?
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.
January 05, 2013
Re: dlangspec.pdf?
On Sat, Jan 5, 2013 at 10:17 AM, Alex Rønne 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.
January 05, 2013
Re: dlangspec.pdf?
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)
January 05, 2013
Re: dlangspec.pdf?
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.
January 05, 2013
Re: dlangspec.pdf?
On Sat, Jan 5, 2013 at 2:13 PM, Andrei Alexandrescu <
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.

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.
January 05, 2013
Re: dlangspec.pdf?
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?
January 05, 2013
Re: dlangspec.pdf?
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
January 05, 2013
Re: dlangspec.pdf?
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 <-> Markdown
>>> 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 – 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.
January 05, 2013
Re: dlangspec.pdf?
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
January 05, 2013
Re: dlangspec.pdf?
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
1 2 3 4 5 6
Top | Discussion index | About this forum | D home