View mode: basic / threaded / horizontal-split · Log in · Help
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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.
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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...
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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.
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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.
>
>
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
    * ...
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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.
1 2 3 4
Top | Discussion index | About this forum | D home