janet-lang / janet-lang.org Goto Github PK

The code blocks in the Janet docs are intense, high contrast, and somewhat difficult to read. If you like the current color scheme, I suggest the following changes:

• background: #111 --> #333
• .mdzsyn-symbol: #9effff --> #afffff
• .mdzsyn-keyword: #f92672 --> #ff97bc
• .mdzsyn-coresym: #fd971f --> #ffbc6d

With those changes, please see these before and after pics:

http://www.unexpected-vortices.com/temp/janet/janet-docs-code-blocks-before.png

http://www.unexpected-vortices.com/temp/janet/janet-docs-code-blocks-after.png

If you'd rather not make those changes, perhaps a lower-contrast colorscheme?

I noticed that https://janet-lang.org/docs/jpm.html doesn't mention declare-bin.

I tried (fiber/setmaxstack (fiber/current) 16384), both in a script and in the REPL, but when I do (fiber/maxstack (fiber/current)) afterwards, I still get 8192.
I'm using an up to date Janet 0.4.0-4713219 on macOS 10.14.3.

Hi! I was writing trying to write a msgpack implementation in pure Janet and I noticed there is no function to convert double -> bytes.

This is useful not just for serialization, but also for various bit hacks like estimating log2 or sqrt.

With the addition if int/to-bytes maybe you should consider adding math/double-to-bytes?

On https://janet-lang.org/, there are four buttons in a row:

• Releases
• Source
• Documentation
• Core API

Hovering over the edge of each button highlights it, indicating that it’s clickable, but clicking it does nothing. The link only works if you click on the actual text inside the button.

The solution is to reorganize the HTML and CSS so that the a element is outside of the button (which is currently a div) rather than inside it.

The Documentation link on https://janet-lang.org/ links to the Introduction documentation page. However, on the navigation sidebar, this Introduction page is displayed in the middle of the other links, which are in alphabetical order:

It is not clear which page one should read next to get a good idea of the language. I have to read the whole list of links, then evaluate which link seems simplest among the pages I haven’t read yet.

I suggest implementing two solutions:

• Display the navigation links in order of suggested reading (most basic to most advanced). If some ordering is arbitrary, you could split the links into two sections: an “Introduction” section that is manually ordered and a “Reference” section that is alphabetically ordered.
• At the bottom of each page, display links to the next and previous pages. For example, on the “Introduction” page, display “Syntax >” on the bottom-right corner and no link on the bottom-left corner.

At https://janet-lang.org/api/index.html, all the functions (top-level functions (like map, filter, reduce, interpose, frequencies, etc.) and functions within modules (such as buffer/trim, os/getenv)) are all shown together on the same big page.

I think the api docs need an additional separate page that only shows the top-level functions (those not in any module).

I'm trying to learn the language and the built-in functions, but it's difficult to see just those core/top-level functions without being distracted by every function of every module.

It doesn't seem to be documented anywhere.

As of v1.20.0, Janet supports & more in destructuring. Update https://janet-lang.org/docs/destructuring.html .

• system: Android 8.0.0
• browser: Chrome 75.0.3770.101

1. The height of the logo is too large in relation to the width.
   

2. One table in Data Structures extends the width.
   
   

(dyn :args) is not documented anywhere.
(dyn :syspath) is documented insufficiently in man janet.

I think important dynamic variables should be documented somewhere.

Intent

Making this issue to record a current issue which even if addressed might have bits that could benefit from upkeep. I haven't thought of a good solution, but figured that spelling out some details in one place might help in maintenance and/or possibly surface / lead to some improved approach.

Observations

On the page with installation instructions there are a couple of sections that have to do with Windows:

• https://janet-lang.org/docs/index.html#Windows
• https://janet-lang.org/docs/index.html#Windows-0

The former currently has this text:

you will also need to install Visual Studio, ideally a recent release (2019 or 2017 should work well). Then, running jpm from the x64 Native Tools Command Prompt should work for a 64-bit build, and from the Developer Command Prompt should work for 32-bit builds. Using these specific command prompts for jpm simply lets jpm use the Microsoft compiler to compile native modules on install.

the latter has (elided some bits):

1. Install [Visual Studio](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=15#) or [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15#)
2. Run a Visual Studio Command Prompt (cl.exe and link.exe need to be on the PATH)
...

To install from source, first follow the steps above, then you will need to

1. Install, or otherwise add to your PATH, the [WiX 3.11 Toolset](https://github.com/wixtoolset/wix3/releases)
2. Run a Visual Studio Command Prompt (cl.exe and link.exe need to be on the PATH)
...

There are a few things that are currently out-of-sync-ish:

• the version of visual studio / build tools -- 2017 and 2019 mentioned in one place while the link in the other seems to point to an older version but goes to a generic location(?)
• the name(s) of the relevant command prompts to use -- x64 Native Command Prompt for 64-bit and Developer Command Prompt for 32-bit are mentioned in one place but not spelled out in the other

Unfortunately, the former (the version info) seems to need upkeep as MS seems to be in the habit of placing older versions behind some login (at least that's what showed up for me before when I went looking for older things -- don't know how it is now).

Perhaps the latter stuff (the names of the command prompts) doesn't change much, but one of the two sections above might be too vague / confusing. AFAIK, Visual Studio Command Prompt (cl.exe and link.exe need to be on the PATH) doesn't point at a specific enough option.

For future reference, I came across this list of some / all of the command prompt shortcuts:

• Developer Command Prompt - Sets the environment to use 32-bit, x86-native tools to build 32-bit, x86-native code.
• x86 Native Tools Command Prompt - Sets the environment to use 32-bit, x86-native tools to build 32-bit, x86-native code.
• x64 Native Tools Command Prompt - Sets the environment to use 64-bit, x64-native tools to build 64-bit, x64-native code.
• x86_x64 Cross Tools Command Prompt - Sets the environment to use 32-bit, x86-native tools to build 64-bit, x64-native code.
• x64_x86 Cross Tools Command Prompt - Sets the environment to use 64-bit, x64-native tools to build 32-bit, x86-native code.

Possible Improvement

May be it makes sense to mention the version and prompt names in one section and then have some text in the other section that makes a reference to the section with the details. I think this would reduce out-of-sync issues at the cost of extra navigation [1].

[1] Where is my transclusion, Mr. Nelson?

I recently learned that I can import /path/to/module.janet with

(import @/path/to/module)

This is not documented on the website, yet.

Moved here from main repo
As the document said:

To build Janet for the web via [Emscripten](https://kripken.github.io/emscripten-site/), make sure you have emcc installed and on your path. On a Linux or macOS system, use make emscripten to build janet.js and janet.wasm - both are needed to run Janet in a browser or in Node.js. The JavaScript build is what runs the REPL on the main website, but really serves mainly as a proof of concept. Janet will run slower in a browser. Building with Emscripten on Windows is currently unsupported.

I ran make emscripten, and I got this:

make: *** No rule to make target 'emscripten'.  Stop.

At the time of this writing, the reference table for bytecodes lacks a row for the new bytecode instruction, divf, added in janet-lang/janet@c83f3ec.

Perhaps inserting an appropriate row between these two rows:

   ['div '(div dest lhs rhs) "$dest = $lhs / $rhs"]
   ['divim '(divim dest lhs im) "$dest = $lhs / im"]

is sufficient to address this issue.

I wonder what to use to indicate the operator in the rightmost column:

 ['divf '(divf dest lhs rhs) "$dest = $lhs ??? $rhs"]

One candidate for ??? might be div because:

$ janet
Janet 1.29.1-58d29736 linux/x64/gcc - '(doc)' for help
repl:1:> (disasm (fn [] (div 2 3)) :bytecode)
@[(ldi 1 2) (ldi 2 3) (divf 0 1 2) (ret 0)]

However, this might be confusing because the row above it would presumably be this:

['div '(div dest lhs rhs) "$dest = $lhs / $rhs"]

That is, the instruction's name in that row is div.

May be using // makes sense?

On GNU/Linux, the installation of Janet goes very smoothly when installing into /usr/local.

My understanding is that I should alternatively be able to install Janet locally (into, say, ~/opt), where root access would not be required.

I'd like to install Janet into ~/opt, but have jpm maintain its installation of libraries under, say, ~/janet (not sure what's commonly used here). Does that sound like somewhat typical usage for Janet?

I asked about this on gitter, and @sogaiu (and also Calvin) lent a hand, but I'm still confused specifically about whether the JANET_PATH env var is used to specify where jpm installs libraries vs having something to do with where the janet itself is installed (~/opt/janet-1.11.3 ?) ( --- or both??).

Perhaps if it can be explained here, I can compose a PR to enhance the GNU/Linux installation instructions adding a local install option.

Thanks!

> (import ./ok)
error: could not find module ./ok:
    ok.jimage
    ok.janet
    ok/init.janet
    ok.so
  in require-1 [boot.janet] on line 3025, column 20
  in import* [boot.janet] on line 3064, column 15
  in _thunk [repl] (tailcall) on line 2, column 1

In the above error, I saw that (import ./ok) tries to load ok/init.janet after trying to load ok.janet.

This behavior is not documented on https://janet-lang.org/docs/modules.html.

This is significant for module organization.

Stack exchange suggests malformed html would likely be the cause. It's only that particular section. I briefly looked at the source and popped it in my editor to see if the syntax highlighter would clue me in, but nothing showed.

https://janet-lang.org/capi/array.html

See change in 1.13.1 re backtick-delimited strings. Possible places to update:

• syntax page --> long strings section
• strings, keywords, & symbols page

While we're at it, it may make sense to change the text "long strings" to "long-strings" or "longstrings" uniformly throughout, to distinguish them from other strings that just happen to be long.

Possibly related to this: PR #99 .

Section should be updated with the proper way to do multithreading now.

Recent activity including this issue resulted in a proposal to create a page on subprocess management for the website docs.

I looked through the existing docs and found os/spawn in a code example, but failed to locate coverage in the main text for it or os/execute. If I've missed anything relevant, I hope someone will point such things out (^^;

The aforementioned issue appears to contain relevant bits of information regarding the use of subprocesses in Janet so hopefully we can capture a useful portion of it in some manner.

Also of note is this PR. Whatever the fate of that, there may still be bits from it that are useful for our purposes here.

There are some operators in the description column of the reference table for the abstract machine's intructions that start with a dot:

$dest = $lhs .>= $rhs
$dest = $lhs .> im
$dest = $lhs .<= $rhs
$dest = $lhs .< im

May be these dots are not intentional?

https://janet-lang.org/docs/jpm.html doesn't reflect what's possible now in project.janet.

For example, :tag.

The Embedding section of the C API chapter explains some basic ways of running Janet code embedded in a C program, such as janet_dobytes, janet_dostring, or janet_call.

It is mentioned multiple times that these ways are mostly meant for running "simple, short running logic" or for running code once. There is a mention of the existence of more efficient options (under the entry for janet_dobytes), but there's no info on what those options actually are.

What are these more efficient ways of running Janet code optimally when embedded in a C program?

Would be nice to have a small syntax-highlighted code example somewhere on the Janet homepage.

Maybe as part of the intro paragraph at the top, after the first sentence (to the right of the logo)?

Hi to all,
this is more of a suggestion than a problem per se.

As a newcomer, I accidentally discovered some peculiar features of the Janet language that set it apart from other programming languages. I'm quite sure they are rock-solid choices made by experienced people, and I'm not going to criticize them or propose changes.

But I think it could be beneficial, at least for beginners like me, to have a section of the Janet documentation devoted to highlighting conventions in Janet that might be different from what one might expect from other, widely used, programming languages.

Just to give some examples, I'm thinking about -2 used to refer to the last item in an array/tuple[1] or the 0-based index for day and month only in os/date[2], and I don't know how many other cases of this kind may exist.

I know that all these behaviors are well and clearly specified in the relevant docstrings but, as I said, I think it could be beneficial for beginners to have them listed on a single page and not scattered all around the documentation.

To be more clear, I'm not advocating changes in language semantic and/or behavior, just more "prime time" in the documentation about these divergences from common practice. I'm thinking about something in the line of "Janet for pythonists/clojurists" or "Janet for C/C++ developer" etc.

Please, above all, take this as a constructive proposal, I do not want to criticize someone else's free time/contribution.
Thank you.

[1] janet-lang/janet#1219 (comment)
[2] janet-lang/janet#1214 (comment)

Hi,

Anybody knows how to install Janet on ubuntu ?

Thanks,

This is a reminder issue based on a brief conversation on the janet-language/website matrix channel.

To be in sync with the changes to jpm, may be changing the first paragraph on the jpm page is worth considering:

Most default installs of Janet come with a build tool, jpm, that makes managing dependencies, building Janet code, and distributing Janet applications easy.

Here's a slightly edited version of a response from bakpakin:

Yes, we should update that text. I think for a patch release we can also add the ability to install jpm while install Janet with Make or meson

However, jpm will be versioned separately from Janet from now on

@pepe suggested moving "The Event Loop" to a position before "Multithreading" in the table of contents. That seems like a more logical order to me too.

Unless there are objections, we can work on a PR toward this end once some decisions (merge / no-merge) are made about these related PRs: #141 and #143

IIUC, to change the order, one might change the numbers appropriately in the following lines:

• https://github.com/janet-lang/janet-lang.org/blob/master/content/docs/networking.mdz#L3
• https://github.com/janet-lang/janet-lang.org/blob/master/content/docs/threads.mdz#L3
• https://github.com/janet-lang/janet-lang.org/blob/master/content/docs/event_loop.mdz#L3

Janet's comparison operators can give some surprising results, especially for comparing values of different types. Polymorphic comparison was just added to the core in a recent PR. In closing out issue janet-lang/janet#272 we discussed adding a chapter to the docs explaining comparison and polymorphic comparison. I have written a section, and am about to issue a PR to this repo. Just wanted to make sure there was a tracking issue for it before I issued the PR.

process module uses &keys in function arguments, but it is not explained on https://janet-lang.org/docs/functions.html

Now that janet-lang/janet#1187 has been merged, may be it makes sense to add some docs for true and false as PEG specials.

Perhaps in this section?

At https://janet-lang.org/ , the link to "Joy Web Framework" leads to joyframework.com , which returns a 404.

Currently in the Installing a module portion of the docs, there is the following:

Using jpm, the path module can be installed like so from the command line:

sudo jpm install https://github.com/janet-lang/path.git

...

If you are not using jpm, you can place the file path.janet from the repository in your current directory, and Janet will be able to import it as well.

Since the path repository has been archived, may be it's worth choosing another one for the example.

May be spork isn't a bad choice? Though I guess that's more than one file, so since the text near the end of what's quoted refers to a single file, updating it as well might be worth considering. However, doing that might lead to losing this valuable tip:

If you are not using jpm, you can place the file path.janet from the repository in your current directory, and Janet will be able to import it as well.

I looked around for a suitable single-file replacement that lived under janet-lang at github but came up empty-handed...

If a .janet script file ends with a #comment and that comment does not have a linefeed character at the end, then the script may run as planned, but at the end this message comes:

parse error in XYZ.janet around byte NNN: unmatched delimiter

You can also add Janet scripting to an application by embedding a single C file and two headers.

I think its now a single header as the config is embedded.

https://janet-lang.org/docs/bindings.html and https://janet-lang.org/docs/functions.html don't explain how multiline doc strings are formatted by doc string formatter.

As per title, I've tested several links in the documentation, and all were broken (404).

Just to be clear, I mean the link to the community examples at the end of each section of spork module.

As an example, the documentation section of spork argparse (https://janet-lang.org/api/spork/index.html#spork/argparse/argparse) has a link to a janetdocs.com page with community examples (https://janetdocs.com/spork/argparse/argparse) that doesn't exist.

I don't know if those links were automatically generated and the corresponding pages never existed or if those pages have been moved.

Thanks for your time and hard work!

...on /docs, /api and /capi pages

Until recently, I didn't recognize the example for &keys on https://janet-lang.org/docs/functions.html was using destructuring. I thought the destructured struct was the only allowed syntax for &keys.

I didn't think it was a destructured struct. I thought it was just the only syntax for &keys.

(defn test
  [&keys {:argument1 arg1 :argument2 arg2}]
  (print arg1)
  (print arg2))

For years, I didn't know something like this was possible.

(defn test
  [&keys struct]
  (pp struct))

https://janet-lang.org/docs/functions.html should mention that what follows after &keys is actually a destructured struct.

I don't have jpm repository cache. I can't use jpm make-lockfile.

I want to manually write it.

At the time of this writing, the reference table for bytecodes lacks a row for the new bytecode instruction subim, added in janet-lang/janet@b5d3c87 .

May be adding something like the following between these two rows:

 ['subim '(subim dest lhs im) "$dest = $lhs - im"]

is sufficient to address this issue.

In a wide window, the navigation links are presented in a vertical list, which is fine:

But in a slightly narrower window (e.g. my browser window when my vertical tabs sidebar is showing), the navigation links are displayed horizontally in a row:

This row display does not look good. It is weird that all of the links are close together except the last two, Syntax and Tables, which fill the whole row. Maybe the intent is to mimic tabs, but there are too many links for that.

As an alternative, first I suggest displaying a vertical list alongside the content, just like with a larger window. There still seems to be plenty of space for it. But for truly narrow windows, I suggest displaying a vertical list of links above the content, perhaps collapsed by default with some JavaScript to expand them.

If I follow a link like this:

https://janet-lang.org/api/index.html#map

I would expect it to take me directly to the map function. And in fact it does exactly that -- but if your browser executes JavaScript, the little search widget thing will scroll the page all the way up to the top a moment later.

As reported here: janet-lang/janet#678 -- on this page: https://janet-lang.org/introduction.html the "Syntax and the Parser" link near the top right of the page comes up incorrect when using Firefox or Chromium here.

The link I see is: https://janet-lang.org/syntax.html

I think that should be: https://janet-lang.org/docs/syntax.html

That's not the only thing though. The links along the left also seem off (missing "/docs").

The above testing is on a Linux box.

On event_loop page, "raises and error" may be typoed - "raises an error"?

https://janet-lang.org/docs/event_loop.html

A PR attempt to fix - although Emacs was a little over-excited to clean up old whitespace (not sure if that whitespace needs to return or not):

#131

The "Panicking" section of "Writing C Functions" has a nice table of format specifiers (used by janet_panic* and elsewhere).

I don't see %c in the list though it is used in a few places, e.g.:

janet_panicf("invalid flag %c, expected a, t, d, e, u, y, i, or p", view.bytes[i]);

via: https://github.com/janet-lang/janet/blob/79807bf2aba035525f99003a7c3df6a30aac0691/src/core/fiber.c#L521

I'm willing to make a PR, but don't know what to put for the "Description" and "Type" columns.

Any hints?

It's available, but it's not documented on janet website.

Plus, janet REPL doesn't provide autocompletion for janet modules...

It took some time to discover this module...