www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Fixed date to move to ddox for Phobos documentation

reply Seb <seb wilzba.ch> writes:
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
Jun 04 2016
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jun 04 2016
next sibling parent reply ag0aep6g <anonymous example.com> writes:
On 06/04/2016 07:01 PM, Andrei Alexandrescu wrote:
 * 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).
I have a pull request open that addresses the issue: https://github.com/dlang/phobos/pull/4397 It hides the handcrafted cheat sheets. It's not been pulled yet, because the handcrafted cheat sheets may be better than the generated ones. I haven't been able to figure out how to hide the generated ones. Also, the handcrafted ones tend to get outdated which is especially bad with DDOX, because you can't just scroll down to it.
Jun 04 2016
parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 04.06.2016 um 19:18 schrieb ag0aep6g:
 On 06/04/2016 07:01 PM, Andrei Alexandrescu wrote:
 * 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).
I have a pull request open that addresses the issue: https://github.com/dlang/phobos/pull/4397 It hides the handcrafted cheat sheets. It's not been pulled yet, because the handcrafted cheat sheets may be better than the generated ones. I haven't been able to figure out how to hide the generated ones. Also, the handcrafted ones tend to get outdated which is especially bad with DDOX, because you can't just scroll down to it.
I think ideally we could do something like introducing a special "Cheatsheet" section or macro for each function that DDOX could aggregate or use instead of the normal short description. Also interesting (although less so since we started using sub modules) would be to do the same for a group/category that would be used to group symbols by other means that simply their type category. The downside is that the normal Ddoc generated docs couldn't use that information to display the overview tables like it does now, so it would make most sense to do this after making the switch.
Jun 04 2016
parent ag0aep6g <anonymous example.com> writes:
On 06/04/2016 07:25 PM, Sönke Ludwig wrote:
 I think ideally we could do something like introducing a special
 "Cheatsheet" section or macro for each function that DDOX could
 aggregate or use instead of the normal short description. Also
 interesting (although less so since we started using sub modules) would
 be to do the same for a group/category that would be used to group
 symbols by other means that simply their type category.

 The downside is that the normal Ddoc generated docs couldn't use that
 information to display the overview tables like it does now, so it would
 make most sense to do this after making the switch.
Thinking about this, if the information in the cheat sheet is the most helpful, maybe we should be putting exactly that in the summaries of things. Meaning, maybe we should change summaries to be one short sentence and/or one short example.
Jun 04 2016
prev sibling parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
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.
Jun 04 2016
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/4/16 2:23 PM, Sönke Ludwig wrote:
 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.
Great, thanks.
 * 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.
Any way you prefer. I'd be fine with copying the manually-crafted table from /phobos/, and eliminate or modify the short text preceding it.
 ** 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.
Cool, thanks. (I think the comments will play a nice role in the future.)
 ** 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:
Oh, I meant the actual word. "Prototypes". It takes a lot of vertical space and doesn't add information, because obviously what follows are the prototypes.
 ** 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/.
Makes sense. Any reasonable design should work fine there.
 ** 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.
Awesome.
 ** 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.
Reasonable.
 ** 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?
I'm thinking just rendering the information in an obvious and immediate manner that doesn't require scrolling or eyes to jump across the page. Consider e.g. https://doc.rust-lang.org/std/boxed/trait.FnBox.html. You open the page and boom, you know it's a trait, you see the signature (without the need to read "Hey hey hey...! here comes the signature!" etc), you see a small yet conspicuous colored box with important information about instability, you see the synopsys, and the example is right after. No need to scroll! It's all clean, immediate, and matter-of-fact, no pomp and circumstance. Imagine that rendered with all components delineated by own headings "<br><br><br>Warning:<br><br>Unstable (fnbox #28796): Newly introduced<br><br><br>" etc.
 * 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 ;-)
Noice.
 * 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.
Seems we can easily defer that if we continue to produce both forms.
 * 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?
I want to collect statistics on how many people continue to use the one-page style. If too few, we can remove that later. This is no competition and no zero sum game: we have two formats and we can leverage that. I and many others prefer page-per-artifact, so /library/ is awesome. However there might be a bunch of folks out there comfy with the page-per-module, and why hurt them if we needn't.
 * 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.
OK.
 * 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.
Thanks.
 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.
Sounds good. I have an honest answer and a manager answer. The honest answer is that only the broken links need to be fixed before. The manager answer is that everything should be fixed before, because then the release creates a forcing function. Otherwise, it could take months before any is looked at. Andrei
Jun 04 2016
prev sibling parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/04/2016 08:23 PM, Sönke Ludwig wrote:
 I think they have. Vladimir has reported a bunch of them over time and
 all of those have been fixed.
Found a new one ;). [Issue 16152 – dpl-docs/ddox doesn't show documentation for eponymous template member](https://issues.dlang.org/show_bug.cgi?id=16152)
Jun 10 2016
prev sibling next sibling parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Saturday, 4 June 2016 at 16:10:14 UTC, Seb wrote:
 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.
One wholesome switch is probably too harsh. We might discover new issues only after the switch. Instead it could be done gradually, in this order: 1. /library/ is promoted as the primary Phobos documentation in the site navigation. 2. /phobos/ is removed from search indexing. 3. /phobos/ is removed from site navigation. 4. /phobos/ is removed. We could start with step 1 upon 2.072's release.
Jun 04 2016
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/4/16 2:33 PM, Vladimir Panteleev wrote:
 On Saturday, 4 June 2016 at 16:10:14 UTC, Seb wrote:
 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.
One wholesome switch is probably too harsh. We might discover new issues only after the switch. Instead it could be done gradually, in this order: 1. /library/ is promoted as the primary Phobos documentation in the site navigation. 2. /phobos/ is removed from search indexing. 3. /phobos/ is removed from site navigation. 4. /phobos/ is removed. We could start with step 1 upon 2.072's release.
Sounds good to me, thanks. Delegation/lieutenantship/empowering for the win. I think we should also secure Martin's buy-in to make sure. -- Andrei
Jun 04 2016
next sibling parent Seb <seb wilzba.ch> writes:
On Saturday, 4 June 2016 at 19:32:33 UTC, Andrei Alexandrescu 
wrote:
 On 6/4/16 2:33 PM, Vladimir Panteleev wrote:
 [...]
Sounds good to me, thanks. Delegation/lieutenantship/empowering for the win. I think we should also secure Martin's buy-in to make sure. -- Andrei
Nice idea! Maybe we can let step 2 follow quickly? Reason: (from a recent discussion here [1])
 As someone who recently tried D and dropped it to learn Python 
 [...] Two main issues I saw? Broken links and poor examples. 
 Also occasionally I get pages that look like a different a 
 style from google searches than the main documentation pages, 
 which makes me feel one is outdated. I ended up actually just 
 going to dlang.org itself to be sure...
[1] http://forum.dlang.org/post/ixpujamnyhguuqiflvom forum.dlang.org
Jun 05 2016
prev sibling parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/04/2016 09:32 PM, Andrei Alexandrescu wrote:
 Sounds good to me, thanks. Delegation/lieutenantship/empowering for the
 win. I think we should also secure Martin's buy-in to make sure. -- Andrei
I'm fine with switching to ddox, could have happened a while ago. Would be worth to switch for the auto-complete alone. I'd want to disable or replace discourse before we make it our official documentation. We could easily self-host some commenting functionality if deemed necessary, but adding an unmaintained communication channel isn't the best idea IMO. -Martin
Jun 10 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/10/16 3:17 PM, Martin Nowak wrote:
 On 06/04/2016 09:32 PM, Andrei Alexandrescu wrote:
 Sounds good to me, thanks. Delegation/lieutenantship/empowering for the
 win. I think we should also secure Martin's buy-in to make sure. -- Andrei
I'm fine with switching to ddox, could have happened a while ago. Would be worth to switch for the auto-complete alone.
Awesome! I should add that it would be valuable to keep the ddoc build as well. In my introductory material on D I discuss the basic elements of distribution: function, unittest, doc, deployment. It is compelling to mention that we build the stdlib documentation using the same means. An introduction to ddox at that point would be too much, and mentioning that "well ddoc isn't good enough for the official stdlib doc" does not sit well.
 I'd want to disable or replace discourse before we make it our official
 documentation. We could easily self-host some commenting functionality
 if deemed necessary, but adding an unmaintained communication channel
 isn't the best idea IMO.
I'm a bit bummed about that. I like it. Is my understanding incorrect that disqus is fairly established by now? I see it on a bunch of legit sites, and it seems to add value to those as it could add to ours. Andrei
Jun 10 2016
next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 6/10/16 1:33 PM, Andrei Alexandrescu wrote:
 On 6/10/16 3:17 PM, Martin Nowak wrote:
 I'd want to disable or replace discourse before we make it our official
 documentation. We could easily self-host some commenting functionality
 if deemed necessary, but adding an unmaintained communication channel
 isn't the best idea IMO.
I'm a bit bummed about that. I like it. Is my understanding incorrect that disqus is fairly established by now? I see it on a bunch of legit sites, and it seems to add value to those as it could add to ours.
I can see a good reason to have a disqus forum for each page, as I have found tremendous value from the php.net forums on each symbol (with common tricks to use with the given function). But the problem is, people will ask questions on these forums, and likely will not get answers. I know I'm not going to peruse the docs looking for questions to answer. It's like adding 1000 black holes for newbies to get trapped in. So what would be the use cases? If we have legitimate reasons to have it, that aren't better solved by routing back to the D forums, or back to github itself (e.g. if you have a trick to post, instead of using disqus, create a PR with the example!). -Steve
Jun 10 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/10/16 5:46 PM, Steven Schveighoffer wrote:
 On 6/10/16 1:33 PM, Andrei Alexandrescu wrote:
 On 6/10/16 3:17 PM, Martin Nowak wrote:
 I'd want to disable or replace discourse before we make it our official
 documentation. We could easily self-host some commenting functionality
 if deemed necessary, but adding an unmaintained communication channel
 isn't the best idea IMO.
I'm a bit bummed about that. I like it. Is my understanding incorrect that disqus is fairly established by now? I see it on a bunch of legit sites, and it seems to add value to those as it could add to ours.
I can see a good reason to have a disqus forum for each page, as I have found tremendous value from the php.net forums on each symbol (with common tricks to use with the given function). But the problem is, people will ask questions on these forums, and likely will not get answers.
Why not? -- Andrei
Jun 11 2016
parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Saturday, June 11, 2016 08:45:08 Andrei Alexandrescu via Digitalmars-d 
wrote:
 On 6/10/16 5:46 PM, Steven Schveighoffer wrote:
 On 6/10/16 1:33 PM, Andrei Alexandrescu wrote:
 On 6/10/16 3:17 PM, Martin Nowak wrote:
 I'd want to disable or replace discourse before we make it our official
 documentation. We could easily self-host some commenting functionality
 if deemed necessary, but adding an unmaintained communication channel
 isn't the best idea IMO.
I'm a bit bummed about that. I like it. Is my understanding incorrect that disqus is fairly established by now? I see it on a bunch of legit sites, and it seems to add value to those as it could add to ours.
I can see a good reason to have a disqus forum for each page, as I have found tremendous value from the php.net forums on each symbol (with common tricks to use with the given function). But the problem is, people will ask questions on these forums, and likely will not get answers.
Why not? -- Andrei
Are _you_ going to spend time going through every single page in the documentation, looking to see whether someone asked a question and then reply to them if they did? I'm sure not doing that, and I doubt that many of us will be. I, for one, rarely even look at the online documentation. I usually just look at the source code locally. And even if I did look at the online docs on a regular basis, I'd only see comments on the symbols that I happened to be looking up, and even then, only if I took the extra time to look and see whether there were comments. I sure wouldn't be going to the docs just to see whether someone asked a question - especially when there so many pages to search through. I really don't see how it's tractable to have hundreds (if not thousands) of pages on dlang.org where someone could ask a question. They will occasionally get an answer, but it's more likely to be from someone else who doesn't know much than it is from anyone who could give a good answer, since the folks who are most likely to give good answers won't even be looking. What's far more likely is that folks will get frustrated, because they asked a question on the documentation page for a symbol and never got an answer - or if they did, it was weeks or months later. - Jonathan M Davis
Jun 11 2016
next sibling parent deed <none none.none> writes:
On Saturday, 11 June 2016 at 12:31:28 UTC, Jonathan M Davis wrote:
 I really don't see how it's tractable to have hundreds (if not 
 thousands) of pages on dlang.org where someone could ask a 
 question.
Wouldn't that be solved by automatically posting the question to Learn with a link?
Jun 11 2016
prev sibling next sibling parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/11/2016 02:31 PM, Jonathan M Davis via Digitalmars-d wrote:
 But the problem is, people will ask questions on these forums, and
 likely will not get answers.
Why not? -- Andrei
Are _you_ going to spend time going through every single page in the documentation, looking to see whether someone asked a question and then reply to them if they did?
There is obviously an overview page https://disqus.com/home/forums/vibe-d/, but I doubt that we'll actively administrate it. Also look at ruby-doc, there is literally zero traffic on the comments. https://disqus.com/home/forum/ruby-doc/. Maybe it doesn't hurt much and might help to gather good ideas for some entities.
Jun 11 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/11/16 12:31 PM, Jonathan M Davis via Digitalmars-d wrote:
 Are_you_  going to spend time going through every single page in the
 documentation, looking to see whether someone asked a question and then
 reply to them if they did?
I get notified by disqus for new posts. The basic idea is if we don't prime it we'll never have it. -- Andrei
Jun 11 2016
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Saturday, 11 June 2016 at 19:20:56 UTC, Andrei Alexandrescu 
wrote:
 On 6/11/16 12:31 PM, Jonathan M Davis via Digitalmars-d wrote:
 Are_you_  going to spend time going through every single page 
 in the
 documentation, looking to see whether someone asked a question 
 and then
 reply to them if they did?
I get notified by disqus for new posts. The basic idea is if we don't prime it we'll never have it. -- Andrei
I think it wouldn't be too hard to embed DFeed as a comment system. What do you think? Then anyone can subscribe to new comments through the usual means. The same solution can be applied to the blog. I understand that the current bottleneck is someone adding new groups to the NNTP server. Can that be resolved?
Jun 11 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 06/11/2016 03:28 PM, Vladimir Panteleev wrote:
 On Saturday, 11 June 2016 at 19:20:56 UTC, Andrei Alexandrescu wrote:
 On 6/11/16 12:31 PM, Jonathan M Davis via Digitalmars-d wrote:
 Are_you_  going to spend time going through every single page in the
 documentation, looking to see whether someone asked a question and then
 reply to them if they did?
I get notified by disqus for new posts. The basic idea is if we don't prime it we'll never have it. -- Andrei
I think it wouldn't be too hard to embed DFeed as a comment system. What do you think? Then anyone can subscribe to new comments through the usual means. The same solution can be applied to the blog.
I'm thinking the line between good dogfooding and NIH is thin. The real questions we should be asking ourselves is how well does disqus serve our purpose, how good a future it has, and how many folks see it as an unpleasant association. Also, how long it would take to adapt DFeed and what advantages/liabilities it has.
 I understand that the current bottleneck is someone adding new groups to
 the NNTP server. Can that be resolved?
Walter or Jan should be able to do that. But I'm confused as to how NNTP groups would help here. Andrei
Jun 13 2016
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu 
wrote:
 Walter or Jan should be able to do that. But I'm confused as to 
 how NNTP groups would help here.
It would allow people to subscribe and reply to comments using their newsreader (or by email, if it's also associated with a mailing list on Brad's server). It's one of the bigger reasons to consider using DFeed.
Jun 13 2016
next sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 6/13/16 9:41 PM, Vladimir Panteleev wrote:
 On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu wrote:
 Walter or Jan should be able to do that. But I'm confused as to how
 NNTP groups would help here.
It would allow people to subscribe and reply to comments using their newsreader (or by email, if it's also associated with a mailing list on Brad's server). It's one of the bigger reasons to consider using DFeed.
So, this means that someone posts a question to the library's std.algorithm.map function (for example), and a newsgroup called `library` gets a post with subject like: [std.algorithm.iteration.map] How does map work? With replies on newsgroup and email server getting posted back to thread? If this is the case, I'm all for it. The other features of disqus are trivial (up/downvoting mechanism), and not necessary there. There must be a way, however, to remove posts (at least for dfeed). We don't want spam or irrelevant posts lingering there forever. -Steve
Jun 14 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/13/16 9:41 PM, Vladimir Panteleev wrote:
 On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu wrote:
 Walter or Jan should be able to do that. But I'm confused as to how
 NNTP groups would help here.
It would allow people to subscribe and reply to comments using their newsreader (or by email, if it's also associated with a mailing list on Brad's server). It's one of the bigger reasons to consider using DFeed.
Aren't the snazzy nice formatting and the display in the page the nicest things about on-doc-page comments? Email subscription to such is fine but writing via email or NNTP seems a clunky adaptation. BTW does disqus allow D syntax coloring? -- Andrei
Jun 14 2016
parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 14 June 2016 at 13:40:57 UTC, Andrei Alexandrescu 
wrote:
 On 6/13/16 9:41 PM, Vladimir Panteleev wrote:
 On Tuesday, 14 June 2016 at 00:31:56 UTC, Andrei Alexandrescu 
 wrote:
 Walter or Jan should be able to do that. But I'm confused as 
 to how
 NNTP groups would help here.
It would allow people to subscribe and reply to comments using their newsreader (or by email, if it's also associated with a mailing list on Brad's server). It's one of the bigger reasons to consider using DFeed.
Aren't the snazzy nice formatting and the display in the page the nicest things about on-doc-page comments? Email subscription to such is fine but writing via email or NNTP seems a clunky adaptation. BTW does disqus allow D syntax coloring? -- Andrei
Well, Markdown support is on the roadmap, and embedding it into the page like Disqus was part of the proposal. Email/NNTP is an option, not a requirement :)
Jun 14 2016
prev sibling next sibling parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Friday, 10 June 2016 at 17:33:01 UTC, Andrei Alexandrescu 
wrote:
 I should add that it would be valuable to keep the ddoc build 
 as well.
We need DDoc anyway for the website itself, as well as formats other than the website (e.g. CHM and HTML files distributed with the compiler), so it's not going away.
Jun 10 2016
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/11/16 5:16 AM, Vladimir Panteleev wrote:
 On Friday, 10 June 2016 at 17:33:01 UTC, Andrei Alexandrescu wrote:
 I should add that it would be valuable to keep the ddoc build as well.
We need DDoc anyway for the website itself, as well as formats other than the website (e.g. CHM and HTML files distributed with the compiler), so it's not going away.
I mean ddoc for the standard library code. -- Andrei
Jun 11 2016
parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Saturday, June 11, 2016 08:48:53 Andrei Alexandrescu via Digitalmars-d 
wrote:
 On 6/11/16 5:16 AM, Vladimir Panteleev wrote:
 On Friday, 10 June 2016 at 17:33:01 UTC, Andrei Alexandrescu wrote:
 I should add that it would be valuable to keep the ddoc build as well.
We need DDoc anyway for the website itself, as well as formats other than the website (e.g. CHM and HTML files distributed with the compiler), so it's not going away.
I mean ddoc for the standard library code. -- Andrei
I'm fine with generating the docs with ddox if that works better, but I sure hope that we're not going to then change how we're doing the actual documenattion in the source files except that if ddox is smart enough that we don't need many of the linking macros, then I could see getting rid of some of those from the docs. I expect to be able to use version(StdDdoc) and all that and have it do the right thing with ddox, or the switch to ddox is going to be very annoying from the standpoint of maintaining the code. However, I would assume that that's all already been sorted out, since we've been generating the docs with ddox alongside the normal documentation for some time now. - Jonathan M Davis
Jun 11 2016
parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/11/2016 02:24 PM, Jonathan M Davis via Digitalmars-d wrote:
 I'm fine with generating the docs with ddox if that works better, but I sure
 hope that we're not going to then change how we're doing the actual
 documenattion in the source files except that if ddox is smart enough that
 we don't need many of the linking macros, then I could see getting rid of
 some of those from the docs.
 
 I expect to be able to use version(StdDdoc) and all that and have it do the
 right thing with ddox, or the switch to ddox is going to be very annoying
 from the standpoint of maintaining the code. However, I would assume that
 that's all already been sorted out, since we've been generating the docs
 with ddox alongside the normal documentation for some time now.
 
 - Jonathan M Davis
It already does all of that (uses dmd's json output atm.), and of course has a ddoc macro interpreter built-in (emulating all of it's quirks).
Jun 11 2016
prev sibling parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/10/2016 07:33 PM, Andrei Alexandrescu wrote:
 I'm a bit bummed about that. I like it. Is my understanding incorrect
 that disqus is fairly established by now?
You need to create an account with a pay-by-data company to even post something.
Jun 11 2016
next sibling parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/11/2016 03:02 PM, Martin Nowak wrote:
 On 06/10/2016 07:33 PM, Andrei Alexandrescu wrote:
 I'm a bit bummed about that. I like it. Is my understanding incorrect
 that disqus is fairly established by now?
You need to create an account with a pay-by-data company to even post something.
I'm mostly out at either of those steps. Adding some simple comments, really doesn't require so much fanciness, e.g. this https://code.dawg.eu/reducing-vibed-turnaround-time-part-1-faster-linking.html runs on a simple sqlite db (https://github.com/posativ/isso).
Jun 11 2016
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 06/11/2016 09:02 AM, Martin Nowak wrote:
 On 06/10/2016 07:33 PM, Andrei Alexandrescu wrote:
 I'm a bit bummed about that. I like it. Is my understanding incorrect
 that disqus is fairly established by now?
You need to create an account with a pay-by-data company to even post something.
How would we estimate the intersection between folks who do want to ask a question, and folks who are ideologically opposed to signing up with disqus? Also, we need to be careful about the influence of our personal beliefs on the core contributors and the community. -- Andrei
Jun 13 2016
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Tuesday, 14 June 2016 at 00:27:21 UTC, Andrei Alexandrescu 
wrote:
 How would we estimate the intersection between folks who do 
 want to ask a question, and folks who are ideologically opposed 
 to signing up with disqus? Also, we need to be careful about 
 the influence of our personal beliefs on the core contributors 
 and the community. -- Andrei
Correct me if I'm wrong but the above consideration excludes the people who are capable of answering questions.
Jun 13 2016
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 14 June 2016 at 01:42:26 UTC, Vladimir Panteleev 
wrote:
 Correct me if I'm wrong but the above consideration excludes 
 the people who are capable of answering questions.
Yeah, I'm not likely to ever use disqus but if it went through the same n.g./mailing list interface at least I'd consider talking at times (though I personally think comments in documentation should typically be used to just go back and improve the documentation rather than making readers actually wade through the out-of-date and repetitive comment thread...)
Jun 13 2016
parent Seb <seb wilzba.ch> writes:
On Tuesday, 14 June 2016 at 01:57:44 UTC, Adam D. Ruppe wrote:
 (though I personally think comments in documentation should 
 typically be used to just go back and improve the documentation 
 rather than making readers actually wade through the 
 out-of-date and repetitive comment thread...)
+1 Also I think having a "show in action"/"show usages" button that searches for the symbol within the dub universe would be a lot more useful.
Jun 14 2016
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 6/13/16 9:42 PM, Vladimir Panteleev wrote:
 On Tuesday, 14 June 2016 at 00:27:21 UTC, Andrei Alexandrescu wrote:
 How would we estimate the intersection between folks who do want to
 ask a question, and folks who are ideologically opposed to signing up
 with disqus? Also, we need to be careful about the influence of our
 personal beliefs on the core contributors and the community. -- Andrei
Correct me if I'm wrong but the above consideration excludes the people who are capable of answering questions.
Oh, indeed - s/want to ask a question/want to ask or answer a question/ Andrei
Jun 14 2016
prev sibling parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Saturday, June 04, 2016 18:33:40 Vladimir Panteleev via Digitalmars-d 
wrote:
 On Saturday, 4 June 2016 at 16:10:14 UTC, Seb wrote:
 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.
One wholesome switch is probably too harsh. We might discover new issues only after the switch. Instead it could be done gradually, in this order: 1. /library/ is promoted as the primary Phobos documentation in the site navigation. 2. /phobos/ is removed from search indexing. 3. /phobos/ is removed from site navigation. 4. /phobos/ is removed. We could start with step 1 upon 2.072's release.
I would point out that removing /phobos/ will break links elsewhere online. For instance, I know that I've linked to the documentation on numerous occasions in posts in the newsgroup and in answers on stackoverflow. All of those will break if /phobos/ is removed. If at all reasonably, possible, the old links should continue to work, even if they point to the new documentation. - Jonathan M Davis
Jun 05 2016
parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
On Sunday, 5 June 2016 at 15:45:11 UTC, Jonathan M Davis wrote:
 I would point out that removing /phobos/ will break links 
 elsewhere online. For instance, I know that I've linked to the 
 documentation on numerous occasions in posts in the newsgroup 
 and in answers on stackoverflow. All of those will break if 
 /phobos/ is removed. If at all reasonably, possible, the old 
 links should continue to work, even if they point to the new 
 documentation.
Of course, by "removed" I mean "replaced with redirects".
Jun 05 2016
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 04/06/16 18:10, Seb wrote:

 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.
I found a minor issue recently. If there's more than one symbol in the same module with the same name but with different casing, all these symbols are shown on the same "single symbol page". Not sure if that's solvable due to some operating systems not using case sensitive file systems. -- /Jacob Carlborg
Jun 05 2016
parent Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 06/05/2016 11:21 AM, Jacob Carlborg wrote:
 I found a minor issue recently. If there's more than one symbol in the
 same module with the same name but with different casing, all these
 symbols are shown on the same "single symbol page". Not sure if that's
 solvable due to some operating systems not using case sensitive file
 systems.
We specifically fix it that way. [Issue 12526 DDox possible issue with case sensitive file names](https://issues.dlang.org/show_bug.cgi?id=12526) If only the casing differs, the entities should always belong together. -Martin
Jun 10 2016
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2016-06-04 18:10, 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.
Just found this issue [1], symbols are hyphenated in Safari. [1] https://github.com/rejectedsoftware/ddox/issues/126 -- /Jacob Carlborg
Jun 16 2016