Fixed date to move to ddox for Phobos documentation

Andrei Alexandrescu via Digitalmars-d digitalmars-d at puremagic.com
Sat Jun 4 10:01:24 PDT 2016


On 06/04/2016 12:10 PM, Seb wrote:
> More than two and half years ago, Sönke added ddox builds for the Phobos
> documentation. We all know that there are many reasons for ddox - being
> able to generate single pages for methods is just one, it also
> eliminates all the JavaScript hacks (e.g. the quickindex menu, anchors,
> ...) that we have added over time to deal with the shortcomings of ddoc.
>
> This post originates from a recent discussion [2] that showed the higher
> ranking of the ddox pages in search engines because of those single
> pages, more static content and meta information.
>
> To quote Adam [3]:
>
>> ddox got a decent go up to here.
>> But then we need to decide what's next - a clear goal, including a due
>> date, gets us all aligned and removes a lot of the uncertainty on the
>> author's side; it is some reassurance that they aren't wasting their
>> time, and encourages outside teams to get onboard.
>
> We got the MREF change into Phobos a month ago and Sönke has fixed the
> last blocking bug with ddox (broken source code links) a couple of days
> ago.
>
> Imho it's quite impressive that he still pushes the project and as Adam
> correctly said - we need to make a decision and have a clear deadline
> like 2.072 will be the last documentation build with ddoc, once it's
> released we will remove the ddoc Phobos build and make ddox (/library)
> the standard (with redirect, of course). This gives us also two to three
> months to test it properly again (it has been tested now for 2.5
> years!!) and resolve issues if occurring.
>
> Does this sound reasonable to everyone?
>
> [1] https://github.com/dlang/dlang.org/pull/267
> [2] http://forum.dlang.org/post/575079DE.2040508@erdani.org
> [3] http://forum.dlang.org/post/zuzlvgqposlmtgdnxhmb@forum.dlang.org

I recall there were a few issues with ddox rendering up until relatively 
recently, have all 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.

* 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).

* 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?)

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

** 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.

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

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

** 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.

* 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.

* 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.

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

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

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


Andrei



More information about the Digitalmars-d mailing list