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.
