Remove Namespace from API function Index

[veqqq]

The pages start with an index of functions, each of which repeats the namespace taking up a lot of space and making it difficult to profitably utilized the index:

Displaying them in the index as accept accept-loop address address-unpack etc. would be nice (but keeping the full net/accept on the actual elements.

We could also add some sort of structure or increase space between elements.

[sogaiu]

I'm not sure why but I think I prefer to have the prefix.

---

I've been trying to come up with something that might be a little more concrete. May be it's something like the following...

At least for what comes with Janet (e.g. net/server), I think we don't generally use the prefixed callables without the prefix. So for example, we typically might call net/server but not server.

In order to use net/server as server I think we could manually create an additional definition, e.g.

(def server net/server)

...but I don't think this tends to be done much.

Even in the docstring, we see the prefix:

$ janet
Janet 1.38.0-0aee7765 linux/x64/gcc - '(doc)' for help
repl:1:> (doc net/server)


    function
    boot.janet on line 3921, column 3

    (net/server host port &opt handler type no-reuse)

    Starts a server with net/listen. Runs net/accept-loop 
    asynchronously if handler is set and type is :stream (the default). 
    It is invalid to set handler if type is :datagram. Returns the new 
    server stream.


nil

---

For items that don't come with Janet (e.g. things from spork or a 3rd party library), the story is different regarding use of callables without prefixes because we might use import or use.

Possibly for such things removing the prefix might make sense?

Not sure 😅

---

Perhaps other folks have some related thoughts

[veqqq]

To actually call them, you need the full name or an alias, yes. But for using the index, in some cases half of the text space being the module prefix is a bit painful. The idea here is to make the indices more legible.

For rhetorical purposes, I'll switch to a more egregious example with an inconsistency:

Note how jpm/commands/build does not include jpm (even in the title. (Though I would actually argue for adding jpm to the individual entries.) Since we already expect readers to understand they need the package, to use them, I suggest making them look like this:

[sogaiu]

Since we already expect readers to understand they need the package

In the case of jpm one can use use and end up with no prefix, but this is not true of the core things. One can also do (import jpm/commands :as commands) and end up with a shorter prefix. Thus one can actually see things like build or commands/build in source code through ordinary use (i.e. via typical importing constructs and not atypical "redefinitions").

Although I'm not unsympathetic to there being an aesthetic / readability angle I don't find removing the prefix to be a net win for the core api things. There is a trade-off and I don't think it's worth it.

I think one of the issues may be readability, but the proposed method may not be the only way to address it.

[veqqq]

Would prepending a sentence explaining that they require the (package and) subpackage to be called, help?

I believe you fundamentally disagree with this suggestion, which is fine. I'm confused by the why (I know you aren't quite sure why either.) I mean, what is the intended workflow supposed to be? What should someone know before arriving at such a documentation page?

To me, at least, the index is just a list of things to click on, so the goal should be quick legibility not correctness, since it takes you to the documentation. Do you use or intend others to use the index to just know what functions are available and just try to use them directly?

Currently, these require a reader to know they have to use an alias or something to call them as described (just commands/build). To me, changing only the link text doesn't seem relevant or confusing in that context. But you don't think adding the entire default call-name would disambiguate further? I believe you would not want to add the top level package name to the index, though. Why or why not?

Also, what's the recommended vocabulary, what are core-api's math or jpm's command called, are both "submodule" and "subpackage" ok for them? Which is better? The official docs don't seem to use "namespace".

[veqqq]

On the side bar, they start with the package e.g. spork, then the subpackage channel, taking us to the actual in the subpackage. In these places, proper code calling convention does not determine the presentation for navigation. The index seems like a continuation of the side bar for navigating on a page.

How do you see it? What structure should guide these things? Would it make sense to have the sidebar only show spork, but expand (html detail) on clicking? Could e.g. channel also expand in the sidebar to show all functions?

---

If preserving the namespace prefix, adding a line break could assist with readability. It will take up a lot of space but lets the reader mentally run down at the same spot?

[bakpakin]

I think this is a pretty sensible suggestion, as long as we have a full "unqualified" name somewhere in the documentation for CTRL-F and to remove as much ambiguity as possible. Repeating the common prefix over and over again in the index looks busy, although it doesn't bother me that much.

BTW, a bit of an aside, but the original look and feel of the documentation came from both clojure's documentation but also PicoLisp, who do something similar with a very dense index in the documentation. Also looking at the index critically again, I think we could add a bit more spacing and padding around symbols.