Adds an Index page for the Standard Library. Fixes #98. #187
Conversation
Looks like this may be complicated by the fact that tree doesn't properly follow anchor links.
|
This is so good! I'm not entirely sure how I feel about sorting these alphabetically rather than by the sections in hoon.hoon. If I'm looking for things to do with lists, I ideally want to be able to ctrl-f for "list" and see all arms under "2b: list logic". Though that may make the index more similar to existing docs pages, I think having this index function as a quick-ref would be neat. Maybe a format along the lines of the following might be nice (per section)?
That's just my two cents though, and very much up in the air still. Not to mention "he who does the work...". It'd be cool to get feedback from more people on this, see what everyone's looking for in an index page like this. Also, +1 for name tags on function arms for those #links, but the next iteration of our markdown-to-html rendered will automagically put those in for you, like Github already does. So spare yourself the effort there! |
|
Thanks for your feedback, @Fang-. I think I headed down the alphabetical route because that's how an index is traditonally organized. 😄 . As a compromise, what if we retained alpha ordering, but added the section to it like so:
I will post something about this PR on /fora to see if we can get a wider audience for comments. Is there any way I can see the in progress version of tree? (I assume that's what you're calling " our markdown-to-html") I looked in the public repo and I don't see any in progress branches. |
|
I'm inclined to think that alphabetical is best. (I guess that's ironic, since I argued against it for the glossary ...) It comes down to which reading patterns should be prioritized: I think an index is most useful for looking up gates referenced somewhere else. And the pages themselves are already grouped by section. I'm conflicted when it comes to including the sample mold in the table. Is it helpful context, or extra, confusing information? I'll have to leave that to others. Finally, it's worthing noting that |
|
It wouldn't be all that difficult to make a table like the sample one that @ngzax has drawn up above (#187 (comment)) sortable. It's a toss up to me whether alphabetical or section makes more sense. If you're looking for a 'kind' of gate then you want to sort by section. Otherwise: this is a great idea. That index page is really not helpful. I feel like https://urbit.org/docs/hoon/reference/ could use some help as well. |
|
Nothing of substance to add, just want to give my support to this idea and lodge another vote in favor of a sortable list, since I can anticipate using one while reading code and while writing. |
|
@galenwp : Thanks for your feedback. One of the reasons I made it the way it is now is because I couldn't see any way using any of the table markdown syntaxes I have ever used to make a table in urbit markdown. Is there a syntax? If not, would it need to be added via tree? I am more than willing (and able) to work on this but as I indicated in my comment to @Fang- above I am concerned that there is a newer version of tree coming soon that isn't publicly visible yet. |
|
Currently, this would be added using some kind of tree component.
The main thing that's changing in the tree update we're working on is the ability to do server-side includes. Basically, you'll be able to write hoon and use %ford to generate your pages. So, this index page could be a function of all the library docs.
@ohAitch, is this stable enough for someone else to experiment with?
… On Aug 7, 2017, at 3:21 PM, Daryl Richter ***@***.***> wrote:
@galenwp : Thanks for your feedback.
One of the reasons I made it the way it is now is because I couldn't see any way using any of the table markdown syntaxes I have ever used to make a table in urbit markdown. Is there a syntax? If not, would it need to be added via tree?
I am more than willing (and able) to work on this but as I indicated in my comment to @Fang- above I am concerned that there is a newer version of tree coming soon that isn't publicly visible yet.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
For stuff like this you already have to write hoon in ford if you want to generate them dynamically, see |
|
I mean, isn't the twig reference (https://urbit.org/docs/hoon/reference/) doing something similar client-side? |
|
That one's less auto-generated, but yes
…On Monday, 7 August 2017, Galen Wolfe-Pauly ***@***.***> wrote:
I mean, isn't the twig reference (https://urbit.org/docs/hoon/reference/)
doing something similar client-side?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#187 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/ABxXhhMcWIVsiPT03KuRd0_o0bdvtpPoks5sV6vLgaJpZM4OrzD->
.
|
|
Thanks guys, I'll check out those pages and see what I can do. |
|
@ngzax Did you see what you can do for this yet? (: |
|
This is something that @rmariani is working on as we speak, so I'm going to close this PR for now, and we can always refer back to this if we need. |
This is a Proposal and is not ready for merge. I wanted to get this out there, however, before I put in more work to make sure I am going down the right path.
This is a big "itch" of mine because when you read examples, for example in this excellent post: https://urbit.org/fora/posts/~2017.7.20..09.13.38..a812~/, you see gates like cork, crip, and trip and it is difficult to find them in the current 1a, 1b, &c. structure of the standard library docs.
This is unfortunately hampered by the fact that tree doesn't properly follow anchor links when sending to another page. (They do work intra-page). This is an existing bug that is already affecting the docs and I am going to try to take a stab at fixing that as well. But, for now, for this patch you'll just have to imagine it works. 😉 At least it takes you to the right section.
Comments on the formatting and presentation are welcomed.