www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Improved Phobos dox

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
I finally gathered strength to rebase 
https://github.com/D-Programming-Language/dlang.org/pull/271 manually, 
which was every bit as involved as I feared.

I hope I didn't mess up anything, reviews appreciated.

That diff includes a new page navigation scheme. (Wasn't the main 
purpose of the diff but found it a nice perk.) I see it as a 
transitional stage toward the larger transition to one-page-per-entity 
that Snke has proposed.

Check out the new navigation at 
http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as 
the top gets replaced by a slick drop-down. Once you jump to a name, you 
can go back by pressing the up arrow on the right or simply go to top.


Andrei
Sep 15 2013
next sibling parent Lionello Lunesu <lionello lunesu.remove.com> writes:
On 9/15/13 15:14, Andrei Alexandrescu wrote:
 I finally gathered strength to rebase
 https://github.com/D-Programming-Language/dlang.org/pull/271 manually,
 which was every bit as involved as I feared.

 I hope I didn't mess up anything, reviews appreciated.

 That diff includes a new page navigation scheme. (Wasn't the main
 purpose of the diff but found it a nice perk.) I see it as a
 transitional stage toward the larger transition to one-page-per-entity
 that Snke has proposed.

 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
 the top gets replaced by a slick drop-down. Once you jump to a name, you
 can go back by pressing the up arrow on the right or simply go to top.


 Andrei

Could you have a look at https://github.com/D-Programming-Language/dmd/pull/2121 ? I'm not sure what's holding that PR up, no concerns were raised, but it would greatly improve the quality of the documentation. L.
Sep 15 2013
prev sibling next sibling parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu 
wrote:
 Check out the new navigation at 
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" 
 list as the top gets replaced by a slick drop-down. Once you 
 jump to a name, you can go back by pressing the up arrow on the 
 right or simply go to top.

I'm not sure this is an improvement, functionally. Finding the right item in much faster when you can see all items at once, and not lined up on only one direction. Also, Ctrl+F was more likely to find the link to the correct item before than now (and if you used your browser's inline search feature, then you could activate that link by pressing Enter). I think some kind of outline would be more useful. What happened with Ddox? This looks like an improvement in both function and aesthetics: http://vibed.org/temp/phobos/std/array.html
Sep 15 2013
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2013-09-15 11:03, Paolo Invernizzi wrote:

 I tend to agree with Vladimir...

+1 -- /Jacob Carlborg
Sep 15 2013
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2013-09-15 13:32, Andrej Mitrovic wrote:

 It's not an improvement at all. Ctrl+F doesn't work with this (like
 you mentioned), and the items list is not even sorted
 alphabetically(!), so now we have to hunt down a symbol before we can
 jump to it. Also, what used to be just one step (click), now becomes
 more (click, scroll, click).

 The categorical table at the top of
 http://dlang.org/phobos/std_algorithm.html is what I prefer the most,
 we could implemented this on other pages.

The only improvement I can see is that it doesn't list non-module symbols. That is members in classes/structs and similar. -- /Jacob Carlborg
Sep 15 2013
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in both function and
 aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.
Sep 15 2013
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 15.09.2013 19:20, schrieb Walter Bright:
 On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in both
 function and
 aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html
Sep 15 2013
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 9/15/2013 11:38 AM, Sönke Ludwig wrote:
 Am 15.09.2013 19:20, schrieb Walter Bright:
 On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in both
 function and
 aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

Much better!
Sep 15 2013
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 16.09.2013 02:54, schrieb Walter Bright:
 On 9/15/2013 11:38 AM, Sönke Ludwig wrote:
 Am 15.09.2013 19:20, schrieb Walter Bright:
 On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in both
 function and
 aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

Much better!

I need some form of authoritative decision on how to go about making (or not making) the transition before I can start to work on the necessary changes to the make file and the rest of the site. There is a suggestion I made in the pull request: https://github.com/D-Programming-Language/dlang.org/pull/267
Sep 15 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 11:34 PM, Sönke Ludwig wrote:
 I need some form of authoritative decision on how to go about making (or
 not making) the transition before I can start to work on the necessary
 changes to the make file and the rest of the site. There is a suggestion
 I made in the pull request:

 https://github.com/D-Programming-Language/dlang.org/pull/267

What other changes need to be made in addition to what's in 267 now? Andrei
Sep 16 2013
parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig outerproduct.org> writes:
Am 16.09.2013 12:45, schrieb Andrei Alexandrescu:
 On 9/15/13 11:34 PM, Sönke Ludwig wrote:
 I need some form of authoritative decision on how to go about making (or
 not making) the transition before I can start to work on the necessary
 changes to the make file and the rest of the site. There is a suggestion
 I made in the pull request:

 https://github.com/D-Programming-Language/dlang.org/pull/267

What other changes need to be made in addition to what's in 267 now? Andrei

My idea was to make a proper transition from the current docs to the new ones using a different path. Quoting from the pull: - Adjust the make file so that the ddox documentation goes to "library/" and "library-prerelease/" instead of "phobos/" - leave the original documentation there - Keep the main documentation links pointed to "phobos/", but add a small secondary link to "library/" - (Optional) In the ddox documentation, add a link at the top of each page to the corresponding old doc page - Make the pull in this state - Incorporate improvements for a while and eventually exchange the links, making "library/" the default Maybe with "api" instead of "library". The current state is that the new docs have a separate make target that needs to be invoked explicitly, but it will write to the same "phobos" folder.
Sep 16 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 10:12 AM, Sönke Ludwig wrote:
 Am 16.09.2013 12:45, schrieb Andrei Alexandrescu:
 On 9/15/13 11:34 PM, Sönke Ludwig wrote:
 I need some form of authoritative decision on how to go about making (or
 not making) the transition before I can start to work on the necessary
 changes to the make file and the rest of the site. There is a suggestion
 I made in the pull request:

 https://github.com/D-Programming-Language/dlang.org/pull/267

What other changes need to be made in addition to what's in 267 now? Andrei

My idea was to make a proper transition from the current docs to the new ones using a different path. Quoting from the pull: - Adjust the make file so that the ddox documentation goes to "library/" and "library-prerelease/" instead of "phobos/" - leave the original documentation there

OK, preserve existing links and migrate later, nice.
   - Keep the main documentation links pointed to "phobos/", but add a
 small secondary link to "library/"

Fine for the beginning. Guess we can pull the plug in a future small diff.
   - (Optional) In the ddox documentation, add a link at the top of each
 page to the corresponding old doc page

Probably not worth the trouble, but always good if easy to implement for making transitioning palatable.
   - Make the pull in this state

Ja.
   - Incorporate improvements for a while and eventually exchange the
 links, making "library/" the default

 Maybe with "api" instead of "library".

 The current state is that the new docs have a separate make target that
 needs to be invoked explicitly, but it will write to the same "phobos"
 folder.

OK great. I'll look at it soon. Andrei
Sep 16 2013
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 9:53 PM, H. S. Teoh wrote:
 On Mon, Sep 16, 2013 at 06:15:35AM +0200, deadalnix wrote:
 On Sunday, 15 September 2013 at 18:38:54 UTC, Snke Ludwig wrote:
 Am 15.09.2013 19:20, schrieb Walter Bright:
 On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in both
 function and aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

I'm sold, that is awesome !

Me too. Why aren't we working towards that, instead of trying to cook up yet another hack on top of the current poor state of documentation?

https://github.com/D-Programming-Language/dlang.org/pull/271 consists mainly of a reorganization of the ddoc macros for PDF and ebook generation purposes, as well as helpers such as plaintext generator and "debugger". These are good starting points for anyone using ddoc for generating their own documentations. I was at it so I thought I'd improve on the bag-of-words-at-the-top morass, too. It only took a little time. That was apparently unsuccessful so I'll remove it from the pull request. https://github.com/D-Programming-Language/dlang.org/pull/267 is the pull request using ddox. That's a larger change of build tooling, which I plan to get to after 271 (with a revert to the bag-of-words) gets in. Andrei
Sep 16 2013
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 12:53 AM, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu wrote:
 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
 the top gets replaced by a slick drop-down. Once you jump to a name,
 you can go back by pressing the up arrow on the right or simply go to
 top.

I'm not sure this is an improvement, functionally. Finding the right item in much faster when you can see all items at once, and not lined up on only one direction.

Not sure what that's based on, but at least for me that only works up to a few words. For large modules that's hopeless. Just look at: http://dlang.org/phobos/std_datetime.html Can you really pick up the desired term? I think http://erdani.com/d/phobos/std_datetime.html is a real improvement over that (it also reduces the size of the list to the top-level ones, which helps).
 Also, Ctrl+F was more likely to find the link to
 the correct item before than now (and if you used your browser's inline
 search feature, then you could activate that link by pressing Enter).

 I think some kind of outline would be more useful.

Of course better designs are welcome. One possibility is an incremental search box.
 What happened with Ddox? This looks like an improvement in both function
 and aesthetics:

 http://vibed.org/temp/phobos/std/array.html

That would be a larger, future step. Walter noted some issues. Also things are a bit messed up right now - appender.html is missing, and the others don't expand D_RUN_CODE ARGS. Andrei
Sep 15 2013
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 11:22 AM, Joseph Rushton Wakeling wrote:
 On 15/09/13 19:47, Andrei Alexandrescu wrote:
 Not sure what that's based on, but at least for me that only works up
 to a few
 words. For large modules that's hopeless. Just look at:

 http://dlang.org/phobos/std_datetime.html

 Can you really pick up the desired term?

It's very unwieldy as is, but what if it was split up into a categorized table and cheat-sheet à la std.algorithm?

That would help either scheme. Again, my focus right now is to get rid of the bag of words without creating much aggravation. Andrei
Sep 15 2013
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, September 15, 2013 19:56:43 Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 17:47:06 UTC, Andrei Alexandrescu
 
 wrote:
 Not sure what that's based on, but at least for me that only
 works up to a few words. For large modules that's hopeless.
 Just look at:
 
 http://dlang.org/phobos/std_datetime.html
 
 Can you really pick up the desired term? I think
 http://erdani.com/d/phobos/std_datetime.html is a real
 improvement over that (it also reduces the size of the list to
 the top-level ones, which helps).

I believe that example is invalid. std.datetime is too big, as abundantly discussed previously. The module's documentation web page is over 130000 pixels long (for me)!

I've got the code split into a package on my box locally, but I need to finish fixing the documentation before I can create a pull request for it. Once I do that, the blob of links won't be so bad, since it'll be split across modules. Unfortunately, I'm quite slow in getting the job finished though as I'm quite busy at the moment. But what I think will really help deal with the blob of links for any module which isn't just a huge list of free functions (e.g. std.algorithm) would be if the links were actually hierarchical instead of treating all symbols like they are at the top level of the module rather than inside an enum or a struct or any other deeper scope. - Jonathan M Davis
Sep 15 2013
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 11:43 AM, Jonathan M Davis wrote:
 On Sunday, September 15, 2013 10:47:06 Andrei Alexandrescu wrote:
 On 9/15/13 12:53 AM, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu wrote:
 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
 the top gets replaced by a slick drop-down. Once you jump to a name,
 you can go back by pressing the up arrow on the right or simply go to
 top.

I'm not sure this is an improvement, functionally. Finding the right item in much faster when you can see all items at once, and not lined up on only one direction.

Not sure what that's based on, but at least for me that only works up to a few words. For large modules that's hopeless. Just look at: http://dlang.org/phobos/std_datetime.html Can you really pick up the desired term? I think http://erdani.com/d/phobos/std_datetime.html is a real improvement over that (it also reduces the size of the list to the top-level ones, which helps).

It's an improvement because it shows the top-level symbols only rather than putting all of the symbols inside of the types at the top level like the current links do. The fact that it's a drop-down hurts rather than helps. - Jonathan Davis

Probably I'll keep that in and drop the drop-down box. Andrei
Sep 15 2013
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 4:32 AM, Andrej Mitrovic wrote:
 On 9/15/13, Vladimir Panteleev <vladimir thecybershadow.net> wrote:
 I'm not sure this is an improvement, functionally.

It's not an improvement at all. Ctrl+F doesn't work with this (like you mentioned)

Again, that would be nicer done with an inline search box. We don't have to support the exact navigation mode in the new API. One obvious drawback of ^F working is that all symbols are there in sight. Vladimir, do you think you could easily implement such an incremental search box (with autocompletion)?
, and the items list is not even sorted
 alphabetically(!), so now we have to hunt down a symbol before we can
 jump to it. Also, what used to be just one step (click), now becomes
 more (click, scroll, click).

Sorting can be done, I thought natural order would impart some logic to the list.
 The categorical table at the top of
 http://dlang.org/phobos/std_algorithm.html is what I prefer the most,
 we could implemented this on other pages.

Sure. My goal with this upgrade is to get rid of the unsightly bag of words at the top of most pages. Andrei
Sep 15 2013
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-09-15 20:25, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
 Vladimir, do you think you could easily implement such an incremental
 search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers already have the function of searching within a page. An in-page search box is not a common UI element, users would need to learn to use it, and that's bad UX - we should stick to existing UI conventions to avoid forcing the users to think to get to their dox.

The Ruby documentation shows all core symbols (classes and methods) in one page with two filters. I like that. It's really useful when you know the name of the method/class you're looking for. It's also useful for guessing names. Like, is there a method called "sort". Then you find it you can figure out if it does what you think it will. -- /Jacob Carlborg
Sep 15 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 1:11 PM, Jacob Carlborg wrote:
 On 2013-09-15 20:25, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
 Vladimir, do you think you could easily implement such an incremental
 search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers already have the function of searching within a page. An in-page search box is not a common UI element, users would need to learn to use it, and that's bad UX - we should stick to existing UI conventions to avoid forcing the users to think to get to their dox.

The Ruby documentation shows all core symbols (classes and methods) in one page with two filters. I like that. It's really useful when you know the name of the method/class you're looking for. It's also useful for guessing names. Like, is there a method called "sort". Then you find it you can figure out if it does what you think it will.

Aha, I now remember - you mentioned this once, really like it. http://ruby-doc.org/core-1.9.3/ Andrei
Sep 15 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-09-16 03:54, Andrei Alexandrescu wrote:

 Aha, I now remember - you mentioned this once, really like it.

 http://ruby-doc.org/core-1.9.3/

I forgot the link, thanks. -- /Jacob Carlborg
Sep 15 2013
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 11:25 AM, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
 Vladimir, do you think you could easily implement such an incremental
 search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers already have the function of searching within a page.

But search boxes with autocomplete are vastly better. Andrei
Sep 15 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 11:49 PM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 01:44:34 UTC, Andrei Alexandrescu wrote:
 On 9/15/13 11:25 AM, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
 Vladimir, do you think you could easily implement such an incremental
 search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers already have the function of searching within a page.

But search boxes with autocomplete are vastly better.

Search boxes with autocomplete are vastly better than the classical Ctrl+F dialog as implemented in Internet Explorer 6. Most browsers currently implement Ctrl+F as incremental search, which highlights results as you type.

Ctrl-F does not progressively adjust the list of search candidates - it can highlight only what's actually visible in the document. Andrei
Sep 16 2013
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-09-16 06:50, H. S. Teoh wrote:

 What we need is not Yet Another Snake Oil Automagic Trick that will
 somehow magically make it all work. What we need is to sit down and put
 in the time to organize the module docs, grouping the symbols by logical
 categories (which a computer can't really figure out for us, unless we
 tag the code, which requires the same amount of effort anyway). I think
 std.algorithm and std.range's docs are a good model to follow. They set
 the minimum standard all Phobos docs should meet.

 Of course, we can also improve on them even more, by figuring out a way
 to prevent the DRY violation currently in std.algorithm (to add a new
 symbol, you now have to add it in 3 places: at the navigation table at
 the top, then in the cheatsheet, then the actual code in the module
 body). Maybe some kind of DDoc tag or UDA that can be collected by a
 postprocessing script that autogenerates the relevant tables based on
 what information is there? For example:

 	// Note: not actual syntax, I just made this up for illustration
 	// purposes:

 	/**
 	 *  category: searching
 	 *  cheatsheet: newHaystack = find(haystack, needle)
 	 *
 	 * Finds needle in haystack.
 	 * ...
 	 */
 	R find(R,S)(R haystack, S needle)
 	{
 		...
 	}

 The postprocessing tool would then collect all the  category tags and
  cheatsheet tags and assemble a table out of them, linked to the
 relevant symbols, and insert it at the top of the page. (Or, it could
 even split the files up into individual pages, which we've been talking
 about since, oh, last year?)

I think we should try and enhance the documentation generated automatically. Tagging and doing other things manually doesn't scale. This should only be used as a last option. -- /Jacob Carlborg
Sep 15 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-09-16 16:39, H. S. Teoh wrote:

 The problem is that Walter wants DDOC to be a generic macro-expansion
 system. Adding any further smarts to it would tie it down to D-specific
 functionality, which reduces the likelihood of it being accepted.

 But, you may be able to change his mind. :)

I just want to have good documentation for D. If Walter wants to create a competitor to Markdown, sure, but don't put it in D. -- /Jacob Carlborg
Sep 16 2013
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 6:20 AM, Wyatt wrote:
 On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu wrote:
 Sure. My goal with this upgrade is to get rid of the unsightly bag of
 words at the top of most pages.

a boxed out vertical list floating at the left. It worked fairly well at all sorts of browser sizes and required zero Javascript. (It will work even better when all the modules have introductory text as mentioned in another thread.</optimism>) I wonder if I should resurrect that branch? -Wyatt

Probably not. The consensus is to got the ddox way, and Walter and myself are on board with it. We're a bit concerned about switching to new tooling (dependencies, bus factor etc) but we think it's worth it. Andrei
Sep 16 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 7:30 AM, Wyatt wrote:
 On Monday, 16 September 2013 at 13:33:55 UTC, Andrei Alexandrescu wrote:
 Probably not. The consensus is to got the ddox way, and Walter and
 myself are on board with it. We're a bit concerned about switching to
 new tooling (dependencies, bus factor etc) but we think it's worth it.

Well, as long as it works (and works WELL) without Javascript, I guess that's a fine start. Though I have to admit the example linked above hurts my eyes. :( (So. Much. White.)

Which example? Are you referring to the extra spacing I added between symbols? Andrei
Sep 16 2013
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 6:05 AM, bearophile wrote:
 Andrej Mitrovic:

 The categorical table at the top of
 http://dlang.org/phobos/std_algorithm.html is what I prefer the most,
 we could implemented this on other pages.

Speaking of JavaScript, can't that table be shown using no JavaScript at all, generating it statically?

I don't think we use javascript there. Andrei
Sep 15 2013
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 12:48 PM, Dicebot wrote:
 On Sunday, 15 September 2013 at 19:29:56 UTC, Gary Willoughby wrote:
 Agreed. Sorry Andrei but this is not an improvement for usability. It
 disables being able to search the index via page search (Ctrl-F). Also
 i thought combobox navigation died out in the 90's!?

+1, combo boxes are terrible

It's not a combo box. Andrei
Sep 15 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 7:15 PM, Adam D. Ruppe wrote:
 On Monday, 16 September 2013 at 01:52:38 UTC, Andrei Alexandrescu wrote:
 It's not a combo box.

http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx check out the CBS_DROPDOWNLIST style.

Ha, it is. Thanks. Andrei
Sep 15 2013
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 9/15/2013 12:14 AM, Andrei Alexandrescu wrote:
 I hope I didn't mess up anything, reviews appreciated.

Can you build the .mobi file with these changes?
Sep 15 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 12:54 AM, Walter Bright wrote:
 On 9/15/2013 12:14 AM, Andrei Alexandrescu wrote:
 I hope I didn't mess up anything, reviews appreciated.

Can you build the .mobi file with these changes?

Yah, and a cursory skim suggests the generated document is okay. Andrei
Sep 15 2013
parent Walter Bright <newshound2 digitalmars.com> writes:
On 9/15/2013 10:49 AM, Andrei Alexandrescu wrote:
 On 9/15/13 12:54 AM, Walter Bright wrote:
 On 9/15/2013 12:14 AM, Andrei Alexandrescu wrote:
 I hope I didn't mess up anything, reviews appreciated.

Can you build the .mobi file with these changes?

Yah, and a cursory skim suggests the generated document is okay.

Great!
Sep 15 2013
prev sibling next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
Andrei Alexandrescu:

 http://erdani.com/d/phobos/std_array.html

One thing I'd like is for every function a link to the GitHub page & line of code where that Phobos function is defined. This is handy because I sometimes need to take a look at the implementation of functions I use. And I think that encourages people to fix the documentation faster, etc. Another small ddoc improvement, is for each of the recently introduced functions a small note that tells compiler version number when it appeared. Bye, bearophile
Sep 15 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 1:48 AM, bearophile wrote:
 Andrei Alexandrescu:

 http://erdani.com/d/phobos/std_array.html

One thing I'd like is for every function a link to the GitHub page & line of code where that Phobos function is defined. This is handy because I sometimes need to take a look at the implementation of functions I use. And I think that encourages people to fix the documentation faster, etc.

That would be nice. It would require either the mythical compiler-as-library or the simpler approach of making the file and line of each symbol available as ddoc symbols.
 Another small ddoc improvement, is for each of the recently introduced
 functions a small note that tells compiler version number when it appeared.

Interesting. That would be some serious work though. Andrei
Sep 15 2013
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 9/15/2013 10:52 AM, Andrei Alexandrescu wrote:
 the simpler approach of making the file and line of each symbol available as
 ddoc symbols.

I think that would make for a nice enhancement to ddoc. Enhancement request to bugzilla?
Sep 15 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 11:04 AM, Walter Bright wrote:
 On 9/15/2013 10:52 AM, Andrei Alexandrescu wrote:
 the simpler approach of making the file and line of each symbol
 available as
 ddoc symbols.

I think that would make for a nice enhancement to ddoc. Enhancement request to bugzilla?

http://d.puremagic.com/issues/show_bug.cgi?id=11050 Andrei
Sep 16 2013
prev sibling next sibling parent "Paolo Invernizzi" <paolo.invernizzi gmail.com> writes:
On Sunday, 15 September 2013 at 07:53:23 UTC, Vladimir Panteleev 
wrote:
 On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei 
 Alexandrescu wrote:
 Check out the new navigation at 
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" 
 list as the top gets replaced by a slick drop-down. Once you 
 jump to a name, you can go back by pressing the up arrow on 
 the right or simply go to top.

I'm not sure this is an improvement, functionally. Finding the right item in much faster when you can see all items at once, and not lined up on only one direction. Also, Ctrl+F was more likely to find the link to the correct item before than now (and if you used your browser's inline search feature, then you could activate that link by pressing Enter). I think some kind of outline would be more useful. What happened with Ddox? This looks like an improvement in both function and aesthetics: http://vibed.org/temp/phobos/std/array.html

I tend to agree with Vladimir... - Paolo
Sep 15 2013
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-09-15 09:14, Andrei Alexandrescu wrote:
 I finally gathered strength to rebase
 https://github.com/D-Programming-Language/dlang.org/pull/271 manually,
 which was every bit as involved as I feared.

 I hope I didn't mess up anything, reviews appreciated.

 That diff includes a new page navigation scheme. (Wasn't the main
 purpose of the diff but found it a nice perk.) I see it as a
 transitional stage toward the larger transition to one-page-per-entity
 that Snke has proposed.

 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
 the top gets replaced by a slick drop-down. Once you jump to a name, you
 can go back by pressing the up arrow on the right or simply go to top.

I don't like that it requires JavaScript. -- /Jacob Carlborg
Sep 15 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-09-15 12:45, Iain Buclaw wrote:

 I  could give it a test using librejs to make sure that the site isn't
 using non-free JS.

I don't like that it uses JavaScript regardless if it's free or not. By default I run with JavaScript off. Then I enable it on sites I use often that really needs it. -- /Jacob Carlborg
Sep 15 2013
prev sibling next sibling parent Iain Buclaw <ibuclaw ubuntu.com> writes:
--047d7b6d972654cdc204e669c808
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Sep 15, 2013 11:25 AM, "Jacob Carlborg" <doob me.com> wrote:
 On 2013-09-15 09:14, Andrei Alexandrescu wrote:
 I finally gathered strength to rebase
 https://github.com/D-Programming-Language/dlang.org/pull/271 manually,
 which was every bit as involved as I feared.

 I hope I didn't mess up anything, reviews appreciated.

 That diff includes a new page navigation scheme. (Wasn't the main
 purpose of the diff but found it a nice perk.) I see it as a
 transitional stage toward the larger transition to one-page-per-entity
 that S=F6nke has proposed.

 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
 the top gets replaced by a slick drop-down. Once you jump to a name, you
 can go back by pressing the up arrow on the right or simply go to top.

I don't like that it requires JavaScript.

I could give it a test using librejs to make sure that the site isn't using non-free JS. Regards --=20 Iain Buclaw *(p < e ? p++ : p) =3D (c & 0x0f) + '0'; --047d7b6d972654cdc204e669c808 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable <p><br> On Sep 15, 2013 11:25 AM, &quot;Jacob Carlborg&quot; &lt;<a href=3D"mailto:= doob me.com">doob me.com</a>&gt; wrote:<br> &gt;<br> &gt; On 2013-09-15 09:14, Andrei Alexandrescu wrote:<br> &gt;&gt;<br> &gt;&gt; I finally gathered strength to rebase<br> &gt;&gt; <a href=3D"https://github.com/D-Programming-Language/dlang.org/pul= l/271">https://github.com/D-Programming-Language/dlang.org/pull/271</a> man= ually,<br> &gt;&gt; which was every bit as involved as I feared.<br> &gt;&gt;<br> &gt;&gt; I hope I didn&#39;t mess up anything, reviews appreciated.<br> &gt;&gt;<br> &gt;&gt; That diff includes a new page navigation scheme. (Wasn&#39;t the m= ain<br> &gt;&gt; purpose of the diff but found it a nice perk.) I see it as a<br> &gt;&gt; transitional stage toward the larger transition to one-page-per-en= tity<br> &gt;&gt; that S=F6nke has proposed.<br> &gt;&gt;<br> &gt;&gt; Check out the new navigation at<br> &gt;&gt; <a href=3D"http://erdani.com/d/phobos/std_array.html">http://erdan= i.com/d/phobos/std_array.html</a>. The ugly &quot;Jump to&quot; list as<br> &gt;&gt; the top gets replaced by a slick drop-down. Once you jump to a nam= e, you<br> &gt;&gt; can go back by pressing the up arrow on the right or simply go to = top.<br> &gt;<br> &gt;<br> &gt; I don&#39;t like that it requires JavaScript.<br> &gt;<br></p> <p>I=A0 could give it a test using librejs to make sure that the site isn&#= 39;t using non-free JS. <br></p> <p>Regards<br> -- <br> Iain Buclaw</p> <p>*(p &lt; e ? p++ : p) =3D (c &amp; 0x0f) + &#39;0&#39;;</p> --047d7b6d972654cdc204e669c808--
Sep 15 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 9/15/13, Vladimir Panteleev <vladimir thecybershadow.net> wrote:
 I'm not sure this is an improvement, functionally.

It's not an improvement at all. Ctrl+F doesn't work with this (like you mentioned), and the items list is not even sorted alphabetically(!), so now we have to hunt down a symbol before we can jump to it. Also, what used to be just one step (click), now becomes more (click, scroll, click). The categorical table at the top of http://dlang.org/phobos/std_algorithm.html is what I prefer the most, we could implemented this on other pages.
Sep 15 2013
prev sibling next sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
Andrej Mitrovic:

 The categorical table at the top of
 http://dlang.org/phobos/std_algorithm.html is what I prefer the 
 most, we could implemented this on other pages.

Speaking of JavaScript, can't that table be shown using no JavaScript at all, generating it statically? Bye, bearophile
Sep 15 2013
prev sibling next sibling parent "Peter Alexander" <peter.alexander.au gmail.com> writes:
On Sunday, 15 September 2013 at 07:53:23 UTC, Vladimir Panteleev 
wrote:
 I'm not sure this is an improvement, functionally.

 ...

 What happened with Ddox? This looks like an improvement in both 
 function and aesthetics:

 http://vibed.org/temp/phobos/std/array.html

+1 The blob of links was bad, but a combo box isn't really much better. Ddox is superior.
Sep 15 2013
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 15 September 2013 at 13:05:34 UTC, bearophile wrote:
 Speaking of JavaScript, can't that table be shown using no 
 JavaScript at all, generating it statically?

yup. http://arsdnet.net/d-web-site/std_datetime.html http://arsdnet.net/d-web-site/std_stdio.html I did this I think almost two years ago now so the program probably needs updating, but if someone wanted to integrate it into the website build process it is simple enough to run: http://arsdnet.net/d-web-site/improveddoc.d (yes, it would be nice if ddoc itself did this kind of thing, but still doing it ahead of time is better than doing it in js)
Sep 15 2013
prev sibling next sibling parent Joseph Rushton Wakeling <joseph.wakeling webdrake.net> writes:
On 15/09/13 13:32, Andrej Mitrovic wrote:
 It's not an improvement at all. Ctrl+F doesn't work with this (like
 you mentioned), and the items list is not even sorted
 alphabetically(!), so now we have to hunt down a symbol before we can
 jump to it. Also, what used to be just one step (click), now becomes
 more (click, scroll, click).

Agree, being able to use Ctrl+F is crucial. Anything that kills that is a problem.
 The categorical table at the top of
 http://dlang.org/phobos/std_algorithm.html is what I prefer the most,
 we could implemented this on other pages.

I seem to recall that table having some issues, e.g. stuff that appeared in the table but no longer appeared elsewhere in the docs, because it had been deprecated. Was that because it's hand-written rather than autogenerated? In any case, it's a nice design -- the combination of the category/functions summary table at the top, and the cheat sheet further down, gives a very good overview of the module. If that sort of category table and cheat sheet could be automatically and statically generated as part of the docs build process, it would be great. It's definitely preferable to avoid JavaScript as much as possible, not just because some people prefer to disable it but also because if the Ddoc build process can create smart module summaries in this way, it means that everyone using Ddoc can use that for their projects.
Sep 15 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Sunday, 15 September 2013 at 17:47:06 UTC, Andrei Alexandrescu 
wrote:
 Not sure what that's based on, but at least for me that only 
 works up to a few words. For large modules that's hopeless. 
 Just look at:

 http://dlang.org/phobos/std_datetime.html

 Can you really pick up the desired term? I think 
 http://erdani.com/d/phobos/std_datetime.html is a real 
 improvement over that (it also reduces the size of the list to 
 the top-level ones, which helps).

I believe that example is invalid. std.datetime is too big, as abundantly discussed previously. The module's documentation web page is over 130000 pixels long (for me)! For the example you presented (std.array), my opinion is as aforementioned.
 http://vibed.org/temp/phobos/std/array.html

That would be a larger, future step. Walter noted some issues. Also things are a bit messed up right now - appender.html is missing, and the others don't expand D_RUN_CODE ARGS.

I believe this is an old proof-of-concept. Wasn't there a more recent and polished version in a pull request?
Sep 15 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Sunday, 15 September 2013 at 17:20:16 UTC, Walter Bright wrote:
 On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in 
 both function and
 aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

It actually does. It simply shows stripped definition of the symbol which includes all of those.
Sep 15 2013
prev sibling next sibling parent Joseph Rushton Wakeling <joseph.wakeling webdrake.net> writes:
On 15/09/13 19:47, Andrei Alexandrescu wrote:
 Not sure what that's based on, but at least for me that only works up to a few
 words. For large modules that's hopeless. Just look at:

 http://dlang.org/phobos/std_datetime.html

 Can you really pick up the desired term?

It's very unwieldy as is, but what if it was split up into a categorized table and cheat-sheet à la std.algorithm?
Sep 15 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu 
wrote:
 Vladimir, do you think you could easily implement such an 
 incremental search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers already have the function of searching within a page. An in-page search box is not a common UI element, users would need to learn to use it, and that's bad UX - we should stick to existing UI conventions to avoid forcing the users to think to get to their dox. I think an index like the one std.algorithm has, and that ddox attempts to generate automatically, is really the best solution from all sides. It provides a birds-eye view of the whole module useful to new users; it allows quickly finding the sought function through its table layout and categorization; and, the first Ctrl+F hit for a symbol name will likely be a link to the symbol, with a short synopsis nearby it. It's pretty hard to beat. I think this is the direction we need, and that it's not worth considerably changing things with interim solutions (which will impact D users who consult the documentation often) that are more of a trade-off rather than an improvement. Implementation-wise: I assume Ddox has failed to be integrated because it was a server-side process. It also places each symbol in its own file, which will break existing links. Perhaps it be feasible to reimplement only its basic index-table functionality in JavaScript, to replace the word-blob/dropdown? Symbol documentation could contain macros which render to invisible HTML, which is picked up by the index-table JS for metadata like categorization.
Sep 15 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Sunday, 15 September 2013 at 18:25:03 UTC, Vladimir Panteleev 
wrote:
 Implementation-wise:

 I assume Ddox has failed to be integrated because it was a 
 server-side process. It also places each symbol in its own 
 file, which will break existing links. Perhaps it be feasible 
 to reimplement only its basic index-table functionality in 
 JavaScript, to replace the word-blob/dropdown?

Admitting that server-side process has failed and moving to JS is akin to accepting failure to do proper documentation at all. Static documentation which requires JS to be conveniently usable is disaster.
Sep 15 2013
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, September 15, 2013 19:35:06 Joseph Rushton Wakeling wrote:
 On 15/09/13 13:32, Andrej Mitrovic wrote:
 It's not an improvement at all. Ctrl+F doesn't work with this (like
 you mentioned), and the items list is not even sorted
 alphabetically(!), so now we have to hunt down a symbol before we can
 jump to it. Also, what used to be just one step (click), now becomes
 more (click, scroll, click).

Agree, being able to use Ctrl+F is crucial. Anything that kills that is a problem.

Yeah. It feels a lot like when you can't resize a Window like Microsoft won't let you done with the dialog for setting environment variables. When I mess with my PATH in Windows, I typically have to copy it elsewhere, edit it, and copy it back. This feels a lot like that except that it relates only to finding data and not editing it. I would much rather have the list of links at the top that we have right now. Really, the main problems with the current list of links relate to the fact that it completely ignores scoping. 1. All of the functions with the same name end up with the same anchor even if they're inside a struct or class (so std.datetime ends up with 3 day links - for SysTime, DateTime, and Date - and they all end up just going to SysTime, because it just so happens to be first). 2. You just get a long list of functions with no organization and no indication of what type (if any) they belong to. You should see something like SysTime.year, DateTime.year, Date.year rather than year three times in a row. And the links as a whole really should be organized by the type that they're in (e.g. all of the SysTime functions would be grouped together and separate from functions in the module which are in other types or which are free). Right now, all we get is a big long list with no hierarchy whatsoever. The case of std.algorithm shows the need to organize free functions based on what they do, but I think that that pretty much has to be done by hand, and if it's really needed it, it implies that separating the module (as we've discussed) is probably a good idea. The hierarchy of the functions themselves however _is_ something that can be done programmatically and would really help any module which has any user-defined types in it. - Jonathan M Davis
Sep 15 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Sunday, 15 September 2013 at 18:31:16 UTC, Dicebot wrote:
 On Sunday, 15 September 2013 at 18:25:03 UTC, Vladimir 
 Panteleev wrote:
 I assume Ddox has failed to be integrated because it was a 
 server-side process. It also places each symbol in its own 
 file, which will break existing links. Perhaps it be feasible 
 to reimplement only its basic index-table functionality in 
 JavaScript, to replace the word-blob/dropdown?

Admitting that server-side process has failed and moving to JS is akin to accepting failure to do proper documentation at all. Static documentation which requires JS to be conveniently usable is disaster.

Using JS has several disadvantages, but would require much less effort for everyone involved. (If effort is not a factor, how come we don't have Ddox on dlang.org yet?)
Sep 15 2013
prev sibling next sibling parent Iain Buclaw <ibuclaw ubuntu.com> writes:
On 15 September 2013 19:22, Joseph Rushton Wakeling
<joseph.wakeling webdrake.net> wrote:
 On 15/09/13 19:47, Andrei Alexandrescu wrote:
 Not sure what that's based on, but at least for me that only works up to=


 few
 words. For large modules that's hopeless. Just look at:

 http://dlang.org/phobos/std_datetime.html

 Can you really pick up the desired term?

It's very unwieldy as is, but what if it was split up into a categorized table and cheat-sheet =E0 la std.algorithm?

I'm sure you could make a t-shirt out of such a cheat-sheet. --=20 Iain Buclaw *(p < e ? p++ : p) =3D (c & 0x0f) + '0';
Sep 15 2013
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, September 15, 2013 11:02:11 Andrei Alexandrescu wrote:
 One obvious
 drawback of ^F working is that all symbols are there in sight.

I actually consider it a serious drawback when they're _not_ in sight. The problem that we have is not that all of the symbols are shown as links but how they're organized. Trying to hide them doesn't help. - Jonathan m Davis
Sep 15 2013
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, September 15, 2013 10:47:06 Andrei Alexandrescu wrote:
 On 9/15/13 12:53 AM, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei Alexandrescu wrote:
 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
 the top gets replaced by a slick drop-down. Once you jump to a name,
 you can go back by pressing the up arrow on the right or simply go to
 top.

I'm not sure this is an improvement, functionally. Finding the right item in much faster when you can see all items at once, and not lined up on only one direction.

Not sure what that's based on, but at least for me that only works up to a few words. For large modules that's hopeless. Just look at: http://dlang.org/phobos/std_datetime.html Can you really pick up the desired term? I think http://erdani.com/d/phobos/std_datetime.html is a real improvement over that (it also reduces the size of the list to the top-level ones, which helps).

It's an improvement because it shows the top-level symbols only rather than putting all of the symbols inside of the types at the top level like the current links do. The fact that it's a drop-down hurts rather than helps. - Jonathan Davis
Sep 15 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 9/15/13, Jonathan M Davis <jmdavisProg gmx.com> wrote:
 Yeah. It feels a lot like when you can't resize a Window like Microsoft
 won't
 let you done with the dialog for setting environment variables. When I mess
 with my PATH in Windows, I typically have to copy it elsewhere, edit it, and
 copy it back.

P.S. you may want to give this app a shot: http://www.rapidee.com/en/screenshots
Sep 15 2013
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu 
wrote:
 Vladimir, do you think you could easily implement such an 
 incremental search box (with autocompletion)?

One of the things that pisses me off most about facebook now is they hooked the / key to go into their own search, thereby breaking the browser's search hotkey (which i use often) and my expectations. Let's let the browser do what it does and not get too smart about it.
Sep 15 2013
prev sibling next sibling parent "Gary Willoughby" <dev nomad.so> writes:
On Sunday, 15 September 2013 at 07:53:23 UTC, Vladimir Panteleev 
wrote:
 On Sunday, 15 September 2013 at 07:14:15 UTC, Andrei 
 Alexandrescu wrote:
 Check out the new navigation at 
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" 
 list as the top gets replaced by a slick drop-down. Once you 
 jump to a name, you can go back by pressing the up arrow on 
 the right or simply go to top.

I'm not sure this is an improvement, functionally. Finding the right item in much faster when you can see all items at once, and not lined up on only one direction. Also, Ctrl+F was more likely to find the link to the correct item before than now (and if you used your browser's inline search feature, then you could activate that link by pressing Enter). I think some kind of outline would be more useful. What happened with Ddox? This looks like an improvement in both function and aesthetics: http://vibed.org/temp/phobos/std/array.html

Agreed. Sorry Andrei but this is not an improvement for usability. It disables being able to search the index via page search (Ctrl-F). Also i thought combobox navigation died out in the 90's!? Seriously though, the navigation needs to be available no matter where you are on the page. For me this is a huge step backwards, you've effectively hidden the navigation and introduced a dependency on javascript. Is there any chance some money can be spent to employ a good web developer to develop a nice user friendly site? IMHO the website really lets D down and to be honest looks very amateurish.
Sep 15 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Sunday, 15 September 2013 at 19:29:56 UTC, Gary Willoughby 
wrote:
 Agreed. Sorry Andrei but this is not an improvement for 
 usability. It disables being able to search the index via page 
 search (Ctrl-F). Also i thought combobox navigation died out in 
 the 90's!?

+1, combo boxes are terrible Polishing ddox is much more promising approach.
Sep 15 2013
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2013-09-15 09:14, Andrei Alexandrescu wrote:
 I finally gathered strength to rebase
 https://github.com/D-Programming-Language/dlang.org/pull/271 manually,
 which was every bit as involved as I feared.

 I hope I didn't mess up anything, reviews appreciated.

 That diff includes a new page navigation scheme. (Wasn't the main
 purpose of the diff but found it a nice perk.) I see it as a
 transitional stage toward the larger transition to one-page-per-entity
 that Snke has proposed.

 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list as
 the top gets replaced by a slick drop-down. Once you jump to a name, you
 can go back by pressing the up arrow on the right or simply go to top.

Can't we just use something like CandyDoc. This requires JavaScript but it actually improves the documentation. The version used by Tango looks like this: http://dsource.org/projects/tango/docs/current/ It has a tree which list all packages and modules and a different tree which list the symbols in a module. It also has a filter for the tree. Simple and useable. -- /Jacob Carlborg
Sep 15 2013
prev sibling next sibling parent "F i L" <witte2008 gmail.com> writes:
Andrei Alexandrescu wrote:
 Of course better designs are welcome. One possibility is an 
 incremental search box.

Best solution, IMO, would be using a categorized jump-list on the left that scrolls separately from the actual documentation (or each item could have it's own page). That way you get and "overview at a glance" of everything in the module, regardless of where you are. Similar to how MSDN works.
Sep 15 2013
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 16 September 2013 at 01:52:38 UTC, Andrei Alexandrescu 
wrote:
 It's not a combo box.

http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx check out the CBS_DROPDOWNLIST style. Or http://harmattan-dev.nokia.com/docs/library/html/qt4/qcombobox.html#details BTW MSDN has something the D docs are really lacking: the conceptual overviews. What are controls? http://msdn.microsoft.com/en-us/library/windows/desktop/bb773173%28v=vs.85%29.aspx What options are available? http://msdn.microsoft.com/en-us/library/windows/desktop/bb773169%28v=vs.85%29.aspx Big picture, what is a combo box? http://msdn.microsoft.com/en-us/library/windows/desktop/bb775792%28v=vs.85%29.aspx Can you tell me more? http://msdn.microsoft.com/en-us/library/windows/desktop/bb775791%28v=vs.85%29.aspx What about a complete example program? http://msdn.microsoft.com/en-us/library/windows/desktop/hh298364%28v=vs.85%29.aspx When I was new with Windows, half my programs were just bits of Microsoft examples (back then it was a .hlp file rather than a website though :) ) copy/pasted together. They're still useful today too. Of course, D doesn't have the kind of resources Microsoft has, and those Windows documents were written over many years. But we should start striving to at least offer: 1) conceptual overviews discussing the big idea and pointing to relevant modules. e.g. "Strings" or "Ranges". Put them right in the Phobos docs linked in all places like MSDN does with the "Related Topics" at the bottom of every page. 2) a big picture module overview on each and every one of them. Could just be a paragraph or two. Some already have this. 3) Collecting more full example programs. The samples directory in the dmd zip should be easily viewable online and open to more submissions. Is it on github?
Sep 15 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sun, Sep 15, 2013 at 12:14:14AM -0700, Andrei Alexandrescu wrote:
 I finally gathered strength to rebase
 https://github.com/D-Programming-Language/dlang.org/pull/271
 manually, which was every bit as involved as I feared.
 
 I hope I didn't mess up anything, reviews appreciated.
 
 That diff includes a new page navigation scheme. (Wasn't the main
 purpose of the diff but found it a nice perk.) I see it as a
 transitional stage toward the larger transition to
 one-page-per-entity that Snke has proposed.
 
 Check out the new navigation at
 http://erdani.com/d/phobos/std_array.html. The ugly "Jump to" list
 as the top gets replaced by a slick drop-down. Once you jump to a
 name, you can go back by pressing the up arrow on the right or
 simply go to top.

Not bad. I'd suggest replacing the default selection on the "slick" drop-down with a more helpful message, like "choose a declaration..." or something like that, instead of just a down arrow with lots of trailing blank space. The one thing that I do NOT like, is the lack of indentation for aggregate members. For example, struct Appender's members aren't visually differentiated from other module-level symbols, which makes the documentation VERY confusing. For reference, this is the format I use for my own ddocs: http://eusebeia.dyndns.org/~hsteoh/tmp/doc/mda which are generated by the minimalistic macros here: https://github.com/quickfur/Viola-ddoc-macros The nesting of various identifiers are deliberately made very explicit visually (see, for example, the docs for `struct IndexRange`), so there's no confusion as to what symbol belongs in which aggregate. I think this is indispensible for the docs to be useful to newbies. T -- Error: Keyboard not attached. Press F1 to continue. -- Yoon Ha Lee, CONLANG
Sep 15 2013
prev sibling next sibling parent "deadalnix" <deadalnix gmail.com> writes:
On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:
 Am 15.09.2013 19:20, schrieb Walter Bright:
 On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in 
 both
 function and
 aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

I'm sold, that is awesome !
Sep 15 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Sun, Sep 15, 2013 at 11:40:28AM -0700, Jonathan M Davis wrote:
 On Sunday, September 15, 2013 11:02:11 Andrei Alexandrescu wrote:
 One obvious drawback of ^F working is that all symbols are there in
 sight.

I actually consider it a serious drawback when they're _not_ in sight. The problem that we have is not that all of the symbols are shown as links but how they're organized. Trying to hide them doesn't help.

+1. What we need is not Yet Another Snake Oil Automagic Trick that will somehow magically make it all work. What we need is to sit down and put in the time to organize the module docs, grouping the symbols by logical categories (which a computer can't really figure out for us, unless we tag the code, which requires the same amount of effort anyway). I think std.algorithm and std.range's docs are a good model to follow. They set the minimum standard all Phobos docs should meet. Of course, we can also improve on them even more, by figuring out a way to prevent the DRY violation currently in std.algorithm (to add a new symbol, you now have to add it in 3 places: at the navigation table at the top, then in the cheatsheet, then the actual code in the module body). Maybe some kind of DDoc tag or UDA that can be collected by a postprocessing script that autogenerates the relevant tables based on what information is there? For example: // Note: not actual syntax, I just made this up for illustration // purposes: /** * category: searching * cheatsheet: newHaystack = find(haystack, needle) * * Finds needle in haystack. * ... */ R find(R,S)(R haystack, S needle) { ... } The postprocessing tool would then collect all the category tags and cheatsheet tags and assemble a table out of them, linked to the relevant symbols, and insert it at the top of the page. (Or, it could even split the files up into individual pages, which we've been talking about since, oh, last year?) T -- I think the conspiracy theorists are out to get us...
Sep 15 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Sep 16, 2013 at 06:15:35AM +0200, deadalnix wrote:
 On Sunday, 15 September 2013 at 18:38:54 UTC, Snke Ludwig wrote:
Am 15.09.2013 19:20, schrieb Walter Bright:
On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
What happened with Ddox? This looks like an improvement in both
function and aesthetics:

http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

I'm sold, that is awesome !

Me too. Why aren't we working towards that, instead of trying to cook up yet another hack on top of the current poor state of documentation? T -- The day Microsoft makes something that doesn't suck is probably the day they start making vacuum cleaners... -- Slashdotter
Sep 15 2013
prev sibling next sibling parent "Joshua Niehus" <jm.niehus gmail.com> writes:
On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig wrote:
 Just as a reminder, this is the current version:
 http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

This is way better +1
Sep 15 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 01:44:34 UTC, Andrei Alexandrescu 
wrote:
 On 9/15/13 11:25 AM, Vladimir Panteleev wrote:
 On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei 
 Alexandrescu wrote:
 Vladimir, do you think you could easily implement such an 
 incremental
 search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers already have the function of searching within a page.

But search boxes with autocomplete are vastly better.

Search boxes with autocomplete are vastly better than the classical Ctrl+F dialog as implemented in Internet Explorer 6. Most browsers currently implement Ctrl+F as incremental search, which highlights results as you type. These have the advantage that simply typing the term will 1) scroll down and highlight the term, bringing into view the symbol's documentation on a "hit", and 2) highlight all occurrences of the term on the visible page, making e.g. overloads and related symbols immediately noticeable. You also don't need to focus a search box immediately after arriving at a page. Anyway, no reason we can't have both. The CHM build tool generates an index of all Phobos/Druntime symbols and D keywords, and I think the dman tool does something similar as well - perhaps it could be used for a site-wide searchbox with autocomplete.
Sep 15 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 10:47:25 UTC, Andrei Alexandrescu 
wrote:
 Ctrl-F does not progressively adjust the list of search 
 candidates - it can highlight only what's actually visible in 
 the document.

If the page is property laid out, this is not an issue. http://dump.thecybershadow.net/269d31b27d121d13ceb51dc308b89b69/00000088.png http://dump.thecybershadow.net/9b9e677a061087ef9486288eeaaccdc1/00000087.png
Sep 16 2013
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
[snip]

Got destroyed so I changed the jump-to list back, added a couple of 
minor improvements until we land 
https://github.com/D-Programming-Language/dlang.org/pull/267.

http://erdani.com/d/phobos/std_array.html


Andrei
Sep 16 2013
next sibling parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 12:59:28 UTC, Andrei Alexandrescu 
wrote:
 On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
 [snip]

 Got destroyed so I changed the jump-to list back, added a 
 couple of minor improvements until we land 
 https://github.com/D-Programming-Language/dlang.org/pull/267.

 http://erdani.com/d/phobos/std_array.html

What happened to the margins/padding? The assocArray example block shouldn't be glued to the uninitializedArray signature.
Sep 16 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 6:08 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 12:59:28 UTC, Andrei Alexandrescu wrote:
 On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
 [snip]

 Got destroyed so I changed the jump-to list back, added a couple of
 minor improvements until we land
 https://github.com/D-Programming-Language/dlang.org/pull/267.

 http://erdani.com/d/phobos/std_array.html

What happened to the margins/padding? The assocArray example block shouldn't be glued to the uninitializedArray signature.

Must have fallen through the cracks. Any chance you'd spot it in the pull request? I'll try the same when I'll find some time. Andrei
Sep 16 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
 What before was <dd>, now is <div class="d_decl_dd"> (and the margin was
 a dd style). Why this change? You can apply any properties of one to the
 other through CSS.

Great, thanks. Now fixed. My intent was to use <div> and <span> for styling ddoc elements to the extent possible, in order to make styling as flexible as possible. But I forgot to give the appropriate style to d_decl_dd (hopefully not others). Destroy: http://erdani.com/d/phobos/std_array.html Andrei
Sep 16 2013
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 8:55 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 15:22:50 UTC, Andrei Alexandrescu wrote:
 On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
 What before was <dd>, now is <div class="d_decl_dd"> (and the margin was
 a dd style). Why this change? You can apply any properties of one to the
 other through CSS.

Great, thanks. Now fixed. My intent was to use <div> and <span> for styling ddoc elements to the extent possible, in order to make styling as flexible as possible.

Although bordering on nitpicking, I'll mention that this is not a good change.

I'm here to learn.
 It is recommended to use the appropriate HTML elements for their
 semantic meaning.

[citation needed] On the contrary, from what I've read in LaTeX and typography is that you want to keep formatting semantics high level, e.g. "This is a chapter title" as opposed to "this is heading text" or (worse) "this is large text with large spacing".
 <dl> is a definition list, which nicely fits
 documenting a list of entities.

It is, but it seems to me the more specific "list of symbols introduced" is better. In this case the distinction is actually material because we have one style file for both Phobos and the larger dlang.org, and we may want to format regular <dd> differently from Phobos symbols description. This seems to be a Good Thing (tm).
 HTML5 even introduced additional HTML
 tags, such as <nav>.

Even better. The more semantic the better, but actual documents always have their own higher-level semantics.
 Styling is not a problem, since you can use CSS to
 remove the default styles from practically any layout tag, making it
 behave like <span> or <div>.

Actually as I noted above that's an issue because we share the same style file between dlang.org and phobos. Of course, we could have two files, but I don't find using classes a shameful alternative.
 If it's not too much effort, I'd revert this change, however this is
 more of a question of principle than practicality.

I think this change makes things better, but am listening to arguments because I'm not an expert. Andrei
Sep 16 2013
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 9:28 AM, Adam D. Ruppe wrote:
 On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu wrote:
 <dl> is a definition list, which nicely fits
 documenting a list of entities.

It is, but it seems to me the more specific "list of symbols introduced" is better.

<dl class="d_decl"> <dd class="d_class"> or whatever Use the closest tag name to what it is, and then put a class in there to get more specific.

Why? To me it seems it makes no difference. Both are phrases that mean "this is a D declaration". Andrei
Sep 16 2013
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 9:30 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu wrote:
 [citation needed]

Sure, here you go: https://en.wikipedia.org/wiki/Semantic_HTML

I don't find disagreement with what I said.
 On the contrary, from what I've read in LaTeX and typography is that
 you want to keep formatting semantics high level, e.g. "This is a
 chapter title" as opposed to "this is heading text" or (worse) "this
 is large text with large spacing".

Well, the big difference with TeX and HTML is that with *TeX, you distribute the output, whereas with HTML, you distribute the source code - which can be interpreted by user agents other than web browsers rendering the page on a computer display.
 <dl> is a definition list, which nicely fits
 documenting a list of entities.

It is, but it seems to me the more specific "list of symbols introduced" is better.

You could use both (<dl class="d_decl">) if you like.

I guess '<dl class="d_decl">' is one iota more specific than '<div class="d_decl">' and would help if one wanted to view the HTML without any accompanying CSS. I doubt this is a goal to pursue.
 In this case the distinction is actually material because we have one
 style file for both Phobos and the larger dlang.org, and we may want
 to format regular <dd> differently from Phobos symbols description.
 This seems to be a Good Thing (tm).

Good thing for that C in CSS! :) If you add a class to the <html> or <body> tag (or any other tag that wraps all symbol definitions), which only appears on Phobos documentation pages, you can create a CSS rule that only applies to those pages. E.g.: HTML: <body class="library_dox"> ... <dd> CSS: .library_dox dd { /* applies only to dd tags in library dox pages */ }

Nice, but what I see here is "different", not "better". Andrei
Sep 16 2013
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 10:07 AM, H. S. Teoh wrote:
 I can attest to that. I'm on another mailing list where one of the list
 members is sight-impaired, and she complains about how some websites
 (i.e. those that suffer from heavy divitis and spanitis) simply can't be
 read in any sane way by the screen reader. Using built-in semantic tags
 like <dl> can make a world of difference for these users, since the
 screen reader has no idea what class="d_decl" means, but it *does* know
 what <dl> means. I wouldn't be so quick to dismiss it.

OK I went back to dl/dt as shown in http://goo.gl/DzW2iI. However, when I tried to redefine DDOC_DECL_DD from DDOC_DECL_DD = $(DIVC d_decl_dd, $0) to DDOC_DECL_DD = $(DDC d_decl_dd, $0) I got bad rendering problems. What could be the matter? Is it because of nesting? Thanks, Andrei
Sep 16 2013
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
(After traveling on Sunday and Monday, and after wondering why people 
still argue with me after I'd sent the message below, I opened my laptop 
to find it, still unsent, in Drafts. I must have forgotten to send it, 
or sending failed... sorry.)

On 9/16/13 10:07 AM, H. S. Teoh wrote:
 I can attest to that. I'm on another mailing list where one of the list
 members is sight-impaired, and she complains about how some websites
 (i.e. those that suffer from heavy divitis and spanitis) simply can't be
 read in any sane way by the screen reader. Using built-in semantic tags
 like <dl> can make a world of difference for these users, since the
 screen reader has no idea what class="d_decl" means, but it *does* know
 what <dl> means. I wouldn't be so quick to dismiss it.

OK, I think this is a solid argument (Adam also made it but I hadn't grokked it). So the idea here is that the specific HTML attributes do have meaning to the renderer that are difficult or impossible to specify in, or infer from, the stylesheet. A google search for divitis spanitis destroyed my former opinion. Andrei
Sep 17 2013
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2013-09-16 18:22, Andrei Alexandrescu wrote:

 [citation needed]

http://en.wikipedia.org/wiki/Semantic_HTML
 On the contrary, from what I've read in LaTeX and typography is that you
 want to keep formatting semantics high level, e.g. "This is a chapter
 title" as opposed to "this is heading text" or (worse) "this is large
 text with large spacing".

This is not LaTeX. When using the proper tags you're adding semantic meaning to your content. Example, a proper table with an header and footer should look like this: <table> <thead> <tr> <th>Header</th> <th>Header 2</th> </tr> </thead> <tfoot> <tr> <td>Footer data</th> <td>Footer data 2</th> </tr> </tfoot> <tbody> <tr> <td>Data</td> <td>Data 2</td> </tr> </tbody> </table> The reason for adding proper tags like "thead", "tfoot" and "tbody" is it gives semantic meaning to the content. A browser can choose to scroll the content in "tbody" while having the content in "thead" and "tfoot". The same idea can be applied to navigation as well. Using the "nav" tag a browser could probably choose to scroll the main content and but not the content of the "nav" tag.
 It is, but it seems to me the more specific "list of symbols introduced"
 is better.

Then you add a class in addition to the correct tag.
 In this case the distinction is actually material because we have one
 style file for both Phobos and the larger dlang.org, and we may want to
 format regular <dd> differently from Phobos symbols description. This
 seems to be a Good Thing (tm).

Then you use different classes, but still uses the correct tag. Another example. If you want to emphasis text one uses the "em" tag, not the "i" tag. The it's up to the style sheet (CSS) to decide if the emphasized text should be italic, bold or some other font. It's the same thing why one should use the type "bool" (D, C++) instead of "int". It gives the correct semantic meaning.
 Actually as I noted above that's an issue because we share the same
 style file between dlang.org and phobos. Of course, we could have two
 files, but I don't find using classes a shameful alternative.

We most likely should. -- /Jacob Carlborg
Sep 16 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 11:21 AM, Jacob Carlborg wrote:
 On 2013-09-16 18:22, Andrei Alexandrescu wrote:
 On the contrary, from what I've read in LaTeX and typography is that you
 want to keep formatting semantics high level, e.g. "This is a chapter
 title" as opposed to "this is heading text" or (worse) "this is large
 text with large spacing".

This is not LaTeX. When using the proper tags you're adding semantic meaning to your content.

Same principles apply to LaTeX. Anyhow, the discussions has been settled. You are right, and I got convinced.
 Actually as I noted above that's an issue because we share the same
 style file between dlang.org and phobos. Of course, we could have two
 files, but I don't find using classes a shameful alternative.

We most likely should.

Yah, we already have separate ddoc files for the main site and for the library. I suspect at a point we'll segregate the css files, too. We haven't gotten to the necessity yet. Andrei
Sep 16 2013
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 8:55 AM, Vladimir Panteleev wrote:
 If it's not too much effort, I'd revert this change, however this is
 more of a question of principle than practicality.

One more argument in favor of using style classes. Consider the bug you found - parameters were not styled in italics. (Whether or not we care to keep that particular formatting is a different matter.) That format was enacted as follows: DDOC_PARAM = $(I $0) which expands to <i>$0</i>. To change that in any way, one would have to do surgery on some .ddoc file, rebuild, and upload the entire site. Alternatively, one could, as you mentioned, restyle <i> in the css file, but then not only parameters would be restyled, but ALL italic text! Not good. The new definition is: DDOC_PARAM=<span class="param">$0</span> The current style is: .param { font-style: italic; } Now whenever we want to change the styling of those particular elements (and only those), we edit the css file and upload it again to the site. This is very simple, economic, and modular. Andrei
Sep 16 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
 I noticed the change: dd -> div. This is bad, because it reduces semantics.

The change was from unqualified <dd> to <div class="param">. Big difference. Now you're arguing that <dd class="param"> is better than <div class="param">. This is more interesting, and I'd like to get convinced one way or another. For my part I prefer the minimal commitment of <div> - just leave it to the style to decide how to go about things. So I have minimal hardcoding of semantics in the generated html, and maximum flexibility in the CSS - I can get to hide the thing altogether, or format it in ways that are very different from classic <dd>.
 Your example is: i -> span class="param". This is good, because it
 improves semantics.

Great. Andrei
Sep 16 2013
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 9:57 AM, Dicebot wrote:
 On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
 ...

Sounds like you are exactly arguing over the concept of semantic web and related tools. Which is a bit weird because it basically repeats the debates from various web world articles I have been reading almost 5 years ago :P Maybe we should use established wisdom of people who are doomed to deal with it on daily basis? :P

What is the established wisdom? Andrei
Sep 16 2013
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 9:56 AM, Vladimir Panteleev wrote:
 Right. I think I found the source of the misunderstanding: the idea is
 not to depend on the default formatting of <dd> - the idea is to remove
 the default styles using CSS, then use it like <div>, which is what the
 old code did.

I don't understand this paragraph. Andrei
Sep 16 2013
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 10:01 AM, Brad Anderson wrote:
 On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
 On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
 I noticed the change: dd -> div. This is bad, because it reduces
 semantics.

The change was from unqualified <dd> to <div class="param">. Big difference. Now you're arguing that <dd class="param"> is better than <div class="param">. This is more interesting, and I'd like to get convinced one way or another. For my part I prefer the minimal commitment of <div> - just leave it to the style to decide how to go about things. So I have minimal hardcoding of semantics in the generated html, and maximum flexibility in the CSS - I can get to hide the thing altogether, or format it in ways that are very different from classic <dd>.
 Your example is: i -> span class="param". This is good, because it
 improves semantics.

Great. Andrei

Why not just make every element a div with a class in that case?

The point of using specific elements is to get their default attributes "for free". Otherwise one would need to specify a bunch in the class definitions. I can see how using specific elements may help the browser if the user alters the defaults.
 There is a reason HTML 4 offered many element types and HTML 5 expanded
 this even more so.  It improves code readability and has other benefits
 beyond that including assisting screen readers and other accessibility
 services for disabled people.

 http://coding.smashingmagazine.com/2013/01/18/the-importance-of-sections/

Sections would be nice to use. Andrei
Sep 16 2013
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 10:02 AM, Adam D. Ruppe wrote:
 On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu wrote:
 Now you're arguing that <dd class="param"> is better than <div
 class="param">. This is more interesting, and I'd like to get
 convinced one way or another.

The difference is the <dd> is part of a list. <div> is just a division of the webpage. If you were using a generic program to fetch all the lists on the page, that could find <dd> better than it could find a <div>. Such a generic program might be a search engine, a screen reader, a customized browser, or something like my old improveddoc.d program. (Though the latter, being custom made for this site, could just use class names too.) You lose nothing by using the most applicable tag, and gain the potential that generic programs will understand your page better.

Weakly agreed.
 BTW, you should use as many classes as possible as well. I think each
 and every ddoc macro should have its own html class. Even if you never
 use them in the css file, they can be useful for third party analyzer
 tools. improveddoc.d used a few hacks to reconstruct some ddoc semantics
 lost in the old setup - knowing that <i> was actually a param for
 instance, so good to see that fixed.

The problem now is I need to worry about two things: class _and_ element. With div/span I only need to worry about paragraph/inline (a simpler Boolean decision) and class. Andrei
Sep 16 2013
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2013-09-16 18:49, Andrei Alexandrescu wrote:

 For my part I prefer the minimal commitment of <div> - just leave it to
 the style to decide how to go about things. So I have minimal hardcoding
 of semantics in the generated html, and maximum flexibility in the CSS -
 I can get to hide the thing altogether, or format it in ways that are
 very different from classic <dd>.

It's doesn't matter if it's a <dd> tag or a <div> tag. You can style both the same way. We might want to add some style sheet that resets an unifies the default styling for all element a cross all browsers. This is an example: http://necolas.github.io/normalize.css/ That one is used by Bootstrap and other libraries. -- /Jacob Carlborg
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 12:59:28 UTC, Andrei Alexandrescu 
wrote:
 On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
 [snip]

 Got destroyed so I changed the jump-to list back, added a 
 couple of minor improvements until we land 
 https://github.com/D-Programming-Language/dlang.org/pull/267.

 http://erdani.com/d/phobos/std_array.html

Links in the list are currently broken, I think you need to prepend a ".".
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 13:32:29 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 6:08 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 12:59:28 UTC, Andrei 
 Alexandrescu wrote:
 On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
 [snip]

 Got destroyed so I changed the jump-to list back, added a 
 couple of
 minor improvements until we land
 https://github.com/D-Programming-Language/dlang.org/pull/267.

 http://erdani.com/d/phobos/std_array.html

What happened to the margins/padding? The assocArray example block shouldn't be glued to the uninitializedArray signature.

Must have fallen through the cracks. Any chance you'd spot it in the pull request? I'll try the same when I'll find some time.

What before was <dd>, now is <div class="d_decl_dd"> (and the margin was a dd style). Why this change? You can apply any properties of one to the other through CSS.
Sep 16 2013
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 7:43 AM, H. S. Teoh wrote:
 On Mon, Sep 16, 2013 at 05:59:27AM -0700, Andrei Alexandrescu wrote:
 On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
 [snip]

 Got destroyed so I changed the jump-to list back, added a couple of
 minor improvements until we land
 https://github.com/D-Programming-Language/dlang.org/pull/267.

 http://erdani.com/d/phobos/std_array.html

Can we pretty-please-with-a-cherry-on-top reintroduce indentation for aggregate members? Right now, for example, RefAppender's members have no visual distinction from module-level symbols. This pretty much makes the docs unusable for me.

Yah, apologies. It's the same bug as noted by Vladimir. Fixed now. Thanks for the feedback and keep it coming! Andrei
Sep 16 2013
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 8:27 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 15:23:50 UTC, Andrei Alexandrescu wrote:
 Yah, apologies. It's the same bug as noted by Vladimir. Fixed now.
 Thanks for the feedback and keep it coming!

I'm opening these in two tabs and cycling between them: http://dlang.org/phobos/std_array.html http://erdani.com/d/phobos/std_array.html One noticeable difference is that parameter names are no longer italicized. Is that on purpose, or a missing .param style? Looks good otherwise!

Great catch. Fixed, along with a couple other nits. Andrei
Sep 16 2013
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 8:30 AM, Andrej Mitrovic wrote:
 On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 Thanks for the feedback and keep it coming!

The links at the top of std_array.html don't have an underline for some reason, making it hard to know they're links.

I did it on purpose :o). I found the many adjacent underlines unsightly, and thought that "Jump to" would be evocative enough. Rollback?
 Also, the links are broken. E.g. RefAppencer points to this:
 http://erdani.com/d/phobos/std_array.html#RefAppender

 But that doesn't lead to anywhere. The old page linked to:

 http://dlang.org/phobos/std_array.html#.RefAppender (note the dot
 before RefAppender).

Blurgh. Fixed. BTW what's the deal with all those \xNN in the javascript? newText += ' &nbsp;\x3Ca class="jumpto" href="\x23.' + a + '"\x3E\x3Cspan class="notranslate donthyphenate"\x3E' + text + '\x3C/span\x3E\x3C/a\x3E'; I guess some care must be exercised so as to not confuse the HTML/Javascript parser, but only for things like </script> and probablt a couple more. No? Andrei
Sep 16 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 10:10 AM, H. S. Teoh wrote:
 On Mon, Sep 16, 2013 at 06:31:11PM +0200, Andrej Mitrovic wrote:
 On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 I did it on purpose :o). I found the many adjacent underlines unsightly,
 and thought that "Jump to" would be evocative enough. Rollback?

Well, it looks like one giant sentence instead of a set of links, especially since some are capitalized and some are not. Perhaps separate them with a bullet? E.g.: Appender • RefAppender • appender • array • assocArray • back... I don't know. :]

I like the idea of delimiting with bullets.

What's a good small circular central bullet for HTML? Andrei
Sep 16 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 11:08 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu wrote:
 What's a good small circular central bullet for HTML?

&middot;

Done, looks nice. http://erdani.com/d/phobos/std_array.html Anyhow enough with this - it's just a patch until ddox. Somebody please pull the blessed thing :o). Andrei
Sep 16 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 11:18 AM, Tourist wrote:
 On Monday, 16 September 2013 at 18:14:23 UTC, Andrei Alexandrescu wrote:
 On 9/16/13 11:08 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu wrote:
 What's a good small circular central bullet for HTML?

&middot;

Done, looks nice. http://erdani.com/d/phobos/std_array.html Anyhow enough with this - it's just a patch until ddox. Somebody please pull the blessed thing :o). Andrei

My 2 cents: links without the underline look quite counter-intuitive. Not that I care that much, I'd rather see ddox up and running by default.

Sure, fixed. Andrei
Sep 16 2013
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/13 8:34 AM, Andrej Mitrovic wrote:
 On 9/16/13, Vladimir Panteleev <vladimir thecybershadow.net> wrote:
 One noticeable difference is that parameter names are no longer
 italicized. Is that on purpose, or a missing .param style?

Personally I never liked this italicization, it doesn't make reading the docs any simpler or easier to me.

I agree, i.e. the only thing I like about it is that whenever I see it I think "nice, that's customizable" :o). Destroy? Andrei
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 15:23:50 UTC, Andrei Alexandrescu 
wrote:
 Yah, apologies. It's the same bug as noted by Vladimir. Fixed 
 now. Thanks for the feedback and keep it coming!

I'm opening these in two tabs and cycling between them: http://dlang.org/phobos/std_array.html http://erdani.com/d/phobos/std_array.html One noticeable difference is that parameter names are no longer italicized. Is that on purpose, or a missing .param style? Looks good otherwise!
Sep 16 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 Thanks for the feedback and keep it coming!

The links at the top of std_array.html don't have an underline for some reason, making it hard to know they're links. Also, the links are broken. E.g. RefAppencer points to this: http://erdani.com/d/phobos/std_array.html#RefAppender But that doesn't lead to anywhere. The old page linked to: http://dlang.org/phobos/std_array.html#.RefAppender (note the dot before RefAppender).
Sep 16 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 9/16/13, Vladimir Panteleev <vladimir thecybershadow.net> wrote:
 One noticeable difference is that parameter names are no longer
 italicized. Is that on purpose, or a missing .param style?

Personally I never liked this italicization, it doesn't make reading the docs any simpler or easier to me.
Sep 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Sep 16, 2013 at 08:22:49AM -0700, Andrei Alexandrescu wrote:
 On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
What before was <dd>, now is <div class="d_decl_dd"> (and the margin was
a dd style). Why this change? You can apply any properties of one to the
other through CSS.

Great, thanks. Now fixed. My intent was to use <div> and <span> for styling ddoc elements to the extent possible, in order to make styling as flexible as possible. But I forgot to give the appropriate style to d_decl_dd (hopefully not others). Destroy: http://erdani.com/d/phobos/std_array.html

OK, that looks *much* better. Thanks! T -- The volume of a pizza of thickness a and radius z can be described by the following formula: pi zz a. -- Wouter Verhelst
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 15:22:50 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 6:40 AM, Vladimir Panteleev wrote:
 What before was <dd>, now is <div class="d_decl_dd"> (and the 
 margin was
 a dd style). Why this change? You can apply any properties of 
 one to the
 other through CSS.

Great, thanks. Now fixed. My intent was to use <div> and <span> for styling ddoc elements to the extent possible, in order to make styling as flexible as possible.

Although bordering on nitpicking, I'll mention that this is not a good change. It is recommended to use the appropriate HTML elements for their semantic meaning. <dl> is a definition list, which nicely fits documenting a list of entities. HTML5 even introduced additional HTML tags, such as <nav>. Styling is not a problem, since you can use CSS to remove the default styles from practically any layout tag, making it behave like <span> or <div>. If it's not too much effort, I'd revert this change, however this is more of a question of principle than practicality.
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 16:11:15 UTC, Andrei Alexandrescu 
wrote:
 BTW what's the deal with all those \xNN in the javascript?

 newText += ' &nbsp;\x3Ca class="jumpto" href="\x23.' + a +
   '"\x3E\x3Cspan class="notranslate donthyphenate"\x3E' + text 
 + '\x3C/span\x3E\x3C/a\x3E';

 I guess some care must be exercised so as to not confuse the 
 HTML/Javascript parser, but only for things like </script> and 
 probablt a couple more. No?

Not sure if this is the reason that applies to our case, but - you can use < and > in inline scripts in HTML, but not in XHTML, which must be well-formed XML. The exception is if the script code is wrapped in a CDATA block.
Sep 16 2013
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu 
wrote:
 <dl> is a definition list, which nicely fits
 documenting a list of entities.

It is, but it seems to me the more specific "list of symbols introduced" is better.

<dl class="d_decl"> <dd class="d_class"> or whatever Use the closest tag name to what it is, and then put a class in there to get more specific.
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 16:22:13 UTC, Andrei Alexandrescu 
wrote:
 [citation needed]

Sure, here you go: https://en.wikipedia.org/wiki/Semantic_HTML
 On the contrary, from what I've read in LaTeX and typography is 
 that you want to keep formatting semantics high level, e.g. 
 "This is a chapter title" as opposed to "this is heading text" 
 or (worse) "this is large text with large spacing".

Well, the big difference with TeX and HTML is that with *TeX, you distribute the output, whereas with HTML, you distribute the source code - which can be interpreted by user agents other than web browsers rendering the page on a computer display.
 <dl> is a definition list, which nicely fits
 documenting a list of entities.

It is, but it seems to me the more specific "list of symbols introduced" is better.

You could use both (<dl class="d_decl">) if you like.
 In this case the distinction is actually material because we 
 have one style file for both Phobos and the larger dlang.org, 
 and we may want to format regular <dd> differently from Phobos 
 symbols description. This seems to be a Good Thing (tm).

Good thing for that C in CSS! :) If you add a class to the <html> or <body> tag (or any other tag that wraps all symbol definitions), which only appears on Phobos documentation pages, you can create a CSS rule that only applies to those pages. E.g.: HTML: <body class="library_dox"> ... <dd> CSS: .library_dox dd { /* applies only to dd tags in library dox pages */ }
Sep 16 2013
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 I did it on purpose :o). I found the many adjacent underlines unsightly,
 and thought that "Jump to" would be evocative enough. Rollback?

Well, it looks like one giant sentence instead of a set of links, especially since some are capitalized and some are not. Perhaps separate them with a bullet? E.g.: Appender =95 RefAppender =95 appender =95 array =95 assocArray =95 back... I don't know. :]
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 16:37:06 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 8:55 AM, Vladimir Panteleev wrote:
 If it's not too much effort, I'd revert this change, however 
 this is
 more of a question of principle than practicality.

One more argument in favor of using style classes. Consider the bug you found - parameters were not styled in italics. (Whether or not we care to keep that particular formatting is a different matter.) That format was enacted as follows: DDOC_PARAM = $(I $0) which expands to <i>$0</i>. To change that in any way, one would have to do surgery on some .ddoc file, rebuild, and upload the entire site. Alternatively, one could, as you mentioned, restyle <i> in the css file, but then not only parameters would be restyled, but ALL italic text! Not good. The new definition is: DDOC_PARAM=<span class="param">$0</span> The current style is: .param { font-style: italic; } Now whenever we want to change the styling of those particular elements (and only those), we edit the css file and upload it again to the site. This is very simple, economic, and modular.

This is correct and I agree. I think we misunderstood each other? I noticed the change: dd -> div. This is bad, because it reduces semantics. Your example is: i -> span class="param". This is good, because it improves semantics.
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 16:44:56 UTC, Andrei Alexandrescu 
wrote:
 I don't find disagreement with what I said.
 [...]
 Nice, but what I see here is "different", not "better".

I think we may be disagreeing regarding different things.
 You could use both (<dl class="d_decl">) if you like.

I guess '<dl class="d_decl">' is one iota more specific than '<div class="d_decl">' and would help if one wanted to view the HTML without any accompanying CSS. I doubt this is a goal to pursue.

I refer to my original argument about how this is borderline-nitpicking. I'd like to add, however, that user-agents such as screen readers might behave better when using appropriate HTML tags.
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
 I noticed the change: dd -> div. This is bad, because it 
 reduces semantics.

The change was from unqualified <dd> to <div class="param">. Big difference.

(I assume that "param" is now used with the meaning of the abstract value of the "class" HTML attribute, in contrast to its previous occurrence as the literal "param" CSS class from the <i> example)
 Now you're arguing that <dd class="param"> is better than <div 
 class="param">. This is more interesting, and I'd like to get 
 convinced one way or another.

Is the Wikipedia link I posted earlier not applicable? I believe it discusses why it is beneficial to use HTML tags that reflect, or reflect closely the semantics of their contents. E.g. <nav> instead of <div> for navigation blocks, <address> instead of <span> for addresses, and respectively <dd> instead of <div> for definition lists.
 For my part I prefer the minimal commitment of <div> - just 
 leave it to the style to decide how to go about things. So I 
 have minimal hardcoding of semantics in the generated html, and 
 maximum flexibility in the CSS - I can get to hide the thing 
 altogether, or format it in ways that are very different from 
 classic <dd>.

Right. I think I found the source of the misunderstanding: the idea is not to depend on the default formatting of <dd> - the idea is to remove the default styles using CSS, then use it like <div>, which is what the old code did. (Apologies to everyone for, once again, blowing up a nitpick matter into an overgrown discussion of a dozen posts.)
Sep 16 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu 
wrote:
 ...

Sounds like you are exactly arguing over the concept of semantic web and related tools. Which is a bit weird because it basically repeats the debates from various web world articles I have been reading almost 5 years ago :P Maybe we should use established wisdom of people who are doomed to deal with it on daily basis? :P
Sep 16 2013
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
 I noticed the change: dd -> div. This is bad, because it 
 reduces semantics.

The change was from unqualified <dd> to <div class="param">. Big difference. Now you're arguing that <dd class="param"> is better than <div class="param">. This is more interesting, and I'd like to get convinced one way or another. For my part I prefer the minimal commitment of <div> - just leave it to the style to decide how to go about things. So I have minimal hardcoding of semantics in the generated html, and maximum flexibility in the CSS - I can get to hide the thing altogether, or format it in ways that are very different from classic <dd>.
 Your example is: i -> span class="param". This is good, 
 because it
 improves semantics.

Great. Andrei

Why not just make every element a div with a class in that case? There is a reason HTML 4 offered many element types and HTML 5 expanded this even more so. It improves code readability and has other benefits beyond that including assisting screen readers and other accessibility services for disabled people. http://coding.smashingmagazine.com/2013/01/18/the-importance-of-sections/
Sep 16 2013
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 16 September 2013 at 16:49:25 UTC, Andrei Alexandrescu 
wrote:
 Now you're arguing that <dd class="param"> is better than <div 
 class="param">. This is more interesting, and I'd like to get 
 convinced one way or another.

The difference is the <dd> is part of a list. <div> is just a division of the webpage. If you were using a generic program to fetch all the lists on the page, that could find <dd> better than it could find a <div>. Such a generic program might be a search engine, a screen reader, a customized browser, or something like my old improveddoc.d program. (Though the latter, being custom made for this site, could just use class names too.) You lose nothing by using the most applicable tag, and gain the potential that generic programs will understand your page better. BTW, you should use as many classes as possible as well. I think each and every ddoc macro should have its own html class. Even if you never use them in the css file, they can be useful for third party analyzer tools. improveddoc.d used a few hacks to reconstruct some ddoc semantics lost in the old setup - knowing that <i> was actually a param for instance, so good to see that fixed.
 For my part I prefer the minimal commitment of <div> - just 
 leave it to the style to decide how to go about things.

The stylesheet has full control of appearance regardless of the tag. You can make a <dd> look like a rainbow circle with invisible text on the top of the page if you want to, or make it plain inline text. Same as <div>, <span>, or (almost*) anything else. * browser bugs might come into play but they aren't supposed to.
Sep 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Sep 16, 2013 at 06:49:01PM +0200, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 16:44:56 UTC, Andrei Alexandrescu
 wrote:
I don't find disagreement with what I said.
[...]
Nice, but what I see here is "different", not "better".

I think we may be disagreeing regarding different things.
You could use both (<dl class="d_decl">) if you like.

I guess '<dl class="d_decl">' is one iota more specific than '<div class="d_decl">' and would help if one wanted to view the HTML without any accompanying CSS. I doubt this is a goal to pursue.

I refer to my original argument about how this is borderline-nitpicking. I'd like to add, however, that user-agents such as screen readers might behave better when using appropriate HTML tags.

I can attest to that. I'm on another mailing list where one of the list members is sight-impaired, and she complains about how some websites (i.e. those that suffer from heavy divitis and spanitis) simply can't be read in any sane way by the screen reader. Using built-in semantic tags like <dl> can make a world of difference for these users, since the screen reader has no idea what class="d_decl" means, but it *does* know what <dl> means. I wouldn't be so quick to dismiss it. T -- It is the quality rather than the quantity that matters. -- Lucius Annaeus Seneca
Sep 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Sep 16, 2013 at 06:31:11PM +0200, Andrej Mitrovic wrote:
 On 9/16/13, Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> wrote:
 I did it on purpose :o). I found the many adjacent underlines unsightly,
 and thought that "Jump to" would be evocative enough. Rollback?

Well, it looks like one giant sentence instead of a set of links, especially since some are capitalized and some are not. Perhaps separate them with a bullet? E.g.: Appender • RefAppender • appender • array • assocArray • back... I don't know. :]

I like the idea of delimiting with bullets. T -- Perhaps the most widespread illusion is that if we were in power we would behave very differently from those who now hold it---when, in truth, in order to get power we would have to become very much like them. -- Unknown
Sep 16 2013
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 16 September 2013 at 17:14:01 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 10:01 AM, Brad Anderson wrote:
 On Monday, 16 September 2013 at 16:49:25 UTC, Andrei 
 Alexandrescu wrote:
 On 9/16/13 9:44 AM, Vladimir Panteleev wrote:
 I noticed the change: dd -> div. This is bad, because it 
 reduces
 semantics.

The change was from unqualified <dd> to <div class="param">. Big difference. Now you're arguing that <dd class="param"> is better than <div class="param">. This is more interesting, and I'd like to get convinced one way or another. For my part I prefer the minimal commitment of <div> - just leave it to the style to decide how to go about things. So I have minimal hardcoding of semantics in the generated html, and maximum flexibility in the CSS - I can get to hide the thing altogether, or format it in ways that are very different from classic <dd>.
 Your example is: i -> span class="param". This is good, 
 because it
 improves semantics.

Great. Andrei

Why not just make every element a div with a class in that case?

The point of using specific elements is to get their default attributes "for free". Otherwise one would need to specify a bunch in the class definitions. I can see how using specific elements may help the browser if the user alters the defaults.

The point is the semantics, not the default styling. The default styling exists just to give them a sane default to work with.
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 17:08:21 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 9:56 AM, Vladimir Panteleev wrote:
 Right. I think I found the source of the misunderstanding: the 
 idea is
 not to depend on the default formatting of <dd> - the idea is 
 to remove
 the default styles using CSS, then use it like <div>, which is 
 what the
 old code did.

I don't understand this paragraph.

You presented the example regarding replacing <i> with <div class="param">. We agree that this is a good change. I understood that your argument against using <dd> is its *stylistic* (not semantic) properties: by default, a <dd> has additional CSS styles that are not present on <div> tags. We agreed that tags that have only stylistic properties, such as <i>, should not be used. <i> has no semantic meaning (its recommended replacement is <em>, short for "emphasized", which has the same default stylistic properties, but now also has semantic meaning). I understood that you applied the above arguments together, to conclude that <dd> should not be used for the same reasons that that <i> should not be used - <i> has the same semantic properties as <span>. However, the difference between <dd> and <div class="d_decl_dd"> is that the former has semantics which the latter doesn't. (To clarify, by "semantics" I mean meaning that can be useful to user-agents reading the HTML, such as screen readers.)
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 17:16:30 UTC, Andrei Alexandrescu 
wrote:
 The problem now is I need to worry about two things: class 
 _and_ element. With div/span I only need to worry about 
 paragraph/inline (a simpler Boolean decision) and class.

You don't need to set the class to every <dd> tag. Since all <dd> tags are direct children of a <dl> tag, you can set the class on the <dl> tag, then use a CSS child selector to specify styling. E.g.: HTML: <dl class="decl_ddoc"> <dt>...</dt> <dd>...</dd> ... CSS: dl.decl_ddoc > dd { /* styles that apply only to <dd> inside a <dl class="decl_ddoc"> */ }
Sep 16 2013
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 16 September 2013 at 17:25:11 UTC, Vladimir Panteleev 
wrote:
 You don't need to set the class to every <dd> tag.

Yes, but since it is ddoc macros we might as well retain whatever information we can. It's only written once there, in the macro, so it isn't a big hassle anyway.
Sep 16 2013
prev sibling next sibling parent "Brad Anderson" <eco gnuk.net> writes:
On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 10:10 AM, H. S. Teoh wrote:
 On Mon, Sep 16, 2013 at 06:31:11PM +0200, Andrej Mitrovic 
 wrote:
 On 9/16/13, Andrei Alexandrescu 
 <SeeWebsiteForEmail erdani.org> wrote:
 I did it on purpose :o). I found the many adjacent 
 underlines unsightly,
 and thought that "Jump to" would be evocative enough. 
 Rollback?

Well, it looks like one giant sentence instead of a set of links, especially since some are capitalized and some are not. Perhaps separate them with a bullet? E.g.: Appender • RefAppender • appender • array • assocArray • back... I don't know. :]

I like the idea of delimiting with bullets.

What's a good small circular central bullet for HTML? Andrei

http://www.fileformat.info/info/unicode/char/25cf/index.htm
Sep 16 2013
prev sibling next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 16 September 2013 at 17:59:11 UTC, Andrei Alexandrescu 
wrote:
 What's a good small circular central bullet for HTML?

&middot;
Sep 16 2013
prev sibling next sibling parent "Tourist" <gravatar gravatar.com> writes:
On Monday, 16 September 2013 at 18:14:23 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 11:08 AM, Vladimir Panteleev wrote:
 On Monday, 16 September 2013 at 17:59:11 UTC, Andrei 
 Alexandrescu wrote:
 What's a good small circular central bullet for HTML?

&middot;

Done, looks nice. http://erdani.com/d/phobos/std_array.html Anyhow enough with this - it's just a patch until ddox. Somebody please pull the blessed thing :o). Andrei

My 2 cents: links without the underline look quite counter-intuitive. Not that I care that much, I'd rather see ddox up and running by default.
Sep 16 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Monday, 16 September 2013 at 17:08:02 UTC, Andrei Alexandrescu 
wrote:
 On 9/16/13 9:57 AM, Dicebot wrote:
 On Monday, 16 September 2013 at 16:49:25 UTC, Andrei 
 Alexandrescu wrote:
 ...

Sounds like you are exactly arguing over the concept of semantic web and related tools. Which is a bit weird because it basically repeats the debates from various web world articles I have been reading almost 5 years ago :P Maybe we should use established wisdom of people who are doomed to deal with it on daily basis? :P

What is the established wisdom? Andrei

AFAIR there has been an article about semantic web linked in this thread. I am not web dev myself by any means but general motto I hear from Internet publications on topic can be summarized as: - HTML is for semantics, CSS is for style - HTML should never interfere with how stuff is viewed - HTML should be meaningful on its own, even without any CSS - Meaning of HTML elements is standardized, not so for classes Importance of last point is often underestimated. Screen readers have been already mentioned but it also applies for stuff like search engine robots - better HTML element selection can result in better search output.
Sep 17 2013
prev sibling parent "Jonas Drewsen" <nospam4321 hotmail.com > writes:
On Monday, 16 September 2013 at 17:08:38 UTC, H. S. Teoh wrote:
 On Mon, Sep 16, 2013 at 06:49:01PM +0200, Vladimir Panteleev 
 wrote:
 On Monday, 16 September 2013 at 16:44:56 UTC, Andrei 
 Alexandrescu
 wrote:
I don't find disagreement with what I said.
[...]
Nice, but what I see here is "different", not "better".

I think we may be disagreeing regarding different things.
You could use both (<dl class="d_decl">) if you like.

I guess '<dl class="d_decl">' is one iota more specific than '<div class="d_decl">' and would help if one wanted to view the HTML without any accompanying CSS. I doubt this is a goal to pursue.

I refer to my original argument about how this is borderline-nitpicking. I'd like to add, however, that user-agents such as screen readers might behave better when using appropriate HTML tags.

I can attest to that. I'm on another mailing list where one of the list members is sight-impaired, and she complains about how some websites (i.e. those that suffer from heavy divitis and spanitis) simply can't be read in any sane way by the screen reader. Using built-in semantic tags like <dl> can make a world of difference for these users, since the screen reader has no idea what class="d_decl" means, but it *does* know what <dl> means. I wouldn't be so quick to dismiss it.

Haven't followed the thread closely but one thing I've missed when trying to define a nicer stylesheet is something more specific that "d_decl". d_decl is used for all declarations which means that you cannot style enums, templates, functions etc. differently in the docs. It would be nice to have an additional class added to the class attribute. For example: class="d_decl d_enum" or class="d_decl d_template". /Jonas
Sep 17 2013
prev sibling next sibling parent "Wyatt" <wyatt.epp gmail.com> writes:
On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu 
wrote:
 Sure. My goal with this upgrade is to get rid of the unsightly 
 bag of words at the top of most pages.

words" into a boxed out vertical list floating at the left. It worked fairly well at all sorts of browser sizes and required zero Javascript. (It will work even better when all the modules have introductory text as mentioned in another thread.</optimism>) I wonder if I should resurrect that branch? -Wyatt
Sep 16 2013
prev sibling next sibling parent "Wyatt" <wyatt.epp gmail.com> writes:
On Monday, 16 September 2013 at 13:33:55 UTC, Andrei Alexandrescu 
wrote:
 Probably not. The consensus is to got the ddox way, and Walter 
 and myself are on board with it. We're a bit concerned about 
 switching to new tooling (dependencies, bus factor etc) but we 
 think it's worth it.

Well, as long as it works (and works WELL) without Javascript, I guess that's a fine start. Though I have to admit the example linked above hurts my eyes. :( (So. Much. White.) -Wyatt
Sep 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Sep 16, 2013 at 08:58:31AM +0200, Jacob Carlborg wrote:
 On 2013-09-16 06:50, H. S. Teoh wrote:
 
What we need is not Yet Another Snake Oil Automagic Trick that will
somehow magically make it all work. What we need is to sit down and
put in the time to organize the module docs, grouping the symbols by
logical categories (which a computer can't really figure out for us,
unless we tag the code, which requires the same amount of effort
anyway). I think std.algorithm and std.range's docs are a good model
to follow. They set the minimum standard all Phobos docs should meet.

Of course, we can also improve on them even more, by figuring out a
way to prevent the DRY violation currently in std.algorithm (to add a
new symbol, you now have to add it in 3 places: at the navigation
table at the top, then in the cheatsheet, then the actual code in the
module body). Maybe some kind of DDoc tag or UDA that can be
collected by a postprocessing script that autogenerates the relevant
tables based on what information is there? For example:

	// Note: not actual syntax, I just made this up for illustration
	// purposes:

	/**
	 *  category: searching
	 *  cheatsheet: newHaystack = find(haystack, needle)
	 *
	 * Finds needle in haystack.
	 * ...
	 */
	R find(R,S)(R haystack, S needle)
	{
		...
	}

The postprocessing tool would then collect all the  category tags and
 cheatsheet tags and assemble a table out of them, linked to the
relevant symbols, and insert it at the top of the page. (Or, it could
even split the files up into individual pages, which we've been
talking about since, oh, last year?)

I think we should try and enhance the documentation generated automatically. Tagging and doing other things manually doesn't scale. This should only be used as a last option.

The problem is that Walter wants DDOC to be a generic macro-expansion system. Adding any further smarts to it would tie it down to D-specific functionality, which reduces the likelihood of it being accepted. But, you may be able to change his mind. :) T -- Computers are like a jungle: they have monitor lizards, rams, mice, c-moss, binary trees... and bugs.
Sep 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Sep 16, 2013 at 05:59:27AM -0700, Andrei Alexandrescu wrote:
 On 9/15/13 12:14 AM, Andrei Alexandrescu wrote:
 [snip]
 
 Got destroyed so I changed the jump-to list back, added a couple of
 minor improvements until we land
 https://github.com/D-Programming-Language/dlang.org/pull/267.
 
 http://erdani.com/d/phobos/std_array.html

Can we pretty-please-with-a-cherry-on-top reintroduce indentation for aggregate members? Right now, for example, RefAppender's members have no visual distinction from module-level symbols. This pretty much makes the docs unusable for me. T -- Marketing: the art of convincing people to pay for what they didn't need before which you can't deliver after.
Sep 16 2013
prev sibling next sibling parent "Gary Willoughby" <dev nomad.so> writes:
On Monday, 16 September 2013 at 04:15:43 UTC, deadalnix wrote:
 On Sunday, 15 September 2013 at 18:38:54 UTC, Sönke Ludwig 
 wrote:
 Am 15.09.2013 19:20, schrieb Walter Bright:
 On 9/15/2013 12:53 AM, Vladimir Panteleev wrote:
 What happened with Ddox? This looks like an improvement in 
 both
 function and
 aesthetics:

 http://vibed.org/temp/phobos/std/array.html

It doesn't document the parameters, return type, and doesn't recognize embedded hyperlinks.

Just as a reminder, this is the current version: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html

I'm sold, that is awesome !

Me too that is much, much nicer! :D
Sep 16 2013
prev sibling parent "Wyatt" <wyatt.epp gmail.com> writes:
On Monday, 16 September 2013 at 14:38:25 UTC, Andrei Alexandrescu 
wrote:
 Which example? Are you referring to the extra spacing I added 
 between symbols?

Turns out I was looking at the wrong version. The current version here looks all right: http://vibed.org/temp/d-programming-language.org/phobos/std/array.html Though I have numerous concerns with having comments on the doc pages, and ESPECIALLY using an external service for them. -Wyatt
Sep 16 2013