Fixed date to move to ddox for Phobos documentation

[Sönke Ludwig via Digitalmars-d]

Am 04.06.2016 um 19:01 schrieb Andrei Alexandrescu:
>
> I recall there were a few issues with ddox rendering up until relatively
> recently, have all been fixed?

I think they have. Vladimir has reported a bunch of them over time and 
all of those have been fixed.

> I don't see these options mutually exclusive, though I do want to make
> ddox the default/preferred rendering if ready. Consider e.g.
> https://www.gnu.org/software/make/manual/ which offers the documentation
> in various formats, including fewer/multiple pages.
>
> Now, I gave myself a few minutes to take a look at ddox:
>
> * http://dlang.org/phobos/ looks nicer than http://dlang.org/library/.
> The intro text is not very important, but the grouping is nice. The
> table vertical split ratio is also nicer.

This is currently just the generic module overview. We could simply 
replace it by a handcrafted version. Shall I copy the one from /phobos/? 
...or I could also just read the corresponding .ddoc file and render that.

> * I assume the dead links matter will be solved.
>
> * The cheat sheet made sense for the single-page docs but not for the
> new ones. Consider e.g.
> http://dlang.org/library/std/algorithm/comparison.html - it's two tables
> with the same row headings one after another. The information should be
> consolidated in one table (I'm speaking from the user's perspective; I
> know it's hard).

Leaving that to the other sub thread.

>
> * There are a few formatting issues that I like less in the new docs.
> These are of course fixable with relative ease. Looking at e.g.
> http://dlang.org/library/std/algorithm/comparison/among.html:
>
> ** the vertical spacing is generally too fluffy (do we really need 25%
> of the page occupied by Authors and License for _every_ function?)

I intended to tackle that multiple times. Definitely agreed that it 
should be much smaller. On the plus side, it's placed after all of the 
real meat of the page (except for the comments), so it doesn't really do 
any harm.

>
> ** Do we need the actual "Prototypes" heading or is it implicit?

That's definitely debatable. The first special purpose sections could be 
layed out in a few different ways:

	Primary heading

	brief description

	[prototypes]

	detailed description

	Parameters and other sections

or maybe

	Primary heading

	brief description
	detailed description

	[prototypes]
	[parameters]

or maybe

	Primary heading

	brief description

	[prototypes]
	[parameters]

	detailed description

They all have their pros and cons, and those also depend on what is 
displayed on the parent page. If, for example, the parent page already 
displays the prototypes (which I intended to add in some form), moving 
them further down below the page can make sense. Otherwise it can be 
good to have them near the top, so that the reader gets an early 
impression about the function, before reading through the detailed 
description.

> ** The booktable style is nice for tables that span the entire page
> width; for parameters the boxes at
> http://dlang.org/phobos/std_algorithm_comparison.html#among seem nicer
> to me.

While I don't particularly like those either (but I'll leave the design 
discussion to other people) - I can of course add that right away. I 
just used the default table style there and simply didn't notice the 
style change in /phobos/.

> ** Do we need the actual heading "Parameters", or it suffices to put
> "Parameter" instead of "Name" in the parameter box heading?

Depending on the general page layout we should definitely be able to 
drop the heading.

> ** Examples are nice but again vertical spacing overall and between
> consecutive examples is too large.

Partially agreed, the spacing could indeed be reduced a bit, however, 
one of the big advantages of the single-page layout is that we can use 
more vertical space to give the page more visual structure and thus make 
it easier to scan for a particular section.

> ** Generally the sentiment of the formatting is "too much foreplay". Get
> to the point already, don't have people scroll through fluff. Relegate
> Authors and License to a small footnote below everything - even after
> disqus.

Authors+License sure, but the rest is content, right? Or what else would 
you consider foreplay?

> * The hotlinks to parameters (e.g. "value", "values") seem unnecessary
> unless the synopsis is very long which shouldn't be the case. It's also
> inconsistent - pred is not hotlinked.

You are probably right. Linking to template arguments is currently not 
supported, so dropping parameter linking in general is definitely the 
more comfortable change ;-)

> * How are we going to deal with links (possibly with hashes) pointing to
> the existing artifacts? Again the simplest way is to keep the old docs
> but just deemphasize them on dlang.org.

Ideally we'd set up redirection rules to forward to the new pages, but 
page anchors will be problematic. One idea to solve that would be, 
instead of defining server-side redirection rules, to put some 
JavaScript code inside of the original /phobos/ docs that detects the 
active page anchor and redirects to the proper /library/ sub page.

> * I'd like a "Show entire module documentation as single page" link for
> e.g. http://dlang.org/library/std/algorithm/comparison.html.

So, conceptually a link to /phobos/? What's the motivation for that? Can 
we solve that by adding more information to the module page, possibly 
with a button to show that on-demand?

> * How do we address the ebook/pdf production? Do we continue using ddoc
> or look into a ddox approach?

I'd say we stay with pure Ddoc as long as that is sufficient. It may get 
interesting depending on which way we go with the cheatsheets/overview 
tables.

> * Any other extant issues with /library/ (I recall there were a few
> cases in which not all text was rendered)?

As stated, I think all of the known DDOX/dpl-docs related issues have 
been solved. However, there are still some issues with the JSON output 
of DMD (alias names are not preserved, no documentation inside of 
`static if` and some others). DDOX also has a doc parser based on 
libdparse, which could be a good alternative to work around that. I'll 
have a look at that.

BTW, thanks for taking the time to write this down (again)! I think this 
has also been one of the main issues in the process that there was 
generally very few feedback, I guess mostly because /library/ was quite 
hidden in the "resources" section.

What I think we should do with these issues is to put them into two 
categories: Needs to be solved _before_ or can be solved _after_ the 
switch. Especially those that are present in /phobos/ now are candidates 
for the latter category.