THE example on the documentation page can't be compiled

[klartext]

The documentation page
https://immediate-mode-ui.github.io/Nuklear/
contains ONE prominent example, following directly after the gallery of screenshots.

I could not compile it. There is no command that shows how to compile it, so I reused what I found in the Makefile of the examples folder and adapted it. I just got a lot of error messages.
Starting with one prominent (the one) example on the documentation page and not getting a running example is rather discouraging.

I tried other examples from the examples-folder and had to tweak things there also, to get something that runs and makes sense.

Please fix the one example (or replace it with a working one) and add a line that can be used to compile the code.

[sleeptightAnsiC]

@klartext

Latest 65fefb1 changed that doc section a bit. It's now more clear about the snippet being just a pseudo code and suggests using the code from demo/ folders instead.

The documentation page https://immediate-mode-ui.github.io/Nuklear/ contains ONE prominent example [...] I could not compile it. [...] Please fix the one example (or replace it with a working one) and add a line that can be used to compile the code.

Not sure if I fully understand, but in case you're asking for - the ready-to-compile self-contained snippet which just-works - that's not easily doable, nor even possible tbh. Starting with Nuklear (or any other ImGUI-like library) heavily depends on setting up windowing and rendering of your choice (e.g. via SDL). Those things don't work out of the box and would require way more than few lines to get compiling from scratch. Unless... you had something different in mind?

I tried other examples from the examples-folder and had to tweak things there also, to get something that runs and makes sense.

May I ask what exactly you tried and tweaked?

[klartext]

There is Nuklear/example containing a file_browser.c

It has this code:

    media.icons.home = icon_load("../icon/home.png");
    media.icons.directory = icon_load("../icon/directory.png");
    media.icons.computer = icon_load("../icon/computer.png");
    media.icons.desktop = icon_load("../icon/desktop.png");
    media.icons.default_file = icon_load("../icon/default.png");
    media.icons.text_file = icon_load("../icon/text.png");
    media.icons.music_file = icon_load("../icon/music.png");
    media.icons.font_file =  icon_load("../icon/font.png");
    media.icons.img_file = icon_load("../icon/img.png");
    media.icons.movie_file = icon_load("../icon/movie.png");
    media_init(&media);

No images were displayed.
So I added an icon directory with some dummy-images one level above.

Now looking at this again, I see that there is a icon directory on the same level.
So the ../ was wrong.... at least if you start the program as bin/file_browser.
It works, if going into bin directory and then start ./file_browser.

Maybe there is a way to prevent confusions of this kind?

Btw, there are two file-browser files:

./demo/common/file_browser.c
./example/file_browser.c

This can also create some confusion.

It's also not clear to me, why there is a demo-directory as well as an example directory.
Which one is for what purpose?

[klartext]

It's now more clear about the snippet being just a pseudo code

Well, maybe it's clear (or at least "more clear") for someone, who is very fluent in reading Nuklear code.
As beginner of some topic/library, there is the natural tendency to just copy&paste code to get something running, and later look at it in more detail.

The pseudo code looks much like normal code. I remember pseudo code to be looking quite different, far away from what normal programming languages look like.

I guess it would be a good idea, to mention in the description above the code, that the code itself is pseudo code, by using the term pseudo code in the text, instead of expecting a beginner to see this at the first time they encounter that example.

[sleeptightAnsiC]

@klartext

There is Nuklear/example containing a file_browser.c [...] It works, if going into bin directory and then start ./file_browser. [...] Maybe there is a way to prevent confusions of this kind?

A common solution is for the app to change CWD to its executable dir before loading anything. I thought about adding it in the past, but not only this would be a headache to do portably in examples/file_browser.c and alike, it still won't solve the cases where someone moves the executable itself (this often happens when compiling from command line by hand)

That example already logs [SDL]: failed to load image: ../icon/home.png which I understand the beginner may not notice or not instantly associate with CWD being incorrect, but it's a really common gotcha that you will run into with many code samples that load assets. This is not only a problem with Nuklear examples, I've seen it all over C repositories.

(btw, the log printing [SDL] seems like some leftover... all Nuklear/example/ files use GLFW, not SDL...)

It's now more clear about the snippet being just a pseudo code

there is the natural tendency to just copy&paste code [...] The pseudo code looks much like normal code. [...] mention in the description above the code, that the code itself is pseudo code, by using the term pseudo code in the text

Sorry, I kinda misused the term "pseudo code" there. What I meant is: the snippet doesn't include any headers, lacks main(), and starting with 65fefb1 it does note about fake functions. This feels like more than enough now to prevent someone from believing it can be compiled.

I think the real problem is all information leading to that snippet, not the snippet itself nor wording right before it. README/documentation should be way more explicit about the library relying on external windowing and rendering. Right now, it drops the buzzwords like "no dependencies" which are misleading without clearly explaining what Nuklear essentially is.

Btw, there are two file-browser files [...] This can also create some confusion. It's also not clear to me, why there is a demo-directory as well as an example directory. Which one is for what purpose?

Short answer: just use the demo directory (IMHO)

Longer answer: some files under ./examples/* have duplicate code from ./demo/common/* with GLFW/OpenGL implementation slapped on it. I suspect the idea was to provide standalone main.c's that could be read without jumping between multiple files (this dates back to old repo at vurtun/nuklear) IIRC, only example/extended.c and example/skinning.c have any unique code worth checking. For everything else you should probably stick with demos instead. Those demos are more like "minimal backends" - meant to be reused next to Nuklear in case you don't want to go through the hassle of implementing it on your own.

[sleeptightAnsiC]

Also, please don't get me wrong, even though I might seem a bit "picky" about few details here, I still think your complaints are pretty much valid. The examples, demos, README, wiki, documentation are a mess... maybe adding a "Getting Started" section about building and running one of the demos step-by-step would be a way to go. I just don't have any good idea on how to do it right, and have few other issues in mind related to this one, e.g. #877 (comment)

[klartext]

Just turned from my working desktop to the private desktop... so I'm somewhat tired, and so I avoid to quote text here and just write some words without quotes. Otherwise it may end up in a mess ;-)

General remark on documentation: if it's easy to write something down in one or two sentences, that can avoid potential misunderstandings (people new to a topic, people distracted by something, people tired, people with ADHD, or some other reason), just add that text. If it's mentioned a second time later on - the better it sticks in (human) memory.
In that example I did not even noticed the missing main().
If there is a good (simple) example in the ´demo` directory, just using a link to that would make more sense (because it's working code (I hope)).

Working examples are a good motivator to look into something more deeply.
A library where the examples don't work are not very convincing.
Documentation can help a lot too.
But I think you see the problem.

You mentioned misleading words... and that the structure of Nuklear is not clearly documented.
Well, I also have no idea, on what level this library works.
If I have to use other libraries anyways, I might consider using them directly.
That might be more work in writing code, but less effort in learning a new library.

Either someone already knows the other libraries (GLFW, SDL, FLTK, or OpenGL/Vulcan etc.), then writing code directly on top of these might be easier to start with. Why then also Nuklear?
Or someone does not know these underlying Libraries, just starting with Nuklear - does this kind of person need to also know the other libraries?
That's not really clear to me.
Also... if I would use Nuklear instead of some other well known (big) GUI libraries... (Gtk, Qt, Tk, ...) for what kind of applications would that make sense? Do I need more time to learn Nuklear than for example Gtk (which also relies on other libs one might also need to learn)?
What kind of things are needed to know for using this library?

The thing with the backend... so I need to know one of these at least a bit I guess.

I think something like a diagram/graphics that explains the hierarchy of Nuklear would help.

For example diagrams like this one:
https://upload.wikimedia.org/wikipedia/commons/a/ab/GTK%2B_software_architecture.svg
or like this one:
https://en.wikipedia.org/wiki/GTK#/media/File:GDK_software_architecture.svg

[klartext]

Maybe give the icons directory a fixed relative path starting from the git-repo toplevel/root.

[sleeptightAnsiC]

@klartext (you're asking for many things, so I used my best judgement which one to answer)

Intermediate UIs, such as Nuklear or DearImGui, are useful when app already implements windowing / input / rendering / OS abstraction, and just needs to compose some simple UI elements. Example: debug overlay for video game.

UI frameworks, such as GTK / Qt / WinForms, come with literally everything, from abstracting window and rendering, to interpreting every single interaction a user may have with it. The scope of what those provide is magnitudes bigger.

Trying to compare UI frameworks to intermediate UIs is like trying to compare submarines to hydrobikes. I don't believe creating diagrams and listing all differences will be very useful in this case.

If you're interested in creating general purpose GUI application, then Nuklear is a rather bad idea for many reasons. The biggest one being that desktop users have specific expectations of how UI should behave. Using intermediate UIs might be OK for poweruser apps, where user experience doesn't matter as much, like debugger or hex editor

That said, how software works under the hood is not always obvious, and I've seen people getting confused about this already, many times actually. The README could definitely state few facts up front in order to prevent false assumptions.

(I guess, I will redirect people to this comment, the next time someone asks me a similar question)