Document posting a resource automatically creating a container (mkdir -p)

[timbl]

The current example and method used is to complicated. Simplicity and speed is important.

Instead of

• Create a new folder
• Create a new resource with a post and a slug

Just PUT the final result.

var post = '$rdf.sym(https://example.org/blog/hello-world#post1'); // post is what you need for the patch ex
var doc = post.doc(); 
var data = var data = '<#post1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/#Post> .';

Solid.web.put(doc, data).then(
    function(meta) {
        console.log(meta.xhr.status); // HTTP 200 (OK)
    }
).catch(function(err){
    console.log(err); // error object
    ...
});

So much simpler. Note that all the solid methods which take URIs should also take rdf symbol objects. This from long experience that is saves worrying about which you use.

We know solid server are required to do the mkdir -p when they get a request like this.

This also points out that it is better to use a local variable within the document than the document itself as an object.

[dmitrizagidulin]

I'm not sure it should be an instead. While we definitely should point out the 'just post something and it'll also create a container' capability, it is crucial that we also show how to create containers.

[deiu]

I agree with @dmitrizagidulin. This is a complete example, walking the user through different capabilities of the library. Basically a full CRUD example. The PUT operation that creates a full path is actually a feature of Solid (spec) not Solid.js.

[timbl]

This documentation should not be of the form "we assume you know all about LDP and containers and RDF and Solid servers, and we want to show you how to do client-side LDP operations faster than you could before". It doesn't matter one inch that The PUT operation that creates a full path is actually a feature of Solid (spec) not Solid.js. Solid.js is not a toolbox for doing LDP with all its warts. It is an API for making apps, and it should cater to what the app dev is thinking and needing.
Or, alternatively if yo want to make solid.js a tutorial to the solid spec, then lets fork it and build separately something optimized for real developers.
The title "Slug etc overly complicated, should suggest users just PUT new resource" is what I meant.

[timbl]

If you want a CRUD example then you need
C
R
U
D

Not
C container
C object fingers crossed
Check slug was actually used
R
U
D

The longer version gets more complicated when you have to check for things pre-existing or not also.

[deiu]

@timbl agreed. The examples here are trying to reflect the functions provided by the library. It's not really a tutorial on how to build an app. In fact, it's something between a README and an API doc, with a few examples that try to stay within the same context. I will try to add some text which reflects this fact, as well as links to the real app tutorial.

[dmitrizagidulin]

Let me attempt to clarify terms, so we can specify what we're arguing about. :)

Solid.js is not a toolbox for doing LDP with all its warts. It is an API for making apps, and it should cater to what the app dev is thinking and needing.

Specifically, Solid itself (as in solid-spec) is an API for making apps, that should cater to developer convenience. solid.js is simply a client-side implementation of that API.

Now, it so happens that the Solid spec is currently based on LDP. And I agree, since Solid is a set of extensions and improvements and clarifications on LDP, it should not be just be a toolbox for doing LDP with all its warts. And so if something in it causes developer awkwardness or pain, we should extend or modify the spec to solve that.

Solid.js, however, is just some syntactic helper code for using the Solid API (not the LDP API). It is, by definition, a toolbox for using Solid with all its warts.

If you want to make solid.js a tutorial to the solid spec, then lets fork it and build separately something optimized for real developers.

So, given the terms above, a solid.js tutorial kind of has to be a tutorial on the solid spec. And we shouldn't fork the tutorial (or the library), but instead modify the spec when needed, and then modify solid.js to match it.

If you want a CRUD example then you need ...

I agree that CRUD tutorials should be simple. But what's getting lost here is that we're essentially documenting two CRUD workflows:

1. A CRUD for Solid containers
2. A CRUD for resources within those containers.

So, I agree with you overall, but I want to make sure we're not skipping important parts of the tutorial.