On Thursday, 3 May 2012 at 05:44:47 UTC, Ary Manzana wrote:
> On 5/3/12 1:26 AM, Jakob Ovrum wrote:
>> This project is finally published and documented, so here's an
>> announcement.
>>
>> https://github.com/JakobOvrum/bootDoc
>>
>> bootDoc is a configurable DDoc theme, with advanced JavaScript features
>> like a package tree and module tree, as well as fully qualified symbol
>> anchors. The style itself and some of the components come from Twitter's
>> Bootstrap framework.
>>
>> Demonstration of Phobos documentation using bootDoc
>>
>> http://jakobovrum.github.com/bootdoc-phobos/
>
> Very nice!
>
> But why the symbols inside std.algorithm, for instance, are not sorted?
>
> http://jakobovrum.github.com/bootdoc-phobos/std.algorithm.html
>
> (they are kind of sorted by chunks...)

The symbols in the symbol tree appear in the order the symbols appear in the documentation, which is the order of declaration in the original source (DMD does it this way). I think it would be a little confusing if the symbol tree was alphabetically sorted, while the main documentation was in order of declaration.

It is possible to rearrange everything with JavaScript of course, but... I think this might be going a little bit too far.

What do you think?

> Now if it only had cross references... :-P

If I understand you correctly, any kind of automatic cross-referencing would need post-processing of DMD's generated output. I am considering such post-processing, but it would massively change the project (a lot less would require JavaScript), and completely bind the project to the included generator tool.

I think the tool needs more trial-by-fire testing to determine whether it's good enough to be mandatory.

On 5/3/12 1:23 PM, Jakob Ovrum wrote:
> On Thursday, 3 May 2012 at 05:44:47 UTC, Ary Manzana wrote:
>> On 5/3/12 1:26 AM, Jakob Ovrum wrote:
>>> This project is finally published and documented, so here's an
>>> announcement.
>>>
>>> https://github.com/JakobOvrum/bootDoc
>>>
>>> bootDoc is a configurable DDoc theme, with advanced JavaScript features
>>> like a package tree and module tree, as well as fully qualified symbol
>>> anchors. The style itself and some of the components come from Twitter's
>>> Bootstrap framework.
>>>
>>> Demonstration of Phobos documentation using bootDoc
>>>
>>> http://jakobovrum.github.com/bootdoc-phobos/
>>
>> Very nice!
>>
>> But why the symbols inside std.algorithm, for instance, are not sorted?
>>
>> http://jakobovrum.github.com/bootdoc-phobos/std.algorithm.html
>>
>> (they are kind of sorted by chunks...)
>
> The symbols in the symbol tree appear in the order the symbols appear in
> the documentation, which is the order of declaration in the original
> source (DMD does it this way). I think it would be a little confusing if
> the symbol tree was alphabetically sorted, while the main documentation
> was in order of declaration.
>
> It is possible to rearrange everything with JavaScript of course, but...
> I think this might be going a little bit too far.
>
> What do you think?

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.

>
>> Now if it only had cross references... :-P
>
> If I understand you correctly, any kind of automatic cross-referencing
> would need post-processing of DMD's generated output. I am considering
> such post-processing, but it would massively change the project (a lot
> less would require JavaScript), and completely bind the project to the
> included generator tool.
>
> I think the tool needs more trial-by-fire testing to determine whether
> it's good enough to be mandatory.

Oh, I just said that because I have a pull request waiting for that feature to be incorporated in DMD... but I don't think it'll happen...

On 2012-05-03 08:09, Jakob Ovrum wrote:

> I am considering putting the module tree and symbol tree in tabs instead
> of below each other.

I think that would be a good idea.

-- 
/Jacob Carlborg

On 2012-05-03 08:53, Ary Manzana wrote:

> Oh, I just said that because I have a pull request waiting for that
> feature to be incorporated in DMD... but I don't think it'll happen...

I really hope we get this functionality.

-- 
/Jacob Carlborg

On 5/3/12 2:10 PM, Jacob Carlborg wrote:
> On 2012-05-03 08:09, Jakob Ovrum wrote:
>
>> I am considering putting the module tree and symbol tree in tabs instead
>> of below each other.
>
> I think that would be a good idea.

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.

Would be great if you could make it an accordion with a live search at the top.


On Thu, May 3, 2012 at 10:09 AM, Ary Manzana <ary@esperanto.org.ar> wrote:

> On 5/3/12 2:10 PM, Jacob Carlborg wrote:
>
>> On 2012-05-03 08:09, Jakob Ovrum wrote:
>>
>>  I am considering putting the module tree and symbol tree in tabs instead
>>> of below each other.
>>>
>>
>> I think that would be a good idea.
>>
>
> 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.
>
>

On Thursday, 3 May 2012 at 06:09:31 UTC, Jakob Ovrum wrote:
> On Thursday, 3 May 2012 at 05:14:43 UTC, James Miller wrote:
>> On Wednesday, 2 May 2012 at 18:26:11 UTC, Jakob Ovrum wrote:
>>> This project is finally published and documented, so here's an announcement.
>>>
>>>   https://github.com/JakobOvrum/bootDoc
>>>
>>> bootDoc is a configurable DDoc theme, with advanced JavaScript features like a package tree and module tree, as well as fully qualified symbol anchors. The style itself and some of the components come from Twitter's Bootstrap framework.
>>
>> I would make a minor change that lets you see the function tree near the top. On my laptop screen (about a standard size) I have to scroll down about an entire screen to see it. How this is implemented is up to you, but being able to collapse to module view might be enough.
>>
>> --
>> James Miller
>
> Packages in the module view are collapsable, just click on them.
>
> Having the module list in its entirety collapsable might be an idea, but unless your project has a ton of top-level packages and modules, it won't help much with your specific problem (the situation would be almost the same).
>
> I am considering putting the module tree and symbol tree in tabs instead of below each other.

Ahh, I missed that, sorry. Nevermind me, carry on, you're awesome.

--
James Miller

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.

-- 
/Jacob Carlborg

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
    * ...

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.