Improving examples.

[davidlehn]

Some ideas for helping new folks figure out how to use this service. I've had these ideas rattling around in my head for years, might as well note them here.

@dgarijo started with an ontology example in #1639. (That has been needed for a long time. Thanks!)

• Long ago I had thought of having two example locations. example/ with a really basic example, more like a template for just having a .htaccess and README.md to get started and redirect something to https://example.com/. Then have a secondary examples/ that has a handful of subdirs for various use cases. In this case the new example dir would be under something like examples/ontology/.
• Refer people to appropriate Apache docs (also noted in a simple tutorial for common redirecting examples? #1530)
• Add other examples based on patterns we've seen other people using over the years.
  • Simple redirects.
  • Pattern matching and replacement.
  • All in one file cover subdirs vs multiple directories.
  • CORS compatability.
  • It hasn't been an issue before, but show how to avoid serving the local README.md if you don't have a wildcard redirect that covers that.
• Figure out which .htaccess options are commonly needed and document them and why they are there.
• The root README should point people at the examples.
• The main homepage should point people at the examples.
• Figure out if info and maintainer info in .htaccess is ok vs putting in README.md. Recently it was suggested to just use README. I had originally thought it would have been the other way.
• Add github PR magic info file with link to or an inline checklist for common issues we've seen (no maintainer info, etc).

I'm sure there's more... if anyone has ideas, add a comment.

[dgarijo]

Thanks, @davidlehn,
I created the example also because I am writing a longer tutorial on best practices for ontology publication (I am using https://w3id.org/example#). Would you rather have the URI located under example/ns?

Right now it does not prevent other people from doing their own examples, but just in case you had something else in mind.

[davidlehn]

@dgarijo I'm not sure what the layout should be. Open to discussion. I'm just guessing that since no one likes to read docs, they will immediately look to example(s)/ type dirs and copy & modify those. So those dirs should have some examples of current best practices for various use cases. Ontology publication is certainly a good use case! Unsure how to organize so people can see how to do simpler things too.

[dgarijo]

Ok, my proposal then is as follows:
Let's create an "examples" directory. Inside, we can have "ontology", which will redirect at the "example"directory I already did (plus a few explanations on a readme file)
And then other examples for a simple 301/302 redirection, add in the readme how to add yourself as a person, etc.
That way I won't have to change the w3id I already created.

[ramonawalls]

this would be great

[melvincarvalho]

Quite late to this issue, but this is a great resource:

https://htaccess.madewithlove.com/

It allows you to test your rewrite rules without the need to run a local server

[bact]

I have create PR #3599 to address some of the items we have proposed here.

[dgarijo]

@bact you were changing one of my w3ids in your PR, and I had to close it. I do not want to redirect w3id/example to example.com. Please add a new PR with the examples folder :) Thanks!

[bact]

Sorry @dgarijo I misunderstand that.

I should follow this proposal instead.

Ok, my proposal then is as follows: Let's create an "examples" directory. Inside, we can have "ontology", which will redirect at the "example"directory I already did (plus a few explanations on a readme file) And then other examples for a simple 301/302 redirection, add in the readme how to add yourself as a person, etc. That way I won't have to change the w3id I already created.

[bact]

New PR #3600 is created. Please kindly comment and suggest any change you feel needed.

I have revert the original files of /example back from previous commits. Apologize for messy commits.

[bact]

PR #3600 is successfully merged and we now have /examples, with two subdirectories:

• /examples/ontology redirects to https://w3id.org/example
• /examples/simple redirects to https://example.com

It also has /examples/README.md containing three examples with explanation:

1. Minimalist (grouping)
2. Supporting multiple media types (MIME types)
3. Dealing with query string

The README has a quick intro to .htaccess as well, but

• still lacks explanation on options commonly found, like Options +FollowSymLinks and Options -MultiViews
• no explanation/recommendation on redirect status yet (302, 303, or 307?)

We may also need to update /README.md (top-level) to link to this.

--

The examples/ directory currently does not have .htaccess of its own.

I'm thinking may be we can just redirect it to https://github.com/perma-id/w3id.org/tree/master/examples and the visitors will see examples/README.md from there. (now in PR #3601)

What do you think?

[dgarijo]

Thanks! I think the examples dir should probably resolve to your suggestion. Your PR is now merged.