On Monday, 10 March 2014 at 16:58:45 UTC, Vladimir Panteleev wrote:
> On Monday, 10 March 2014 at 16:54:37 UTC, Brad Anderson wrote:
>>
>> I wanted to do just this so I considered adding a predefined macro to ddoc to get line numbers like I did to get filenames (I needed SRCFILENAME to add the Improve This Page button) but the line numbers would pretty quickly lose sync between master and the documentation so that would also require integrating the release tag into the documentation somehow so I gave up on that idea.
>
> So... don't link to master?
>
> The dmd repo has a VERSION file. Can that be used to link to the respective tag instead?

I'm not sure how ddox works but I suspect that wouldn't be terrible difficult to integrate. Doing it with ddoc would require something like copying the value from VERSION into a macro within std.ddoc using the html make target. Not terribly difficult but now that we are switching to ddox we might as well do it using ddox where line information is already easily accessible.

Am 10.03.2014 15:11, schrieb Vladimir Panteleev:
> On Monday, 10 March 2014 at 14:08:07 UTC, Mike wrote:
>> Thank you, to everone who worked on this.  It's quite an improvement.
>>
>> Problem:
>> http://dlang.org/library/std/compiler/vendor.html is a 404
>>
>> Recommendation:
>> I really liked the immediate link to the source file on github in the
>> old layout.  If possible please add it to the new layout.
>
> Since (IIRC) DDox parses JSON layout, I think it is capable of
> generating exact links to the file:line of each symbol. That would be
> neat, as it allows quickly seeing the implementation if the
> documentation is not sufficient.

It's actually already there - at the top of each page, there is a "View source code" button that goes to the proper file/line and to the proper branch/tag. I've used the same style as the already existing buttons, but those are indeed not very noticeable on the right side of the page.

Any suggestions for a better place/style without visually cluttering up the actual documentation?

The documentation is looking very good, good work to all involved. There are a few bugs here and there. Appender's docs were missing, some runtime modules are in there which should maybe be hidden. Still, this is a massive improvement, and I love it.

On Monday, 10 March 2014 at 18:56:41 UTC, Sönke Ludwig wrote:
> Am 10.03.2014 15:11, schrieb Vladimir Panteleev:
>> On Monday, 10 March 2014 at 14:08:07 UTC, Mike wrote:
>>> Thank you, to everone who worked on this.  It's quite an improvement.
>>>
>>> Problem:
>>> http://dlang.org/library/std/compiler/vendor.html is a 404
>>>
>>> Recommendation:
>>> I really liked the immediate link to the source file on github in the
>>> old layout.  If possible please add it to the new layout.
>>
>> Since (IIRC) DDox parses JSON layout, I think it is capable of
>> generating exact links to the file:line of each symbol. That would be
>> neat, as it allows quickly seeing the implementation if the
>> documentation is not sufficient.
>
> It's actually already there - at the top of each page, there is a "View source code" button that goes to the proper file/line and to the proper branch/tag.

Ah, that's great.

I think it's fine as it is, we just didn't expect it to be there already.

On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
> On 3/10/14, 7:00 AM, Dicebot wrote:
>> I still don't like disqus :)
>
> Are there better such systems available?
>

Yea, forum.dlang.org ;) And anything else that doesn't completely and totally break without JS.

On Monday, 10 March 2014 at 18:56:41 UTC, Sönke Ludwig wrote:
> It's actually already there - at the top of each page, there is a "View source code" button that goes to the proper file/line and to the proper branch/tag. I've used the same style as the already existing buttons, but those are indeed not very noticeable on the right side of the page.
>

Oops. My mistake. I'm happy with it the way it is.

On Monday, 10 March 2014 at 22:28:11 UTC, Nick Sabalausky wrote:
> On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
>> On 3/10/14, 7:00 AM, Dicebot wrote:
>>> I still don't like disqus :)
>>
>> Are there better such systems available?
>>
>
> Yea, forum.dlang.org ;) And anything else that doesn't completely and totally break without JS.

A possible plan for forum.dlang.org integration:

1. Walter and Brad create a new newsgroup and mailing list specifically for doc comments.
2. We have one thread per documentation page.
3. The relevant thread is displayed on each page via an iframe or a JS snippet (with a noscript iframe fallback).

Downsides:

- Requires implementation effort, whereas Disqus is already there.
- Limited moderation support (although I don't imagine the problem to be worse than now, and there is still room for improvement with the current one).
- No formatting.
- No voting.
- (More Disqus advantages I forgot? I think the previous thread had a few more.)

Benefits:

- We hold all data ourselves. If disaster strikes, the code is open-source, I have backups, and Walter and Andrei have SSH access.
- No JavaScript required.
- Forum, newsgroup and mailing list integration allows volunteers to easily subscribe to new comments, and answer questions as they are posted. As DFeed is also an IRC client, IRC notifications are also possible.
- As the code is open-source, we can implement features that are present in Disqus, or even features that Disqus doesn't have.
- Subjective, but hopefully we can come up with a less cluttered interface. There's lots of elements which I think are undesirable: "Share", "Favorite", the "vibe.d" link (what's that for?), "Subscribe", "Add Disqus to your site", the "Disqus" logo, "comments powered by Disqus".

On 3/10/14, 3:28 PM, Nick Sabalausky wrote:
> On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
>> On 3/10/14, 7:00 AM, Dicebot wrote:
>>> I still don't like disqus :)
>>
>> Are there better such systems available?
>>
>
> Yea, forum.dlang.org ;) And anything else that doesn't completely and
> totally break without JS.

Well forum.dlang.org has quite a different charter doesn't it?

Also it lacks a very basic feature that I asked for in vain: a flat list of messages sorted by date posted, most recent. It would be the one thing that would make it comparable to the NNTP I use.

Andrei

On Monday, 10 March 2014 at 22:56:04 UTC, Andrei Alexandrescu wrote:
> On 3/10/14, 3:28 PM, Nick Sabalausky wrote:
>> On 3/10/2014 11:08 AM, Andrei Alexandrescu wrote:
>>> On 3/10/14, 7:00 AM, Dicebot wrote:
>>>> I still don't like disqus :)
>>>
>>> Are there better such systems available?
>>>
>>
>> Yea, forum.dlang.org ;) And anything else that doesn't completely and
>> totally break without JS.
>
> Well forum.dlang.org has quite a different charter doesn't it?
>
> Also it lacks a very basic feature that I asked for in vain: a flat list of messages sorted by date posted, most recent. It would be the one thing that would make it comparable to the NNTP I use.

It's still on my list... sorry it's taking this long. You're the only one who requested this feature, though. I can think of several improvements (some of which are in the pipeline) which I think would be more useful to the community overall, but if you think this is important I can bump it higher :)

A key required (imho) feature, the ability to edit after the fact.  The primary value that I see in any sort of embedded user input feature is the the most streamlined way of adding essentially bug reports about the page directly on the page.  Those reports should be acted upon and the page itself updated after which the report dropped.  The same with the essentially unmaintained wiki page that is linked to most of the dlang.org pages.

I'm concerned about it becoming yet another forum for discussion.  Yet another place that needs to be monitored and maintained.  Something else that will grow stale.  Etc.  There's certainly value, and I've seen the value on other sites that support per-page user comments.  But there's a very real and very important cost that comes with it.

My 2 cents,
Brad