Can we produce formulas, or latex in ddoc? Are there any examples in phobos I can refer to?

On 9/14/16 1:50 AM, Manu via Digitalmars-d wrote:
> Can we produce formulas, or latex in ddoc? Are there any examples in
> phobos I can refer to?

https://github.com/dlang/dlang.org/blob/master/latex.ddoc

That's the macros file for generating the language spec in LaTeX format.


Andrei

On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 9/14/16 1:50 AM, Manu via Digitalmars-d wrote:
>>
>> Can we produce formulas, or latex in ddoc? Are there any examples in phobos I can refer to?
>
>
> https://github.com/dlang/dlang.org/blob/master/latex.ddoc
>
> That's the macros file for generating the language spec in LaTeX format.

Ah, wow, yeah I actually saw this when I googled for it before posting here.

I'm just gonna come out and say that I really don't feel like taking
the few hours it might take me to try and understand what's going on
here. I really have better things to do...
Considering I don't really know latex either, I just have to wing
that, this is like 721 lines of tedious double-indirection, with no
examples in sight ;) (yet I'm being hassled about lack of examples!)

I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a
lot better :/
I'm struggling to produce docs I'm happy with. Formatting is hard,
macros for everything really sucks!

On Wednesday, 14 September 2016 at 13:38:21 UTC, Manu wrote:
>
> I'm just gonna come out and say that I really don't feel like taking
> the few hours it might take me to try and understand what's going on
> here. I really have better things to do...
> Considering I don't really know latex either, I just have to wing
> that, this is like 721 lines of tedious double-indirection, with no
> examples in sight ;) (yet I'm being hassled about lack of examples!)
>

I learned Latex by playing with LyX. You can get things looking how you want pretty easily. When you copy some code from LyX and paste it somewhere else, the output is the Latex code you need. I do this somewhat frequently because the only Latex I remember is things like subscripts and superscripts.

On Wednesday, 14 September 2016 at 13:38:21 UTC, Manu wrote:
> On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
>> On 9/14/16 1:50 AM, Manu via Digitalmars-d wrote:
>>>
>>> Can we produce formulas, or latex in ddoc? Are there any examples in phobos I can refer to?
>>
>>
>> https://github.com/dlang/dlang.org/blob/master/latex.ddoc
>>
>> That's the macros file for generating the language spec in LaTeX format.
>
> Ah, wow, yeah I actually saw this when I googled for it before posting here.
>
> I'm just gonna come out and say that I really don't feel like taking
> the few hours it might take me to try and understand what's going on
> here. I really have better things to do...
> Considering I don't really know latex either, I just have to wing
> that, this is like 721 lines of tedious double-indirection, with no
> examples in sight ;) (yet I'm being hassled about lack of examples!)
>
> I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a
> lot better :/
> I'm struggling to produce docs I'm happy with. Formatting is hard,
> macros for everything really sucks!

I agree. That's why I quickly gave up on ddoc. The macro system needs to be better designed and documented if that's the route you're going to choose.

That said, if all you want to do is insert equations in the finished documentation, can't you do a simple text substitution on the ddoc output file? I needed equations so I did that when I started. It was a D script with only a few lines of code.

On 09/14/2016 09:38 AM, Manu via Digitalmars-d wrote:
> On 14 September 2016 at 21:36, Andrei Alexandrescu via Digitalmars-d
> <digitalmars-d@puremagic.com> wrote:
>> On 9/14/16 1:50 AM, Manu via Digitalmars-d wrote:
>>>
>>> Can we produce formulas, or latex in ddoc? Are there any examples in
>>> phobos I can refer to?
>>
>>
>> https://github.com/dlang/dlang.org/blob/master/latex.ddoc
>>
>> That's the macros file for generating the language spec in LaTeX format.
>
> Ah, wow, yeah I actually saw this when I googled for it before posting here.
>
> I'm just gonna come out and say that I really don't feel like taking
> the few hours it might take me to try and understand what's going on
> here. I really have better things to do...
> Considering I don't really know latex either, I just have to wing
> that, this is like 721 lines of tedious double-indirection, with no
> examples in sight ;) (yet I'm being hassled about lack of examples!)

Generally speaking it's difficult to produce good latex documents without knowing latex, so it may be the case a latex crash course is needed or the task is ill-defined.

That said, the stuff I published at http://erdani.com/d/DIP1000-grammar.html and http://erdani.com/d/DIP1000-typing-baseline.html use MathJAX, you may want to take a look. Truth be told that's generated code (using a much smaller ddoc source).

> I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a
> lot better :/
> I'm struggling to produce docs I'm happy with. Formatting is hard,
> macros for everything really sucks!

Why?


Andrei

On 2016-09-14 15:38, Manu via Digitalmars-d wrote:

> I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a
> lot better :/
> I'm struggling to produce docs I'm happy with. Formatting is hard,
> macros for everything really sucks!

For reference: http://forum.dlang.org/post/nrdgl0$2p21$1@digitalmars.com

-- 
/Jacob Carlborg

On Wednesday, 14 September 2016 at 11:36:11 UTC, Andrei Alexandrescu wrote:
> On 9/14/16 1:50 AM, Manu via Digitalmars-d wrote:
>> Can we produce formulas, or latex in ddoc? Are there any examples in
>> phobos I can refer to?
>
> https://github.com/dlang/dlang.org/blob/master/latex.ddoc
>
> That's the macros file for generating the language spec in LaTeX format.

I think what the man is asking for is a way to write formulas in DDoc, regardless of output format. Foremost, the math should display well on dlang.org.

If you look at https://dlang.org/phobos/std_mathspecial.html#.gamma, there is some math there. But then if you look at the DDoc source, https://github.com/dlang/phobos/blob/master/std/mathspecial.d, it's pretty terrible how to get it done, and it is very limited (how would you get "sqrt(x+y)" to display well, or probably what Manu wants, how to get matrix math to display well?).

A great addition to DDoc would be to allow LaTeX bits, like doxygen does, and render it nicely for both web and PDF output. You just mark a piece of text as <LatexStartsHere>....<LatexOut>.

On Wednesday, 14 September 2016 at 13:38:21 UTC, Manu wrote:
>
> I'm kinda feeling ddoc is fairy serious problem. Doxygen is like... a lot better :/

Definitely :/

-Johan

On Wednesday, 14 September 2016 at 13:56:26 UTC, jmh530 wrote:

> I learned Latex by playing with LyX. You can get things looking how you want pretty easily. When you copy some code from LyX and paste it somewhere else, the output is the Latex code you need. I do this somewhat frequently because the only Latex I remember is things like subscripts and superscripts.

Yes, Lyx is nice and easy.
If you only want to write some heavy formulas, use Lyx.
It will put out the proper Latex, and that can be easy integrated in DDox

On 15 September 2016 at 19:50, Johan Engelen via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On Wednesday, 14 September 2016 at 11:36:11 UTC, Andrei Alexandrescu wrote:
>>
>> On 9/14/16 1:50 AM, Manu via Digitalmars-d wrote:
>>>
>>> Can we produce formulas, or latex in ddoc? Are there any examples in phobos I can refer to?
>>
>>
>> https://github.com/dlang/dlang.org/blob/master/latex.ddoc
>>
>> That's the macros file for generating the language spec in LaTeX format.
>
>
> I think what the man is asking for is a way to write formulas in DDoc, regardless of output format. Foremost, the math should display well on dlang.org.
>
> If you look at https://dlang.org/phobos/std_mathspecial.html#.gamma, there is some math there. But then if you look at the DDoc source, https://github.com/dlang/phobos/blob/master/std/mathspecial.d, it's pretty terrible how to get it done, and it is very limited (how would you get "sqrt(x+y)" to display well, or probably what Manu wants, how to get matrix math to display well?).
>
> A great addition to DDoc would be to allow LaTeX bits, like doxygen does, and render it nicely for both web and PDF output. You just mark a piece of text as <LatexStartsHere>....<LatexOut>.

Right, thank you.