Add Links Section

[tajmone]

• Append to main README a section of useful link to ALAN related projects and assets.
• Fix a couple of typos.
• Improve special chars.

[thoni56]

There's a lot of valuable links and extra information added here. Considering this is the compiler/interpreter repo, I just wanted to discuss if there is any other, better, place to host this collection.

It seems to belong in the "primary" repo, since we don't want to have duplicated copies of this information everywhere. But I don't know where that actually is. I can't find a way to have a a README for the alan-if organisation, so maybe it is this repo.

One suggestion could be to make a "links" document in the docs-project, then all README:s could point to it?

Other suggestions?

[tajmone]

There's a lot of valuable links and extra information added here. Considering this is the compiler/interpreter repo, I just wanted to discuss if there is any other, better, place to host this collection.

Yes, I imagined there were too many links, but I've copied and pasted them from the reference links document, which the ALAN Repository Template:

https://github.com/alan-if/alan-repository-template

The original idea was to fix the typos and add a couple of links, but I decided to paste them all and discuss which one keep. I believe there should be at least some important links, e.g.

• official website
• StdLib 2.0 repo
• Alan Docs
• this repo's Wiki

so even if someone ends up in a forked and outdated copy of this repository, he/she'll find his/her way back to some official sources, and then find more links there (bear in mind, forks usually don't fork projects' Wikis).

It seems to belong in the "primary" repo, since we don't want to have duplicated copies of this information everywhere. But I don't know where that actually is. I can't find a way to have a a README for the alan-if organisation, so maybe it is this repo.

True, there's no central repo with such a README that end users can contribute to and update with new links.

I think that the ideal place for a community-shared README and/or LINKS document would actually be the Wiki of this repository — and we do actually already have a links section there, in the Home page, although it might need some updates:

• https://github.com/alan-if/alan/wiki

As for the alan-if/alan-repository-template, that remains also an official source of links and information, since it has a higher priority when it comes to updates, due to the fact that third parties use it as the starting point for new ALAN related projects. But that said, it's not as easy to edit as a Wiki page, and will not contain links to every possible resource (whereas the Wiki does).

Another source of ALAN related links is the Awesome Interactive Fiction project, which has gained some popularity in the course of time:

https://github.com/tajmone/awesome-interactive-fiction#alan

One suggestion could be to make a "links" document in the docs-project, then all README:s could point to it?

I think the Wiki (of this repo) is a better choice, for it can edited on the fly via the WebUI, even by those who don't known how to use Git.

But still, we should keep a links section in the README of every ALAN related repository, albeit a smaller version, even if this adds some redundancy. It's important to show that the ALAN project is alive, and to stimulate visitors to discover them, and to promote these other projects.

Sometimes for me is quicker to just copy and past the whole links sections from the template repo, instead of having to go through all the links, checks their URLs, etc.

Other suggestions?

Let's decide which links to keep, and I'll fix the commit and force push it.

Also, I was thinking of using reference style links for the badges at the beginning, and move their labels at the end of the document which makes the source document more readable (e.g. in the terminal). Since I work a lot with markdown, I prefer to keep all labels organized at the end, so it's easy to update their URIs all in one place, and separate concerns. What to do you think?

[thoni56]

All valid points. A short "essentials links" section should probably be in most (all) READMEs, but it could probably be very short

• the website
• the wiki in this repo (good suggestion to have that as the canon link collection! Linking to it from over all probably makes us, and other, remeber that it exists ,-))
• a link to the organization github page
• google group

There might be one or two more, but to me that is the most vital ones.

It that is the set of links, then there's no need to go through them. You can just copy them as you suggest.

I have no objection to "footnote style" URLs. It is probably a good idea, especially in larger texts where links shows up more than once. If we are shortening this list, that would not be a problem, but I still have no particular objection...

[tajmone]

Done! I've reduced the links to the essential ones you mentioned, ad removed all the unused ref-labels definitions — except for two, which really ought to be used in the text:

[Artistic License 2.0]: https://opensource.org/licenses/Artistic-2.0
[Thomas Nilefalk]: https://github.com/thoni56 "View Thomas Nilefalk's GitHub profile"

there should be a License and Credits section in the README, so I've left those there for future use.

I've also slimmed the badges code by transforming them into ref-style links, moving their labels at the end of the doc — and took liberty to add a new LICENSE badge, and add some hovering text to the badges.

Note that the Jenkins badge from www.alanif.se takes ages to load, often failing to do so. There seems to be some problem there, I couldn't even open the link.

[thoni56]

Thanks. Will merge in a minute...

Yes, https://ci.alanif.se is currently down. It was running on my home computer and I have had to rebuild the complete Windows installation and haven't gotten around to that yet. It's actually the last thing on my list.

(It failed to boot because of missing boot information, tried to rebuild the boot information for days, but did not manage to get the Windows installation to start. I'm suspecting the virus protection had installed itself into the GPT-boot sector/process somehow and I could not get around that. Anyway now I have a fresh installation of Windows 10 ;-)

[thoni56]

I just realized that the StdLib should probably be amongst the essential links. Or what's you view? Re-reading the links I find them mostly pointing to "more information" kind of places, so maybe not?

[tajmone]

I just realized that the StdLib should probably be amongst the essential links. Or what's you view? Re-reading the links I find them mostly pointing to "more information" kind of places, so maybe not?

Well, which links are provided in the README largely depends on the type of repository.

Maybe this being an advanced repository (i.e. offering the ALAN sources) we might give for granted that whoever lands here has some knowledge of Alan (someone looking for the binaries will probably head to the website instead).

In any case, the Wiki home contains all the available links — maybe we should add next to the Wiki link "— for more links.".