On 09/16/2016 01:25 PM, bachmeier wrote:
> On Friday, 16 September 2016 at 16:03:44 UTC, Adam D. Ruppe wrote:
>
>> It isn't really a difficult process and it is only 62 lines of code in
>> my doc gen source. I don't do as much validation as Wikipedia but even
>> if it were to, it'd just be a larger source file, no real trouble for
>> the end user.
>>
>>
>> This isn't really a difficult problem!
>
> I think that's better as a third-party tool though. MathJax and KaTeX
> require no changes to the current workflow. You have to be able to build
> your documentation using DMD. If someone prefers images, they can run
> their .d file through your option, and be responsible for the additional
> setup.

Also, a bitmap image format that does not match article text in font size, does not usually have proper baseline alignment for inline math, is not as well anti-aliased as article text, can only be copied and pasted by right-clicking on the PNG and choosing "Information about image" and then selecting the "Associated text" to copy (in Firefox), and does not change color when part of a link. (https://en.wikipedia.org/wiki/Wikipedia:Rendering_math) -- Andrei

On Friday, 16 September 2016 at 17:25:10 UTC, bachmeier wrote:
> You have to be able to build your documentation using DMD.

eh, speak for yourself. Even Phobos is moving away from actually using dmd's doc generator!

On Friday, 16 September 2016 at 19:57:38 UTC, Adam D. Ruppe wrote:
> On Friday, 16 September 2016 at 17:25:10 UTC, bachmeier wrote:
>> You have to be able to build your documentation using DMD.
>
> eh, speak for yourself. Even Phobos is moving away from actually using dmd's doc generator!

The advantage of ddoc is generating documentation from that file with a single call to dmd. As soon as you add dependencies, you either have to include it with DMD or allow the documentation to break as soon as someone adds an equation. Neither is an option.

On Friday, 16 September 2016 at 19:57:38 UTC, Adam D. Ruppe wrote:
> On Friday, 16 September 2016 at 17:25:10 UTC, bachmeier wrote:
>> You have to be able to build your documentation using DMD.
>
> eh, speak for yourself. Even Phobos is moving away from actually using dmd's doc generator!

Bitter much? When you started Walter opined progress will soon stall and you will have an incomplete tool with no users to maintain. That is what happened. I appreciate your contributions to D and your overall decency as a human being. It makes it all the more surprising when you lose it all to stridently promote your tool and demean ddoc and ddox.

On Friday, 16 September 2016 at 18:30:25 UTC, Andrei Alexandrescu wrote:
> and does not change color when part of a link.

That's only partially true, image links traditionally got a colored border (such behavior is nowadays CSS defined and still fully possible) and there's other options too. Wikipedia might not color it, but we could.

> (https://en.wikipedia.org/wiki/Wikipedia:Rendering_math) --

But, while it is true that png output has its weaknesses, weaknesses of the alternatives include words like "not usable", "not supported", "not well formatted".

A png image isn't perfect for displaying this information, but it is the best realistic option... and really easy to implement with fallbacks to the other options.

On Friday, 16 September 2016 at 20:25:33 UTC, bachmeier wrote:
> The advantage of ddoc is generating documentation from that file with a single call to dmd.

dmd could just as well call executeShell as another program.

> dependencies, you either have to include it with DMD or allow the documentation to break as soon as someone adds an equation.

No, then it will just fallback to what it does today.

That is what my program already does: if latex isn't available (if the call to executeShell fails), it outputs the plain text, which can still be processed by Javascript if you wish. You've lost nothing by trying to produce the image and gained a lot of convenience for the author and usability for the reader if it does work. dmd can do exactly the same thing.

Y'all are letting the nonexistent perfect be the enemy of the easily implemented good.

On Friday, 16 September 2016 at 20:46:55 UTC, Tourist wrote:
> Bitter much?

It was decided some time ago that dlang.org would migrate to ddox. There was even a push by Andrei recently to hammer out some more of the ddox bugs to keep these plans on track, and he reported another just today.

Web traffic analysis also recently showed the ddox pages are significantly more popular than the ddoc pages. https://github.com/dlang/dlang.org/pull/1363#issuecomment-241770552

Even Walter this week considered changing the syntax and has said he changed his mind on Markdown! http://forum.dlang.org/post/nrh0bi$1elq$2@digitalmars.com


And finally, the Phobos doc generation process has used more than just dmd for a very long time anyway... in fact, it even already lists latex as an optional dependency!

https://github.com/dlang/dlang.org/blob/master/CONTRIBUTING.md


So it is simply objective fact that we don't have to be able to build the documentation using dmd, especially not dmd alone.

On Friday, 16 September 2016 at 21:02:26 UTC, Adam D. Ruppe wrote:
> On Friday, 16 September 2016 at 20:25:33 UTC, bachmeier wrote:
>> The advantage of ddoc is generating documentation from that file with a single call to dmd.
>
> dmd could just as well call executeShell as another program.
>
>> dependencies, you either have to include it with DMD or allow the documentation to break as soon as someone adds an equation.
>
> No, then it will just fallback to what it does today.
>
> That is what my program already does: if latex isn't available (if the call to executeShell fails), it outputs the plain text, which can still be processed by Javascript if you wish. You've lost nothing by trying to produce the image and gained a lot of convenience for the author and usability for the reader if it does work. dmd can do exactly the same thing.
>
> Y'all are letting the nonexistent perfect be the enemy of the easily implemented good.

But then you introduce other problems:

- Inconsistency in the output when you change machines or when you build someone else's program if only one has latex installed.
- Different latex configurations will give different output.
- All machines might have latex installed but not the right packages, or the package versions can be different.
- Not all of latex is supported by the Javascript implementations.

It would open a big can of worms to do this. I've run into so many problems trying to collaborate with coauthors using latex over the years. Rarely can you send a latex file to someone else and not run into issues. This is fine for a third-party tool but not for DMD.

On Friday, 16 September 2016 at 20:46:55 UTC, Tourist wrote:
> Bitter much? When you started Walter opined progress will soon stall and you will have an incomplete tool with no users to maintain. That is what happened.

Well, he's got at least one user. When I find the official docs too cluttered or difficult to understand due to a huge symbol dump on the page (such as with some of the docs in std.experimental.logging and elsewhere), I go to Adam's documentation which is usually much easier to read and understand. He can also respond to bug reports much faster as it's a one-person project and all it takes is an email. I found a bug in symbol searching awhile back and he had it fixed within an hour or so.