On Friday, 4 August 2017 at 23:14:38 UTC, Adam D. Ruppe wrote:
On Friday, 4 August 2017 at 21:53:14 UTC, Johnson Jones wrote:
When I click on gtk on the link you gave it gives basically an
empty page(a single module).
Yeah, there is no overview page in the source code... but I can
make it create one automatically.
http://dpldocs.info/experimental-docs/gtk.HButtonBox.HButtonBox.html
Does not list any members to the left.
That's intentional, actually. For the left nav, I show parents
and siblings, not children (that's in the main content on the
right). I sometimes miss children there too, but siblings are
actually usually more useful to me.
Easier to see the value in Phobos since it is flatter:
http://dpldocs.info/experimental-docs/std.algorithm.sorting.isSorted.html
you can see the bolded isSorted showing where you are now, and
then its other siblings to navigate the module over there.
Yeah, that is a nice feature. But I do not think we are talking
about the same thing.
While having the siblings only is also nice and desirable to
reduce clutter, one needs to quickly see all methods in a module
rather than having to hunt and peck.
This is actually done in the phobos link you gave and is what am
I talking about. The problem then is that we do not see the
hierarchy of all the modules and how they relate without having
to click clinks.
e.g.,
http://dpldocs.info/experimental-docs/std.algorithm.sorting.nextPermutation.html
but
http://dpldocs.info/experimental-docs/std.html
shows all the modules in the main view which is very long and
takes time to scroll. It would be nice if those were shown in the
left pane rather than nothing.
This way, instead of having to scroll down the long list to find
a module one can see it usually instantaneously to the left.
Basically the same as the functions that are listed in the first
link.
The way I would do it, probably, is to have a complete hierarchy
tree.
std
...
experimental
...
allocator
...
building_blocks
...
region
...
InSituRegion
Now, obviously this is a very big list. (For speed, probably ajax
would be used to load only the most relevant)
Also, everything cannot be expanded at the start. Only the most
current position is expanded + any siblings.
So, it is sorta like what you have but offers a way to see the
entire library and navigate it relatively quickly but without
having to leave that panel to find something. It's all their,
just not the descriptions, etc.(although mouse over could provide
some basic description when required)
Because humans are amazing and have figured out vast ways to do
things, I'd probably have a small toolbar at the top that lets
one go between different views. If you want a flat list you click
the flat button. If you want a full hierarchy you can click a
button for that. If you want a reduced hierarchy(immediate module
only, still in tree form but all the other branches off the root
are not shown) you could get that. Siblings only would have a
button.
Since all these are basically just different "views" of the same
data, they all have their pros and cons and some are more useful
than others at different times. The more ways one can view data
the more ways one can understand the data.
gtkd has really shallow modules with just one class per module,
so this appears less useful... but in general I find it really
easily to navigate. Maybe I could detect the one class per
module pattern and collapse it though.
My problem with gtkD's docs is that one cannot quickly(within a
click) go from one module to another.
One must select the packages tab then find the module and click
on it. Do whatever, then when one wants to go to another module,
repeat the process. It's not slow in an absolute sense(whatever
that means) but it takes a few seconds when it can be done < 1s.
Since the packages and module are tabbed, one can't have them
both open. If they were side by side, it would probably work
fine... not much different than a tree view.
Also, the package tree is not collapsed by default. This means
more scrolling. Scrolling is a slow process. It may seems fast
but it's just a waste of time ultimately because we cannot do
anything while we are doing it... and all those little scrolls
add up to significant time loss. It's similar to how banks try to
get a few extra cents per customer because it's billions at the
end of the day... or how manufactures try to cut costs on a
product that are a few cents work per product but add up to
billions. Similar for programmers. Imagine if we could instantly
find the help we wanted how much more time we would have over our
lives. E.g., some type of brain interface device that we could
transmit our thoughts in to and it would do a search for the data
and present the results. That is effectively what we have with
google or whatever computer searching tools.. but it far slower
than a direct connection.
When one scrolls down to view a long page one doesn't want to
have to scroll all the way back up to view the members list
again.
See, this is why I DON'T use a tree over there. There's just
way too much scrolling in a tree, both vertical and horizontal.
By just showing parents and siblings, it presents the most
useful info without needing scrolling... it just doesn't work
well for one class per module.
I agree, in most cases for programming docs(or file systems, say)
this is true. But most of the time the tree should be completely
collapsed at all levels so within O(log2(depth)) clicks we can
find what we want. Usually the depth is not more than 10 so it
takes just a few clicks to find(usually about 3 to 4). These
clicks are better than scrolling because to scroll we have to
move the cursor to the scroller and then back and click. When we
click generally it is a smaller distance to move because the
information is localized on the screen(e.g., we click on the
parent then on a child which is somewhere below the parent, but
usually not too far off).
If humans organized things better we wouldn't have such problems.
Hierarchies that are effectively a flat list(e.g., a folder with
1M sub-folders in it) is not designed properly for optimal
searching and effectively is not a hierarchy. (We end up with
O(n) searching rather than O(log(n))).
Since many programs spend a significant portion of their life
searching through docs online, I think it's important to
optimize that routine.
That's why I forked the docs... everyone else was just doing
the same boring crap so I went something fairly different.
That's good, that's what it takes for progress. Most people are
lemmings and don't have any imagination and can't or won't think
outside the box. Why humans have progressed to where they are is
someone being tired of the same old boring and broke shit and
decided to find a better way.
I'm not sure what Geralds docs look like but it might solve
many of the problems already and you don't have to waste your
time if you don't want to.
It sounds like ddox which is one option I evaluated and
rejected when I did my fork... so it might be ok but I doubt it
is better.
The official gtk docs are the competition and I don't actually
like them either...
I don't know how time consuming it would be to rerun it on all
the docs you've generated... hopefully you've automated that
too ;).
Simple case of running ./doc /path/to/gtk and waiting like 5
mins for it. So it is slow but automatic so I can just do it in
the background.
I just hate running big disk operations on my computer... so I
need to optimize this since I run so many docs now.
Could you automate this better using a "cloud" based strategy?
Something like github or a remote server where you have all the
docs uploaded to and can trigger an update which causes it to
update the documentation and then a rebuild which builds the
docs? This way it should only take a few seconds to start the
process and everything will be done remotely not effecting your
own time much(of course the design/setup time might be costly but
probably not too bad).
IMO, the modern documentation sucks. I remember doing win32 stuff
back in the day of win95/98 and microsoft had all the docs with
visual studio 2005. The documentation was extremely informative
rather than just a list of functions and parameter descriptions.
They'd give you the theory, the relationships between everything,
etc. It wasn't that easy to navigate but it wasn't a big deal
because most of the time was spent reading and clicking links.
Now, since the actual information is so frugal, one spends more
time searching for stuff and therefor the searching time is more
of an issue.
For example:
----
InSituRegion
struct InSituRegion(size_t size, size_t minAlign =
platformAlignment)
InSituRegion is a convenient region that carries its storage
within itself (in the form of a statically-sized array).
Region
struct Region(ParentAllocator = NullAllocator, uint minAlign =
platformAlignment, Flag!"growDownwards" growDownwards =
No.growDownwards)
A Region allocator allocates memory straight from one
contiguous chunk. There is no deallocation, and once the region
is full, allocation requests return null. Therefore, Regions are
often used (a) in conjunction with more sophisticated allocators;
or (b) for batch-style very fast allocations that deallocate
everything at once.
SbrkRegion
struct SbrkRegion(uint minAlign = platformAlignment)
Allocator backed by $(LINK2
https://en.wikipedia.org/wiki/Sbrk, sbrk) for Posix systems. Due
to the fact that sbrk is not thread-safe by design, SbrkRegion
uses a mutex internally. This implies that uncontrolled calls to
brk and sbrk may affect the workings of SbrkRegion adversely.
----
Basically tells me nothing about how to use these things nor how
they work with the whole design of allocator. It may be somewhat
straight forward in some cases but in others it's helpful to know
theory. To get that, I have to track down where the information
is, if it exists. It is backwards than what it used to be which
was a top down approach(a hierarchy starting with the root).
e.g., You might start with a section on memory management that
describes how it works and all that and it would then break off
in to the more detailed aspects and those then would break off.
As you learn about them you start with the most general
understanding and learn the specifics... which is how the human
brain learns. Now we seem to just deal with specifies.
Generalities must be learned from other sources and one must try
and piece everything together. Of course, this is probably due to
isolated individuals writing the docs rather than a team that
actually plans out everything...
The D docs sorta try to do the top down approach so there is info
there but I don't get the same feeling I get from the win32
docs(which, some time later MS$ changed the help system and
everything started going down hill). I think it's because the
win32 help design was just very well put together. It didn't feel
like a cobbling of different statements but a very well thought
out explanation of the entire system.
In any case, thanks for working on this stuff! It benefits a lot
of people.
