A few documentation issues to fix

[perminder-17]

Here's are some of the specific updates to make:

• Document the default value of the ends property (the default is INCLUDE), at least on the splineProperty() page. The splineProperties() page can link to that.
• Replace the broken link to curve() with a link to spline(), on the splineVertex() page.
• Fix spline() examples.
• Fix splinePoint() examples.
• Fix splineTangent() examples.
• Add code example for the ends property to the splineProperty() page.
• Typos, language cleanup 1 (since language complexity and typos affect accessibility)
• Revise top-line descriptions that appear on the main reference page? For example, for splineVertex(), we might replace "Adds a spline curve segment to a custom shape" with "Connects points with a smooth curve (a spline)." This is less pressing, but a more beginner-friendly explanation focused on the main use case may improve discoverability significantly.

[perminder-17]

Hi @GregStanton, thank you for your comment on this issue (link). It helped me make a clear checklist, and I believe I’ve fixed the points you mentioned. I’m also checking the math parts to see what might be missing.

If you know any other examples, docs, or tutorials that need updates, please let me know and I’ll fix them quickly. If you have time, your review on this PR would be very helpful for future readers. I’m happy to improve anything else you suggest. Thanks again!

For reference, here’s the code I’m using for ends (INCLUDE/EXCLUDE): https://editor.p5js.org/aman12345/sketches/wXMOd_gxe

[davepagurek]

The changes are looking good!

We can optionally do this in another PR, but because all the examples are ports from 1.x where it only had EXCLUDE mode, the examples for spline and splineVertex currently demonstrate mostly the more complicated EXCLUDE case. I feel like the first thing people should see, and see most of, would be the INCLUDE case. It's a bit of a bigger undertaking so it's ok to wrap up and merge this one first. I think the other improvements we could make would be:

• For splineVertex, show some examples of drawing shapes without editing the default end mode
• For splineVertex, show examples of smooth loops using endShape(CLOSE), like in this example @GregStanton sent me a little while ago: https://editor.p5js.org/highermathnotes/sketches/lyeF29D_v
• For spline, also show some examples first without changing to EXCLUDE mode
• In splineProperty, show examples for tightness right after describing it using the interleaved example syntax, and then put the INCLUDE/EXCLUDE description + examples after that
• Update splinePoint examples to use INCLUDE
• Update splineTangent examples to use INCLUDE

[davepagurek]

I think we've got another curve() reference later in this doc on line 1683 that needs a similar update.

[davepagurek]

Also later on in this doc, some things to correct:

• Splines are defined by two anchor points and two control points.

  This explanation only applies to the non-default EXCLUDE mode now, we can maybe replace this with @GregStanton's concise explanation, "splineVertex() draws a smooth curve through the points you give it."

• splineVertex() must be called at least four times

  I think this is no longer true, thanks to the default INCLUDE ends mode. Two points also works, it just draws a straight line. So we can probably take out that restruction entirely.

• The code examples talk about control points and anchor points. In the default ends mode, all vertices are anchor points, since the cable goes through all of them.

• The code snippet above would only draw the curve between the anchor points, similar to the curve() function. The segments between the control and anchor points can be drawn by calling splineVertex() with the coordinates of the control points

  Similarly, this is also no longer the case with the INCLUDE mode, and it'll go through allt he points immediately. So this distinction and the snippet that follow can be removed.

[davepagurek]

With the default INCLUDE mode, we don't need to double the first and last vertex, it'll go through them automatically, so we can take this and the last splineVertex line out!

[davepagurek]

Also some notes for the spline docs:

• Splines are defined by two anchor points and two control points.

  Like splineVertex, this is only true for EXCLUDE mode. In the default mode I think it just goes through all the points, making them anchor points.

• The first two parameters, x1 and y1, set the first control point. This point isn’t drawn and can be thought of as the curve’s starting point.

  This and the last point do get drawn now by default, so we'd need to update these explanations too. We probably don't need a parameter-by-parameter description any more since they all function similarly to each other.

I think this control point / anchor point distinction currently also exists in splinePoint and splineTangent and can be taken out there too.

[GregStanton]

@perminder-17:

Thanks for moving this forward! Based on your work and the detailed review that @davepagurek did, I'll outline an approach to tackling these docs. I'll include draft docs and code examples for some of the key features. I hope this does two things:

1. Make it easier for you to update the docs.
2. Make it easier for users to understand the docs.

Please let me know if any of this is unclear, and if you want to ping me again for a review, I'd be happy to take another look! Also, I'm okay with whatever you two decide regarding whether or not to do a separate PR for the larger changes.

splineVertex()

As @davepagurek's review shows, there are a lot of updates to be made if we try to adjust the docs line by line. That's because the current documentation is based on the old docs for curveVertex(). But splineVertex() is a new feature! It's not just the name that changed, and we didn't just add on some capabilities. So it requires new docs, not adjusted docs. But don't worry... We designed the new feature to be extremely intuitive, which means documenting it is much easier than documenting the old feature.

Below, I'll outline how the new docs could look. Note that the typical flow of these reference pages uses Dave's interleaved-example feature and goes like this:

1. Brief, general explanation.
2. Short explanation of one usage pattern.
3. Example.
4. Short explanation of another usage pattern.
5. Example.
6. Etc.

The idea is to place explanations alongside examples, instead of putting all the explanations in a wall of text at the top, followed by a list of examples. This is based on the spatial contiguity principle: "corresponding information is easier to learn in a multimedia format when presented close together rather than separate or farther apart."

Description

Connects points with a smooth curve (a spline). That's the whole description!!! We can add a couple links to other features below that:

The splineVertex() function must be called between beginShape() and endShape(). See splineProperty() for ways to customize splines made with splineVertex().

Example: Basic usage

If you provide three points, the spline will pass through them. It works the same way with any number of points.

source code

Example: Basic closed spline

Passing in CLOSE to endShape() closes the spline smoothly. (This is already documented on the reference page for endShape(), but adding a different example on the splineVertex() reference page makes the feature easier to discover.)

source code

Example: Advanced closed spline

Thanks @davepagurek for sharing my animated blob example. It's reasonably short, and it's kind of cool, so it might inspire some creativity. But it's also not a totally minimal example (it uses noise(), for example). If we do include it, I suppose it should go at the end. What do you two think?

splineProperty()

The old behavior with excluded ends can be described here.

Description

I'll jot down some rough docs here, to give a feel for how this can look.

Gets or sets a given spline property

Use splineProperty() to customize splines made with splineVertex() or spline(). Two properties of splines can be customized: ends and tightness.

By default, the ends property has the value INCLUDE. This means the spline is drawn through all points, including the endpoints. The other possible value is EXCLUDE. This means the spline is drawn through all points, excluding the endpoints.

// Interleaved example: Excluded ends (see further below for details)

By default, the tightness property is 0, which creates a smooth curve passing through the vertices. Values less than zero make the curve pass more loosely through the vertices. Values greater than zero make it pass more tightly. Typical values are between -1 and 1, but values outside this range may be used.

// Interleaved example: Tightness (see further below for details)

In all cases, the splines in p5.js are cardinal splines. When tightness is 0, these splines are often known as Catmull-Rom splines.

For a more concise way of setting multiple spline properties, see splineProperties().

Note on terminology: Throughout, I avoided jargon like "control point," "anchor point," or "span." It's generally good to keep the language as simple as possible without sacrificing accuracy. The docs for Bézier curves in p5.js already use "control" and "anchor," and that might be helpful in that context; however, those terms are used inconsistently in the literature, which can cause confusion. For example, the Wikipedia article on Bézier curves refers to all the defining points as control points. With splines, there seems to be a greater chance of confusion, due to the differences in the ends modes. So at least for splines, it may be best to avoid using these terms for the time being.

Example: Excluded ends

The slope of a spline at each vertex matches the slope of the line segment connecting its neighbors. So, when ends are excluded, they become invisible points that can be used to adjust the spline's shape.

source code

Example: Variable tightness

The existing example of tightness on the splineProperty() page is great. I think it'd be even better with a couple simple tweaks: visible vertices and a dynamic tightness label. Then the user can see how specific tightness values affect the way the spline wraps around the vertices.

The code changes are indicated below. Note the new description passed to describe() and the extra code added at the end.

// Move the mouse left and right to see the curve change.

function setup() {
  createCanvas(100, 100);

  // NEW DESCRIPTION

  describe('A black spline forms a sideways U shape through four points. The spline passes through the points more loosely as the mouse moves left of center (negative tightness), and more tightly as it moves right of center (positive tightness). The tightness is displayed at the bottom.');
}}

  // SAME CODE AS BEFORE
  // ...

  // EXTRA CODE
  push();
  strokeWeight(5);
  point(10, 26);
  point(10, 26);
  point(83, 24);
  point(83, 61);
  point(25, 65);
  point(25, 65);
  pop();

  fill('black');
  text(`tightness: ${round(t, 1)}`, 15, 90);

Example: splineProperty() affects spline() too

One example to show that spline() is affected by splineProperty() should be sufficient.

splineProperties()

All that's needed here is one example where multiple properties are set at the same time, and one example of splineProperties() being used as a getter for all available properties. Unfortunately, there seem to be some bugs...

Possible bug

The splineProperty() and splineProperties() features don't seem to work properly as getters. If you try console.log(splineProperty('ends')), I think you'll get null instead of the default value INCLUDE, and if you try console.log(splineProperties()), you'll get an object with the tightness property but not the ends property. But console.log(splineProperty('tightness')) works correctly. So it seems that the issue is only with ends. I tested this in 2.0.4. Would either of you mind filing a bug report, @perminder-17 or @davepagurek? It may be a good issue for beginners, and if so, it could be tagged as such.

Other spline-related features

The docs for other spline-related features—spline(), splinePoint(), and splineTangent()—can be updated similarly. As with the page for splineVertex(), the description and examples can all be entirely in the default mode (so it's not necessary to talk about control and anchor points, or about excluded endpoints not being drawn). In particular, instead of adapting the old examples so that they run as before, it may be better to start anew with simpler examples using the new default mode. I think the only place where excluded ends need to be mentioned is the splineProperty() page, and other pages like the spline() page can link to that.

General documentation issues

If you know any other examples, docs, or tutorials that need updates, please let me know and I’ll fix them quickly.
—@perminder-17

I'm glad you're working on this! Once we finish the spline docs, we can go from there. In general, the beta site needs a lot of attention. I checked a small random sample of pages a while back and found a lot of existing problems (I made a list). I only say that to clarify that some coordination might be required, possibly including stewardship of other volunteers. So once you're ready, let me know, and we can come up with a strategy. We might need to have a quick video call. Does that sound okay?

[perminder-17]

Thank you all for your inputs. I’ll update and fix this PR, and also draft a new one with the changes suggested by @davepagurek and @GregStanton.

Once I feel this PR is in good shape, I’ll request a review from the maintainers. There’s still a bit of work left, so really thanks everyone for the guidance and patience.

[perminder-17]

Thanks everyone for the help and feedback. I’ve incorporated several suggestions in this PR, but it’s already quite large and tough to review. I’ll open a follow-up PR to handle the remaining items:

• Update the splineProperties reference with a short description and a few example sketches.
• Add some more spline() example that uses ends: INCLUDE.
• Open a PR in p5.js-website to fix asset handling where images were being uploaded directly.
• Add this example demonstrating ends: EXCLUDE to both splineVertex() and splineProperty() pages.
• Add additional examples to splinePoint().

@davepagurek @GregStanton Can you review it once and let me know what else I am missing. Maybe something which is not technically correct, (it's my first time working with math stuffs, so sorry for any oversight.)

[ksen0]

Thanks so much for all your work on this @perminder-17 . Just a couple of minor things.

[ksen0]

Minor: "Think of them simply as “points on the curve.”" -> "Think of them as points on a curve"

[ksen0]

I saw your comment that other PRs are coming - would be great to avoid committing TODOs where possible, but I understand if this is really needed in this case to make sure it's not forgotten!

[perminder-17]

Yes, I was just locating on which part I need the images to explain, so I wrote there and forgot to remove them. Just need to open up a PR in p5.js-website to include those images.

[ksen0]

I'm guessing this example needs something like this at 2014:2021:

      beginShape();
      splineVertex(10, 26);
      splineVertex(83, 24);

      splineVertex(83, 61);
      splineVertex(25, 65);
      endShape();

[perminder-17]

Thankyou for catching this.

[perminder-17]

By the way, I just wanted to check if there are any additional suggestions apart from the image uploading changes for the p5.js-website. If there isn’t anything else to address at this point, I was thinking of respectfully merging this PR and then opening up follow-up PRs to continue working on the remaining tasks. #8031 (comment)? @davepagurek @ksen0 @GregStanton ?

[ksen0]

@perminder-17 Looks great to me, thanks so much for the careful iteration. Your plan sounds good, please feel free to merge.

[perminder-17]

Thanks, I'll draft follow-up PR's very soon.