May 03, 2012
> What I meant with "under the same tree is"
>
> + std
> + algorithm
> * map
> * reduce
> * ...

Aha, I was thinking more like "below the tree" as it is now.

-- 
/Jacob Carlborg
May 03, 2012
On 2012-05-03 14:43, Jakob Ovrum wrote:

> There would be a lot of wasted whitespace to the left, and overflow for
> long symbol names would become an even bigger issue.
>
> I do understand the problem though, and I want to fix it. Some more
> opinions are much appreciated.
>
>

The right side is pretty empty if you have a wide screen. Perhaps the symbols can be placed there.

-- 
/Jacob Carlborg
May 03, 2012
On Thu, 03 May 2012 08:43:43 -0400, Jakob Ovrum <jakobovrum@gmail.com> wrote:

> On Thursday, 3 May 2012 at 12:33:33 UTC, Ary Manzana wrote:
>> On 5/3/12 6:41 PM, Jacob Carlborg wrote:
>>> On 2012-05-03 10:09, Ary Manzana wrote:
>>>
>>>> I'm not sure. I'd like the symbols to be under the same tree.
>>>>
>>>> With tabs you'd have to click twice to go from one place to another.
>>>>
>>>
>>> I didn't even know the symbols where there until a scrolled down.
>>>
>>
>> The same happened to me.
>>
>> What I meant with "under the same tree is"
>>
>> + std
>>   + algorithm
>>     * map
>>     * reduce
>>     * ...
>
> There would be a lot of wasted whitespace to the left, and overflow for long symbol names would become an even bigger issue.
>
> I do understand the problem though, and I want to fix it. Some more opinions are much appreciated.

I suggest:

1. Only expand tree to the level of the current symbol selected.  So for instance, you click on std.datetime, you see all the top-level symbols of std.datetime *not* expanded.  If you click on std.datetime.Month, the Month enum expands in the tree.
2. When inside a module, only show the packages of that module as breadcrumbs, without indentation.  That saves you the white space.

BTW, I noticed two issues:

1. If a symbol name is too long, it is truncated with ..., but the expand/collapse arrow is also removed.
2. The index.html goes to links like std_base64.html, but the actual doc is at std.base64.html, so you get a 404.

Looks really nice!  I agree with Ary, we *really* really need cross references (generated by the compiler), and I'd add it would be nice to be able to show categories and category headers at the top of each module (i.e. here are all the structs in this file, here are all the classes).

-Steve
May 04, 2012
On Thursday, 3 May 2012 at 14:30:38 UTC, Steven Schveighoffer wrote:
> I suggest:
>
> 1. Only expand tree to the level of the current symbol selected.  So for instance, you click on std.datetime, you see all the top-level symbols of std.datetime *not* expanded.  If you click on std.datetime.Month, the Month enum expands in the tree.

You mean like the module list currently works with packages and modules?

> 2. When inside a module, only show the packages of that module as breadcrumbs, without indentation.  That saves you the white space.

Packages of a module?

I'm not sure what you mean here, could you try to explain this again, perhaps with an example? I have a feeling it's a good idea, so I want to comprehend it fully.

> BTW, I noticed two issues:
>
> 1. If a symbol name is too long, it is truncated with ..., but the expand/collapse arrow is also removed.

Added a comment to an existing issue, thanks.

https://github.com/JakobOvrum/bootDoc/issues/1

> 2. The index.html goes to links like std_base64.html, but the actual doc is at std.base64.html, so you get a 404.

The links on the index page are generated from hard-coded HTML in index.d. With the new fix for the noscript sidebar, file names must use a dot as a package separator, while the hard-coded paths use an underscore (the package separator in output files is configurable, by the way). Previously the links incidentally worked because the output was configured with underscores.

So the problem really lies with the Phobos documentation for using hard-coded links. I think the noscript sidebar is more important than the (terribly outdated) index page, which could be fixed by editing the source anyway (I suppose I could easily do this for the Phobos bootDoc demo).

May 04, 2012
On Thursday, 3 May 2012 at 14:27:38 UTC, Jacob Carlborg wrote:
> The right side is pretty empty if you have a wide screen. Perhaps the symbols can be placed there.

On my current 16:9 1080p monitor, the full width of the page is utilized by the main documentation, tested with Opera and Chrome (as it's supposed to do with the current use of Bootstrap's "table" framework). It does depend on the quantity of documentation though; for LuaD, the right side is considerably more empty than for most Phobos modules.

I think it's possible to conditionally and cleanly introduce a right-side sidebar depending on the screen width, that could be worth experimenting with.

First I think I want to try to make the sidebar into an accordion, as was suggested earlier in the thread.
May 04, 2012
On Thursday, 3 May 2012 at 08:16:48 UTC, Rory McGuire wrote:
> Would be great if you could make it an accordion with a live search at the
> top.

An accordion is a nice idea, and Bootstrap has good support for it.

Where would you have the search, exactly, though? And do you mean the existing symbol search, a project-wide search (which is non-trivial), or a module search?
May 04, 2012
On Thursday, 3 May 2012 at 06:53:42 UTC, Ary Manzana wrote:
> I don't think the main documentation order is right in the first place. If a module provides many functions, like std.algorithm, I don't see how there could possibly be an "intended" order, like "these are more likely to be used".
>
> In any case, if I want to quickly find a function, for example "remove" or "insert" or something I think might have the name I'm looking for, alphabetical order is the best way to go.

I agree that the current order doesn't make a whole lot of sense, but it's something that requires one of three things; either 1) a patch to DDoc to make it emit declarations in a different order, or 2) post-processing of DDoc's output, or 3) dynamic reordering with JavaScript.

Although it's actually quite trivial to implement (especially with jQuery), I don't like the sound of #3.

The problem I have with #2 is that it indicates a problem with the documentation generator in the first place (DMD's DDoc implementation). I'd rather have a go at making a better DDoc generator (maybe Descent is a good start? A new project using SDC is another option) than go down route #2.
May 04, 2012
On Fri, 04 May 2012 09:56:48 -0400, Jakob Ovrum <jakobovrum@gmail.com> wrote:

> On Thursday, 3 May 2012 at 14:30:38 UTC, Steven Schveighoffer wrote:
>> I suggest:
>>
>> 1. Only expand tree to the level of the current symbol selected.  So for instance, you click on std.datetime, you see all the top-level symbols of std.datetime *not* expanded.  If you click on std.datetime.Month, the Month enum expands in the tree.
>
> You mean like the module list currently works with packages and modules?

I don't see it working that way.  If I click on etc.c.sqlite3 for example, it doesn't collapse std.

Essentially, what I mean is, I should only see the parents, immediate children, and siblings of the currently selected item in the tree *by default*, and then let the user expand if he's interested in more.  I only suggest this for the module, though.

For example, std.datetime has a huge tree, but everything is expanded fully.  If all the top-level items are collapsed, then I don't have to go as far to navigate for something.

>> 2. When inside a module, only show the packages of that module as breadcrumbs, without indentation.  That saves you the white space.
>
> Packages of a module?

packages that a module is in.  For example, etc.c.sqlite3 is in packages etc and c.  If we make those breadcrumbs instead of part of a large tree, it can get around your worry about whitespace, because they don't need separate indentation.

>> 2. The index.html goes to links like std_base64.html, but the actual doc is at std.base64.html, so you get a 404.
>
> The links on the index page are generated from hard-coded HTML in index.d. With the new fix for the noscript sidebar, file names must use a dot as a package separator, while the hard-coded paths use an underscore (the package separator in output files is configurable, by the way). Previously the links incidentally worked because the output was configured with underscores.
>
> So the problem really lies with the Phobos documentation for using hard-coded links. I think the noscript sidebar is more important than the (terribly outdated) index page, which could be fixed by editing the source anyway (I suppose I could easily do this for the Phobos bootDoc demo).

OK, not a big deal then.  Part of the problem with phobos ddoc in this regard is that cross-links are defined in each individual module.

-Steve
May 04, 2012
On Friday, 4 May 2012 at 14:48:04 UTC, Steven Schveighoffer wrote:
> I don't see it working that way.  If I click on etc.c.sqlite3 for example, it doesn't collapse std.
>
> Essentially, what I mean is, I should only see the parents, immediate children, and siblings of the currently selected item in the tree *by default*, and then let the user expand if he's interested in more.  I only suggest this for the module, though.
>
> For example, std.datetime has a huge tree, but everything is expanded fully.  If all the top-level items are collapsed, then I don't have to go as far to navigate for something.

Right, I didn't notice that problem, but it is indeed glaringly obvious with std.datetime. Will fix that, thanks!

> packages that a module is in.  For example, etc.c.sqlite3 is in packages etc and c.  If we make those breadcrumbs instead of part of a large tree, it can get around your worry about whitespace, because they don't need separate indentation.

That's a great idea, but where in the tree would it appear? What would happen to the rest of the modules, should they be indented like they are now? Wouldn't that look a little weird?

May 04, 2012
On Fri, 04 May 2012 10:59:46 -0400, Jakob Ovrum <jakobovrum@gmail.com> wrote:

> On Friday, 4 May 2012 at 14:48:04 UTC, Steven Schveighoffer wrote:
>
>> packages that a module is in.  For example, etc.c.sqlite3 is in packages etc and c.  If we make those breadcrumbs instead of part of a large tree, it can get around your worry about whitespace, because they don't need separate indentation.
>
> That's a great idea, but where in the tree would it appear? What would happen to the rest of the modules, should they be indented like they are now? Wouldn't that look a little weird?

I was envisioning eliminating the rest of the tree, and you'd have to click on one of the breadcrumbs to get it back.  But that might be weird.

Something like:

etc . c .
sqlite3
* func1
* func2
...

And then you click on etc or c, and get the module tree back (either dynamically or after a round-trip from the server).

The idea is, when you are navigating in a module, you are interested in the module, not the rest of the modules.

I personally am not as much concerned about how many clicks it takes to navigate as much as I'm concerned about making the tree more focused on what you are doing now.

-Steve
1 2 3 4
Top | Discussion index | About this forum | D home