View mode: basic / threaded / horizontal-split · Log in · Help
May 03, 2012
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
> 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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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
Re: bootDoc - advanced DDoc framework using Twitter's Bootstrap
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