some restructuring

[pkra]

I finally figured out how to redirect latest to any branch (dark and hidden corner of the readthedocs dashboard...).

This means we can get rid of the complications of keeping the latest version branch in sync with master -- we'll configure readthedocs to present 2.3-latest at latest (and part of the release process will be to switch this at readthedocs).

For the above, we should get rid of the version warning for the latest version. But we may as well do that in general since we include canonical links to latest now which has cleared up the page rank (no more people coming from Google to the wrong version). (And while we're at it, we could switch to the new readthdocs theme.)

[dpvc]

That all sounds good. Do you need me to do anything about this, or are you planning to make the changes?

[pkra]

Ok, it's settled then. I'll do it when I find some time to spare.

[pkra]

I've created a test branch with the new RTD theme at http://docs.mathjax.org/en/new_theme/index.html

Looking good to me.

[pkra]

It turns out I misunderstood the redirecting part.

What we can do is have docs.mathjax.org redirect to any version/branch we want. That leaves the question what to do with latest. We could stop building latest entirely but that would bring back the problem we solved with canonical links to latest -- page rank of some specific version will dominate.

So I would propose to leave the branches and RTD setup as they are. Switching back to theme = default will at least simplify the merging of latest and N.m-latest which triggered this issue...

[pkra]

For a live built see http://pkra-mathjax-docs.readthedocs.org/en/latest/

[pkra]

@dpvc can you review these? Then I can start working on the docs for 2.4

[dpvc]

it looks good overall. But there are two things that bother me. First, in the left-hand sidebar, all the links from the home page appear, but not separated into their categories. I think it is hard to read these without the separations by heading that is part of the home page. I'm not sure you can do anything about it or not.

The other thing is that the alphabetical list of LaTeX commands doesn't format well (for me in Safari) due to the bold monospaced font. Apparently the bolding is being done algorithmically rather than via an actual font, and that makes it no longer monospaced, so the second column does not align. Perhaps there is a better way to handle that?

[pkra]

Ok, I'll look into these. (When we spoke, I thought you meant the rendering of :: describe blocks which are used for TeX examples like \bbox[options]{math}).

I'll look into the sidebar and TeX-command list thing.

[dpvc]

No, I just meant the alphabetical listing, which has a second column that indicates the extension to load for that command. The second column is not aligning properly for me.

Davide

On May 8, 2014, at 12:55 PM, Peter Krautzberger wrote:

Ok, I'll look into these. (When we spoke, I thought you meant the rendering of :: describe blocks which are used for TeX examples like \bbox[options]{math}).

I'll look into the sidebar and TeX-command list thing.

—
Reply to this email directly or view it on GitHub.

[pkra]

Hm. I think I see that. Do you mean all the bracketed ones? I think the problem with those is in the source.

[dpvc]

No, what I mean is this:

You may not see it, because I think it is font dependent. The font-family is set to "Incosolata","Consolata","Monaco",monospace, and I don't have the first two, so am getting Monaco. This does not have a bold variant, so the bold is generated algorithmically (by adding a shifted version of the original -- poor-man's-bold). That means that the width is not the same as the unbold Monaco, and so the longer control sequences take more pixels than the shorter ones, and so the spacing of the second column is off. Admittedly, that is an error in Safari's rendering, but I'm not sure the bold is worth it. I also checked with Firefox, and it has a similar issue.

[dpvc]

PS, the bracketed ones are supposed to be one character to the left, so the extension name is the alignment point.

[pkra]

Ah, ok. I don't see that on my system. I'll create an issue.

[pkra]

Would you be ok with merging this for the time being? Or would you consider those two issues as blocking?

[dpvc]

Sure, go ahead. The sidebar is the one that bothers me the most, and I hope it can be improved in the future.