[Swift-devel] documentation formatting

[Mihael Hategan]

On Sun, 2015-03-29 at 20:15 -0500, Michael Wilde wrote:
> Nice!  I like it. :)
> 
> Is it generated from the AsciiDoc source in an automated (or automatable)
> manner?

Yes. It's the existing asciidoc stuff with some additional stylesheets
and some javascript. It's compiled the exact same way as our current
docs are.

> 
> A few thoughts:
> 
> - would be great if the left column menu was a collapsable/expandable
> outline (eventually)

I agree.

> 
> - would be better if the right side was in the current single-doc format,
> at least while its of manageable size.  Makes it easier to search.

We could have a search function. It is actually one html page. The
swapping of sections is done in javascript.

> 
> - scroll behavior is a bit odd: when the left menu hits the top or bottom,
> the right-column text start scrolling. That might be desirable, not sure.
> But it felt a tad strange.

What browser? I don't think I've seen that.

> 
> Regardless, I think this is great and a nice improvement in readability.
> Thanks for suggesting it and doing it.
> 
> We should discuss whats needed to make this the new live format - or at
> least an optional link users can select on the doc page (e.g., "New indexed
> User Guide")

It's one commit away really, but we should probably do this in a branch
as part of 0.97 documentation efforts.

Mihael