On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote:
> On 12/15/15 9:01 PM, deadalnix wrote:
>> On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Also, ddoc always appeared to me like a big NIH syndrome.
>
> What would you have done instead?

While I like ddoc for inlined documentation, I believe that using a easy to learn, and well supported (in IDEs, editors, github, familiar to programmers coming from any other language background) format like Markdown is the way to go.

I'm very partial to using pandoc (http://pandoc.org/) as a universal processor for converting markdown to various output formats. Rust used pandoc as their processor till they wrote their own toolchain. (writing markdown parsers appears to be right of passage to some...).

Of course, there are multiple implementations of what "markdown", but http://commonmark.org/ is a step in the right direction (created by the author of Pandoc, with others).

On 17/12/15 3:23 AM, Pradeep Gowda wrote:
snip
> I'm very partial to using pandoc (http://pandoc.org/) as a universal
> processor for converting markdown to various output formats. Rust used
> pandoc as their processor till they wrote their own toolchain. (writing
> markdown parsers appears to be right of passage to some...).

I've considered writing a markdown parser for D.
Compliant with leanpub's Markua flavour.

Unfortunately without a good PDF library, its just not worth it for me.

On 12/16/2015 09:23 AM, Pradeep Gowda wrote:
> On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote:
>> On 12/15/15 9:01 PM, deadalnix wrote:
>>> On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Also, ddoc
>>> always appeared to me like a big NIH syndrome.
>>
>> What would you have done instead?
>
> While I like ddoc for inlined documentation, I believe that using a easy
> to learn, and well supported (in IDEs, editors, github, familiar to
> programmers coming from any other language background) format like
> Markdown is the way to go.
>
> I'm very partial to using pandoc (http://pandoc.org/) as a universal
> processor for converting markdown to various output formats. Rust used
> pandoc as their processor till they wrote their own toolchain. (writing
> markdown parsers appears to be right of passage to some...).
>
> Of course, there are multiple implementations of what "markdown", but
> http://commonmark.org/ is a step in the right direction (created by the
> author of Pandoc, with others).

I think Markdown postdates 2001. So at this point, would it be worth it switching over to Markdown? -- Andrei

On Wednesday, 16 December 2015 at 14:23:54 UTC, Pradeep Gowda wrote:
> I'm very partial to using pandoc (http://pandoc.org/) as a universal processor for converting markdown to various output formats. Rust used pandoc as their processor till they wrote their own toolchain. (writing markdown parsers appears to be right of passage to some...).

pandoc comes with an unbelievable amount of dependencies.

Notably the LaTeX dependency: on Mac the LaTeX distribution is a whopping 2gb download.

It seems nice in theory, but in practice pandoc takes things like \newpage (latex code fragments) in their Markdown input. And Markdown already accepts HTML tags! I much prefer DDoc.

On Wednesday, 16 December 2015 at 14:42:08 UTC, Andrei Alexandrescu wrote:
> I think Markdown postdates 2001. So at this point, would it be worth it switching over to Markdown? -- Andrei

I think this thread has gotten sidetracked: the question about the web site and the question of ddoc are separate things.

Regular ddoc's strength is its integration with D source files. But the web pages aren't D source files. They are stand-alone files that just happen to use ddoc. They could be changed to use something else very easily without changing ddoc at all.


On the topic of ddoc though, my worries with it aren't syntax related. I'm reasonably happy with the syntax right now. Cross-referencing, automatic linking, and tables of contents are the missing features if you ask me... and the major bug is that it honors conditional compilation, so building the docs on a Linux box can result in the Windows functions being left out of the generated page, and vice versa!

And you know, there, I think we are still better off enhancing what we have than throwing it out. Cross referencing for example, in the compiler, means it can automatically emit some kind of link with the full name of the symbol done with scope resolution.




So I ask everyone to please remember that we can change website .dd files to .whatever files without changing ddoc and let's not forget ddoc's already existing strengths and weaknesses when talking about changing it.

On Wednesday, 16 December 2015 at 13:49:22 UTC, Andrei Alexandrescu wrote:
>> One still most likely need to build the site, which is kind of a pain to
>> do.
>
> Building the site mimicks building dmd, druntime, and phobos. It's an invocation of make. What are the difficulties? -- Andrei

Building dmd, druntime, and phobos is a big pain in the butt too.

To check a change to the documentation right now, you first need to download and build git dmd (which depends on an existing dmd). Then druntime and phobos with it. Only then are you in a position to build the website since it depends on running the compiler over phobos which often depends on bleeding edge dmd.

Maybe that's easy if you're already running bleeding edge everything, but it is an awful lot of process when you just want to eyeball a quick visual change.

(and there's all the stuff about git branches being out of sync for me too because I'm a more casual contributor)

When I make doc changes, I tend to just do it blind on the website and hope it works because it isn't worth spending half an hour setting up just to paste in an example or something.


...and then the auto-tester is awfully whiny so the pull request needs more adjustment and I'm left dropping f-bombs and vowing to never try contributing to upstream D again.

On Wednesday, 16 December 2015 at 14:42:08 UTC, Andrei Alexandrescu wrote:
> I think Markdown postdates 2001. So at this point, would it be worth it switching over to Markdown? -- Andrei

Honestly, no. For three reasons

1. DDoc isn't hard. It took me all of ten minutes to understand it and make my first contribution to the website

2. Markdown is good for creating *simple* content. Once you need anything custom you start adding in your own things and you're right back where you started. This would become a problem with all of the extra macros that we have in the website (e.g. $(NOT_EBOOK)) which are needed in some pages. How would one represent $(NOT_EBOOK) in Markdown?

3. "Who wants to spend hours and hours of work writing a DDoc to Markdown converter or manually convert all existing pages? Do we have any volunteers?"

On 12/16/2015 10:13 AM, Adam D. Ruppe wrote:
> And you know, there, I think we are still better off enhancing what we
> have than throwing it out. Cross referencing for example, in the
> compiler, means it can automatically emit some kind of link with the
> full name of the symbol done with scope resolution.

I have a pretty cool idea on how to do cross referencing and other global things simply.

All we need is that ddoc generates plaintext wrapped in a macro. For example, consider the input:

====
This is a $(D ddoc) sentence with a lil $(B bold) in the mix.
====

Right now the generated output consists of the raw text interspersed with the expansion of the macros. What we need is this:

====
$(DDOC_RAWTEXT This is a )$(D ddoc)$(DDOC_RAWTEXT  sentence with a lil )$(B bold)$(DDOC_RAWTEXT  in the mix.)
====

Expansion would proceed normally. The default value is:

DDOC_RAWTEXT=$0

With this change to ddoc it becomes easy to define filters that eliminate all text and tags except those of interest. For example, generating a list of all URLs for verification purposes is trivial. Cross-referencing, glossary, etc. etc. become easy to automated.

Another cool project!


Andrei

On Wednesday, 16 December 2015 at 15:02:24 UTC, Guillaume Piolat wrote:
> On Wednesday, 16 December 2015 at 14:23:54 UTC, Pradeep Gowda wrote:
> pandoc comes with an unbelievable amount of dependencies.
>
> Notably the LaTeX dependency: on Mac the LaTeX distribution is a whopping 2gb download.
>
> It seems nice in theory, but in practice pandoc takes things like \newpage (latex code fragments) in their Markdown input. And Markdown already accepts HTML tags! I much prefer DDoc.

I use pandoc everyday.

This is provably false. You do not need LaTeX to use pandoc.
On linux and mac it's a self-contained binary. (I don't use windows, so i don't know).

This is how i use it everyday:

1. write markdown and convert to docx for sharing with coworkers. Not a single line of LaTeX
2. just finished writing a paper in IEEE format using just pandoc, which i converted to latex and yet did not have to use a single inline latex command in the main document.
2. write my website/notes in markdown and convert to HTML using hakyll which uses pandoc as a library. No Latex there either.

On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote:
>> Also, ddoc always appeared to me like a big NIH syndrome.
>
> What would you have done instead?
>

Honestly for D code itself, ddoc does just fine, but for the website, plain html or some known template format like . This is what people know.