www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Our docs should be more beautiful

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
I was proofreading 
http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experime
tal_checkedint.html 
and there are a few ways in which our docs could look better.

* My pet dream was to work on a project with a beautiful justified and 
hyphenated website. After endless debates, ugliness has won - I'm 
looking at a eye-scratching ragged right edge.

* The constraint on "struct Checked" is not formatted the same as the 
other constraints.

* Vertical spacing is just too fluffy. Looking e.g. at the docs for 
"Payload" and "hook" - each has a short description. The vspace between 
definition and description is too tall. The vspace between the 
description and the next definition is too tall. The grayed space within 
which the definition itself sits has too large up and bottom margins. 
The vspace above "Jump to:" is too high. Literally all vertical spacing 
is larger than it should be.

* The red vertical line on the left of each definition is meh. There's a 
bit more sense for struct definitions because of the "Jump to:" real 
estate. But for each little one-line definition, the red bar is just 
odd. Also, there is no change in color as indentation goes in (which 
would be a useful cue for long struct definitions).

* I don't see a point to the boxes within which each definition + its 
comments sits. Then there's one more box for the example! Boxes, boxes 
everywhere, and nary a drop to drink. They'd make sense e.g. if one 
could collapse a box. As such - hey, they just add more vspace :o).

* The vspace between the ditto'ed definitions "enum auto min;" and "enum 
auto max;" is again too large.

* The grayed out constraints are also indented horizontally - by a lot. 
If they're already distinguished by color, no need to indent them. Oh, 
then I saw if you hover you see "Constraints: " written in the space 
that seem to be indentation. Could we format that in non-code font at least?

* Spacing between doc paragraphs (see e.g. doc of opCast) seems to be 
80% line height. Should be 50%.

* The enumerated items (see doc of opChecked) seem to be the only 
artifact that's properly spaced vertically. I guess nobody discovered 
them so they're at the system default.

* "0 Contributors" should not be displayed at the bottom if there are no 
contributors. But I assume that's only the case before the pull is merged?


Andrei
Jul 18 2016
next sibling parent reply Jack Stouffer <jack jackstouffer.com> writes:
On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
wrote:
 * My pet dream was to work on a project with a beautiful 
 justified and hyphenated website. After endless debates, 
 ugliness has won - I'm looking at a eye-scratching ragged right 
 edge.
Please, no more debates on this. The web's typographic code is not good enough yet and it looks terrible. Also, bad justified text is a nightmare for people with Dyslexia. My dyslexic friend has many custom styles for sites with justified text just so he can read without a headache.
 * The constraint on "struct Checked" is not formatted the same 
 as the other constraints.
This is a bug. File a report :-) ?
 * The grayed out constraints are also indented horizontally - 
 by a lot. If they're already distinguished by color, no need to 
 indent them. Oh, then I saw if you hover you see "Constraints: 
 " written in the space that seem to be indentation. Could we 
 format that in non-code font at least?
I rather like the indentation. Let's me reduce things that need to be processed visually easily.
 * "0 Contributors" should not be displayed at the bottom if 
 there are no contributors. But I assume that's only the case 
 before the pull is merged?
Yeah, should be one when it's merged.
Jul 18 2016
parent Seb <seb wilzba.ch> writes:
On Monday, 18 July 2016 at 16:18:27 UTC, Jack Stouffer wrote:
 On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
 wrote:
 * "0 Contributors" should not be displayed at the bottom if 
 there are no contributors. But I assume that's only the case 
 before the pull is merged?
Yeah, should be one when it's merged.
Yes. However a PR for this AutoTester edge case has already been submitted ;-) https://github.com/dlang/dlang.org/pull/1431
Jul 18 2016
prev sibling next sibling parent reply Kagamin <spam here.lot> writes:
Do we see the same thing? I see ugly justified hyphenated text 
https://abload.de/img/tmpr5ow8.png
Jul 18 2016
next sibling parent Lodovico Giaretta <lodovico giaretart.net> writes:
On Monday, 18 July 2016 at 17:09:57 UTC, Kagamin wrote:
 Do we see the same thing? I see ugly justified hyphenated text 
 https://abload.de/img/tmpr5ow8.png
It probably depends on the browser. Mine shows the text not justified, and it does not try to break words (while your does). Probably, the CSS does not explicitly state what to do, so the browser applies its own default, which is different between you and me (and Andrei).
Jul 18 2016
prev sibling parent Brad Anderson <eco gnuk.net> writes:
On Monday, 18 July 2016 at 17:09:57 UTC, Kagamin wrote:
 Do we see the same thing? I see ugly justified hyphenated text 
 https://abload.de/img/tmpr5ow8.png
It's hyphenated on browsers that support it. The chrome team is very close to supporting hyphenation so it'll soon be justified in all the major browsers (I think they are just trying to decide what to do on desktops browsers that don't have a system-wide hyphenation dictionary).
Jul 18 2016
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2016-07-18 17:56, Andrei Alexandrescu wrote:

 * My pet dream was to work on a project with a beautiful justified and
 hyphenated website.
I hate when words are split between rows. -- /Jacob Carlborg
Jul 18 2016
prev sibling next sibling parent qznc <qznc web.de> writes:
On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
wrote:
 I was proofreading 
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experime
tal_checkedint.html and there are a few ways in which our docs could look
better.

 * My pet dream was to work on a project with a beautiful 
 justified and hyphenated website. After endless debates, 
 ugliness has won - I'm looking at a eye-scratching ragged right 
 edge.
The "ragged" left is more ugly. If you want a be beautiful, the left side should align, but every text is indented differently due to boxes/lines.
 Literally all vertical spacing is larger than it should be.
I would disagree, but at this level it is bike shedding. There should be more vertical space. For example, I would increase the line height a little and the lines are too wide. Does it make sense to work on this soon-to-be-replaced styling?
Jul 18 2016
prev sibling next sibling parent reply bitwise <bitwise.pvt gmail.com> writes:
On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
wrote:
 I was proofreading 
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experime
tal_checkedint.html and there are a few ways in which our docs could look
better.

 * My pet dream was to work on a project with a beautiful 
 justified and hyphenated website. After endless debates, 
 ugliness has won - I'm looking at a eye-scratching ragged right 
 edge.

 * The constraint on "struct Checked" is not formatted the same 
 as the other constraints.

 * Vertical spacing is just too fluffy. Looking e.g. at the docs 
 for "Payload" and "hook" - each has a short description. The 
 vspace between definition and description is too tall. The 
 vspace between the description and the next definition is too 
 tall. The grayed space within which the definition itself sits 
 has too large up and bottom margins. The vspace above "Jump 
 to:" is too high. Literally all vertical spacing is larger than 
 it should be.

 * The red vertical line on the left of each definition is meh. 
 There's a bit more sense for struct definitions because of the 
 "Jump to:" real estate. But for each little one-line 
 definition, the red bar is just odd. Also, there is no change 
 in color as indentation goes in (which would be a useful cue 
 for long struct definitions).

 * I don't see a point to the boxes within which each definition 
 + its comments sits. Then there's one more box for the example! 
 Boxes, boxes everywhere, and nary a drop to drink. They'd make 
 sense e.g. if one could collapse a box. As such - hey, they 
 just add more vspace :o).

 * The vspace between the ditto'ed definitions "enum auto min;" 
 and "enum auto max;" is again too large.

 * The grayed out constraints are also indented horizontally - 
 by a lot. If they're already distinguished by color, no need to 
 indent them. Oh, then I saw if you hover you see "Constraints: 
 " written in the space that seem to be indentation. Could we 
 format that in non-code font at least?

 * Spacing between doc paragraphs (see e.g. doc of opCast) seems 
 to be 80% line height. Should be 50%.

 * The enumerated items (see doc of opChecked) seem to be the 
 only artifact that's properly spaced vertically. I guess nobody 
 discovered them so they're at the system default.

 * "0 Contributors" should not be displayed at the bottom if 
 there are no contributors. But I assume that's only the case 
 before the pull is merged?


 Andrei
Any chance of getting one definition or overload-set per page? I've never liked the way that each module, in it's entirety, is all dumped into a single page. Finding what you're looking for is often difficult among all the noise. It's also very easy to scroll past what you're looking for. If each definition or overload-set had it's own page, issues like vertical spacing would be at least, tolerable. Example: https://msdn.microsoft.com/en-us/library/bb354760(v=vs.100).aspx On the left, is all overloads of Enumerable.Average. The full path of whatever nested scope you're in is listed along the top. If you navigate back(up one scope level), you'll see the module/namespace's contents grouped by type(method, property, etc..), and each one has nothing more than a short summary of what it does. imo, the 1 module-per-page setup is a bit of a no-win situation. Bit
Jul 18 2016
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 18 July 2016 at 22:13:35 UTC, bitwise wrote:
 Any chance of getting one definition or overload-set per page?
Both the ddox pages at /library and my pages at dpldocs.info do it this way. The ddox ones are supposed to be made default eventually. http://dlang.org/phobos/std_algorithm_searching.html#.balancedParens vs http://dlang.org/library/std/algorithm/searching/balanced_parens.html vs http://dpldocs.info/experimental-docs/std.algorithm.searching.balancedParens.html
Jul 18 2016
next sibling parent bitwise <bitwise.pvt gmail.com> writes:
On Monday, 18 July 2016 at 22:24:09 UTC, Adam D. Ruppe wrote:
 On Monday, 18 July 2016 at 22:13:35 UTC, bitwise wrote:
 Any chance of getting one definition or overload-set per page?
Both the ddox pages at /library and my pages at dpldocs.info do it this way. The ddox ones are supposed to be made default eventually. http://dlang.org/phobos/std_algorithm_searching.html#.balancedParens vs http://dlang.org/library/std/algorithm/searching/balanced_parens.html vs http://dpldocs.info/experimental-docs/std.algorithm.searching.balancedParens.html
Ok, so I'm a little late to the party as usual ;) This one is pretty much what I'm talking about, except for a few things: http://dlang.org/library/std/algorithm/searching.html 1) The page heading is confusing. I would either remove "Module", "Template", etc completely, or put them on their own line: current: Module std.algorithm.searching to: std.algorithm.searching Module or(like dpldocs): std.algorithm.searching 2) I much prefer the navigation structure of the dpldocs as well, in that it only shows the parent scope of whatever you're looking at instead of the current tree structure. At most, I would prefer two levels maximum. Also, I like that top level packages like (std) have a standard looking page like their inner modules(http://dpldocs.info/experimental-docs/std.html). I think having the entire hierarchy look standard from root to leaf is important. 3) I like the fonts better on the dpldocs, but I think I prefer the current color scheme. It would be nice to see these changes merged into the beta library reference. Thanks, Bit
Jul 18 2016
prev sibling parent qznc <qznc web.de> writes:
On Monday, 18 July 2016 at 22:24:09 UTC, Adam D. Ruppe wrote:
 The ddox ones are supposed to be made default eventually.
What is the state on this? I found no issue tracking this.
Jul 19 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 07/18/2016 06:13 PM, bitwise wrote:
 Any chance of getting one definition or overload-set per page?
Been like that for a while, my comments refer to the old styling. -- Andrei
Jul 18 2016
parent reply bitwise <bitwise.pvt gmail.com> writes:
On Tuesday, 19 July 2016 at 01:37:20 UTC, Andrei Alexandrescu 
wrote:
 On 07/18/2016 06:13 PM, bitwise wrote:
 Any chance of getting one definition or overload-set per page?
Been like that for a while, my comments refer to the old styling. -- Andrei
Why talk about the old style though? I don't see any of the problems you've mentioned in the new beta docs http://dlang.org/library/std/algorithm/searching/balanced_parens.html Bit
Jul 19 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 7/19/16 12:39 PM, bitwise wrote:
 On Tuesday, 19 July 2016 at 01:37:20 UTC, Andrei Alexandrescu wrote:
 On 07/18/2016 06:13 PM, bitwise wrote:
 Any chance of getting one definition or overload-set per page?
Been like that for a while, my comments refer to the old styling. -- Andrei
Why talk about the old style though? I don't see any of the problems you've mentioned in the new beta docs http://dlang.org/library/std/algorithm/searching/balanced_parens.html Bit
The two coexist. -- Andrei
Jul 19 2016
parent bitwise <bitwise.pvt gmail.com> writes:
On Tuesday, 19 July 2016 at 17:02:34 UTC, Andrei Alexandrescu 
wrote:
 On 7/19/16 12:39 PM, bitwise wrote:
 On Tuesday, 19 July 2016 at 01:37:20 UTC, Andrei Alexandrescu 
 wrote:
 On 07/18/2016 06:13 PM, bitwise wrote:
 Any chance of getting one definition or overload-set per 
 page?
Been like that for a while, my comments refer to the old styling. -- Andrei
Why talk about the old style though? I don't see any of the problems you've mentioned in the new beta docs http://dlang.org/library/std/algorithm/searching/balanced_parens.html Bit
The two coexist. -- Andrei
Ok, I was under the impression the old ones would eventually be removed. Thanks, Bit
Jul 19 2016
prev sibling next sibling parent reply Mattcoder <no spam.com> writes:
On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
wrote:
 I was proofreading 
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experime
tal_checkedint.html and there are a few ways in which our docs could look
better.

 ...
Look over this: changed(left) and the old(right) versions, what you think? http://i.imgur.com/UTLpK42.png PS: Click to see the full image. Mattcoder.
Jul 18 2016
next sibling parent Mattcoder <no spam.com> writes:
On Monday, 18 July 2016 at 22:16:45 UTC, Mattcoder wrote:
 On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
 wrote:
 I was proofreading 
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experime
tal_checkedint.html and there are a few ways in which our docs could look
better.

 ...
Look over this: changed(left) and the old(right) versions, what you think? http://i.imgur.com/UTLpK42.png PS: Click to see the full image. Mattcoder.
Oh and by the way, we should use something like google page insights or alternatives, because it usually show good points. For example the space between the links, it's frustrating when browsing using mobile and you click on a link and opens the other link. Google page insights: https://developers.google.com/speed/pagespeed/insights/?url=http%3A%2F%2Fdtest.thecybershadow.net%2Fartifact%2Fwebsite-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564%2Fweb%2Fphobos-prerelease%2Fstd_experimental_checkedint.html&tab=mobile Mattcoder.
Jul 18 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 07/18/2016 06:16 PM, Mattcoder wrote:
 On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu wrote:
 I was proofreading
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experimental_checkedint.html
 and there are a few ways in which our docs could look better.

 ...
Look over this: changed(left) and the old(right) versions, what you think? http://i.imgur.com/UTLpK42.png PS: Click to see the full image.
I like the styling on the right - the vertical spacing between paragraph is ridiculous in the left version, and the "Jump to:" box is too tall. -- Andrei
Jul 18 2016
parent Mattcoder <stop spam.com> writes:
On Tuesday, 19 July 2016 at 01:38:54 UTC, Andrei Alexandrescu 
wrote:
 ...

 http://i.imgur.com/UTLpK42.png

 PS: Click to see the full image.
I like the styling on the right - the vertical spacing between paragraph is ridiculous in the left version, and the "Jump to:" box is too tall. -- Andrei
This is why I don't go through this and help on this matter, I mean the layout is too subjective, I think the left version (Which was changed by my friend) is much better to read than the version on the right. Another thing: using "font-weight" or "bold" sometimes looks weird on high resolutions, which was avoided on the left, maybe is not too visible here but anyway... And finally: Keep in mind that some folks (like myself) use Tablet to read manuals, and the font size matters a lot on tiny screens. By the way, this is not a rant, :) I'm just saying that making layout for others is something that I don't like because the different tastes. Mattcoder.
Jul 19 2016
prev sibling next sibling parent reply Carl Vogel <carljv gmail.com> writes:
On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
wrote:
 I was proofreading 
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experime
tal_checkedint.html and there are a few ways in which our docs could look
better.

 * My pet dream was to work on a project with a beautiful 
 justified and hyphenated website. After endless debates, 
 ugliness has won - I'm looking at a eye-scratching ragged right 
 edge.

 * The constraint on "struct Checked" is not formatted the same 
 as the other constraints.

 * Vertical spacing is just too fluffy. Looking e.g. at the docs 
 for "Payload" and "hook" - each has a short description. The 
 vspace between definition and description is too tall. The 
 vspace between the description and the next definition is too 
 tall. The grayed space within which the definition itself sits 
 has too large up and bottom margins. The vspace above "Jump 
 to:" is too high. Literally all vertical spacing is larger than 
 it should be.

 * The red vertical line on the left of each definition is meh. 
 There's a bit more sense for struct definitions because of the 
 "Jump to:" real estate. But for each little one-line 
 definition, the red bar is just odd. Also, there is no change 
 in color as indentation goes in (which would be a useful cue 
 for long struct definitions).

 * I don't see a point to the boxes within which each definition 
 + its comments sits. Then there's one more box for the example! 
 Boxes, boxes everywhere, and nary a drop to drink. They'd make 
 sense e.g. if one could collapse a box. As such - hey, they 
 just add more vspace :o).

 * The vspace between the ditto'ed definitions "enum auto min;" 
 and "enum auto max;" is again too large.

 * The grayed out constraints are also indented horizontally - 
 by a lot. If they're already distinguished by color, no need to 
 indent them. Oh, then I saw if you hover you see "Constraints: 
 " written in the space that seem to be indentation. Could we 
 format that in non-code font at least?

 * Spacing between doc paragraphs (see e.g. doc of opCast) seems 
 to be 80% line height. Should be 50%.

 * The enumerated items (see doc of opChecked) seem to be the 
 only artifact that's properly spaced vertically. I guess nobody 
 discovered them so they're at the system default.

 * "0 Contributors" should not be displayed at the bottom if 
 there are no contributors. But I assume that's only the case 
 before the pull is merged?


 Andrei
I'm not going to get involved this round of bikeshedding, (except to say that yes, the docs are far from perfect, and also that justification/hyphenation on the Web is a mixed bag, and right-ragged with a good line-length is a fine and robust solution). But I'd like to give some resources for reference. Racket's docs have actually been designed by a professional typographer, so might be a good reference point. Example: https://docs.racket-lang.org/reference/flonums.html And that the same person has an excellent online resource for typographic style: http://practicaltypography.com/ And it's good to have something like that (no matter if it's somewhat arbitrary) to decide these kinds of endlessly debatable issues. (Notice the site is left-justified/right-ragged :)) "Keep in mind that the jus­ti­fi­ca­tion en­gine of a word proces­sor or web browser is rudi­men­tary com­pared to that of a pro­fes­sional page-lay­out pro­gram. So if I’m mak­ing a word-proces­sor doc­u­ment or web page, I’ll al­ways left-align the text, be­cause jus­ti­fi­ca­tion can look clunky and coarse. Whereas if I’m us­ing a pro­fes­sional lay­out pro­gram, I might justify." (http://practicaltypography.com/justified-text.html)
Jul 18 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 07/18/2016 09:28 PM, Carl Vogel wrote:
 Racket's docs have actually been designed by a professional typographer,
 so might be a good reference point. Example:
 https://docs.racket-lang.org/reference/flonums.html
They do look nice! -- Andrei
Jul 18 2016
parent Charles Hixson via Digitalmars-d <digitalmars-d puremagic.com> writes:
I think the Python docs looks better and are more useful...but the older 
Python docs were even better.  Sometimes fancier HTML just makes things 
less useful.

That said, I think that when feasible docs should be auto-generated from 
code included within the code files.  More like ddoc or javadoc then 
Sphinx or such.  But this shouldn't necessarily apply to the basic 
frameworks.  The basic D documentation is extremely good, it's when we 
get to the libraries that things become a bit iffy.  (Then again, I 
don't like the template syntax.  I thought the D1 docs were better than 
the D2 docs, but this might be because when they were rewritten they 
assumed things that give me trouble.  I prefer the way that Python 
handles ranges to the way the D does. Etc.  These impact the 
understanding of the documentation of many Phobos files.)


On 07/18/2016 06:41 PM, Andrei Alexandrescu via Digitalmars-d wrote:
 On 07/18/2016 09:28 PM, Carl Vogel wrote:
 Racket's docs have actually been designed by a professional typographer,
 so might be a good reference point. Example:
 https://docs.racket-lang.org/reference/flonums.html
They do look nice! -- Andrei
Jul 21 2016
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 07/18/2016 11:56 AM, Andrei Alexandrescu wrote:
 I was proofreading
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experimental_checkedint.html
 and there are a few ways in which our docs could look better.
BTW, apparently the ddox version is not generated. Should be at: http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/library-prerelease/std/experimental/checkedint.html but it's not. Vladimir? Andrei
Jul 18 2016
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 07/18/2016 09:43 PM, Andrei Alexandrescu wrote:
 On 07/18/2016 11:56 AM, Andrei Alexandrescu wrote:
 I was proofreading
 http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experimental_checkedint.html

 and there are a few ways in which our docs could look better.
BTW, apparently the ddox version is not generated. Should be at: http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/library-prerelease/std/experimental/checkedint.html but it's not. Vladimir?
Eh, found it at: http://dtest.thecybershadow.net/artifact/website-32ee0211c7f70b1a06ed3f6ee49f561bee57fee0-ef296f09c3917e6f329f2ca29cbd9f6a/web/library-prerelease/std/experimental/checkedint.html The ddox version does look nicer. My only nits there are: * The red underline for links looks jarring, especially in conjunction with blue code. * Look, ma, no boxes - awesome. And most horizontal lines are understatedly helpful. * At the bottom of the page there's an odd "| Page generated by ddox." I suppose something should be before the pipe? * Well the template constraint is not formatted differently/helpfully. I'm thinking some stylized comments in conjunction with ddox could work miracles here. Andrei
Jul 18 2016
prev sibling next sibling parent Wyatt <wyatt.epp gmail.com> writes:
On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
wrote:
 * My pet dream was to work on a project with a beautiful 
 justified and hyphenated website. After endless debates, 
 ugliness has won - I'm looking at a eye-scratching ragged right 
 edge.
I just want to point out that Firefox will sporadically justify incredibly poorly, leaving huge spaces between words (In one extreme case, I caught it making something like 3cm gaps). It looks really bad, and isn't actually easier to read when the line length is long. -Wyatt
Jul 19 2016
prev sibling next sibling parent w0rp <devw0rp gmail.com> writes:
I like this kind of discussion. It's good to make the website 
look as attractive and functional as we can make it. I think we 
just need to remember to file each issue individually, then group 
all of the issues to track all of them. Then each individual 
issue can be tackled, and some work can get done while the rest 
of the issues are discussed.

Maybe I'm just speaking common sense or something, but I think 
it's worth mentioning.
Jul 21 2016
prev sibling parent Robert burner Schadek <rburners gmail.com> writes:
** RANT ON **

A perfect example for an item for your action list.
And it pretty much looks like the syntax the wiki is using 
already.

I bet you a drink at next years DConf that it will take you at 
least 10 minutes to find and reread this thread next time you 
create a vision document just to rewrite parts of it for you next 
vision document.

** RANT OFF **
Jul 26 2016