Adding Tutorial in Readme

This commit is contained in:
jyamihud 2022-04-02 11:28:46 +03:00
parent 55f375a49f
commit 1d1a3cb175
2 changed files with 129 additions and 13 deletions

131
README.md
View file

@ -10,7 +10,7 @@ FSF likes the word "Replacement" more then "Alternative" since "Alternative" mea
# License
This software is under the terms of AGPLv3 or any later version. So image GPLv3 or later with one more requirement. You need to publish the source code of the website, if you are serving it. It has a handy button for source if you change nothing. If you change something, please upload your own version to some place and link to your source instead. Please see LICENSE file for more info.
This software is under the terms of AGPLv3 or any later version. So imagine GPLv3 or later with one more requirement. You need to publish the source code of the website, if you are hosting it. It has a handy button for source if you change nothing. If you change something, please upload your own version to some place and link to your source instead. Please see LICENSE file for more info.
# Installation
@ -18,9 +18,11 @@ The software is built on Python. So you will need to have python3 installed. The
`python3 server.py`
It will prompt you to select a `PORT`. To which on your end to bind the server. For now it binds it to your localhost. You can edit that part. We are using a standard SimpleHTTPServer python module for it.
It will prompt you to select a `PORT` to which on your end to bind the server. For now it binds it to your localhost. You can edit that part. We are using a standard SimpleHTTPServer python module for it.
# How it works
Please tell us if you start an instance. We want to add it's link here.
# How it works?
In [apps](apps) folder there are a bunch of .json files with different data about various software. When the user types in the name of the software, it looks for a closest match of the name. So the user can slightly misspell the name and it will give him the software. Like somebody can type "What's Up" and get "WhatsApp".
@ -28,16 +30,123 @@ Next, based on the other data, like features, file formats and supported network
The algorithm avoids recommending Non-Free Software. So if you type "WhatsApp" it will recommend you "Element" and other Free Software messengers. But if you write "Element" it will recommend you only Free Software messengers. "WhatsApp" will be excluded. It is done by referencing the "licenses" data-point.
# API
When talking to an instance over the normal HTTP insert a `/json/` between the domain name and the search request. So instead of `domainmane.site/youtube` do `domainname.site/json/youtube` and it will give you the same results but formatted as a json.
# Adding new software
Do add software let's look at two examples from the [apps](apps) folder:
This is the json for Blender.
```
{"names":["Blender"],
"comment":"Blender is a Free Software 3D creation suite. It supports the entirety of the 3D pipeline-modeling, rigging, animation, simulation, rendering, compositing, motion tracking and video editing.",
"links":{"website":"https://www.blender.org/",
"git":"https://git.blender.org/gitweb/gitweb.cgi/blender.git",
"wikipedia":"https://en.wikipedia.org/wiki/Blender_(software)",
"documentation":"https://docs.blender.org/manual/en/latest/",
"icon":"https://download.blender.org/branding/square/blender_icon_64x64.png"},
"licenses":["GPL-2.0-or-later"],
"platforms":["GNU/Linux",
"Windows",
"MacOS",
"BSD",
"AmigaOS",
"Solaris"],
"interface":["opengl"],
"languages":["C"],
"networks_read":[],
"networks_write":[],
"formats_read":["blend",
"dae",
"abc",
"usd",
"usdc",
"usda",
"svg",
"bvh",
"ply",
"stl",
"fbx",
"glb",
"obj",
"x3d",
"wrl"],
"formats_write":["blend",
"dae",
"abc",
"usd",
"usdc",
"usda",
"svg",
"pdf",
"obj",
"ply",
"stl",
"fbx",
"glb",
"gltf",
"x3d"],
"generic_name":["Text Editor",
"Video Editor",
"3D Modeling",
"3D Rigging",
"3D Animation",
"3D Rendering",
"Compositing",
"Motion Tracking"]}
```
Since it's Free Software it's important to give the users links to it's core things. Like the Website where they get a copy and learn more about it. Like the git ( or other version control ) repository of source code. Like the documentation.
Notice the `icon` datapoint. It links to `download.blender.org`. This way we give away some of the website's load to other websites. Usually Wikipedia has a lot of icons for a lot of software.
It's also very important to list at least the core file formats / networks that it supports. If you are adding something like Emacs or Gedit which are text editors that can edit text with any extension, please then list the text encoding that it supports. Like `ASCII` or `UTF-8`. Usually they are listed in Save or Open menus.
The idea here is not to document the software precisely. We are not making a Wikipedia. The idea is to compare features between software to give users a relevant replacement / alternative.
Also note the `licenses`. You should be careful. In the [data](data) folder there is a licenses list file. We use it to see if the license is Free or not. So please make sure you are using the correct formatting of the license's name. Use `licenseId` preferably.
Not let's look at a proprietary program YouTube:
```
{"names":["YouTube",
"You Tube",
"youtube.com",
"youtu.be"],
"comment":"A platform for uploading and watching videos.",
"links":{"website":"https://youtube.com",
"wikipedia":"https://en.wikipedia.org/wiki/YouTube",
"icon":"https://upload.wikimedia.org/wikipedia/commons/thumb/0/09/YouTube_full-color_icon_%282017%29.svg/120px-YouTube_full-color_icon_%282017%29.svg.png"},
"platforms":["Android",
"iOS",
"Web"],
"interface":["HTML5"],
"languages":["JavaScript"],
"networks_read":["youtube"],
"networks_write":["youtube"],
"formats_read":[],
"formats_write":[],
"generic_name":["Video Player",
"YouTube Client",
"Music Player",
"Publication"],
"issues":["Surveillance",
"Non-Free Software",
"Non-Free JavaScript",
"DRM"]}
```
With surveillance software we try to avoid linking it's icon from the website itself. It should not even try to connect to the bad website. We don't know what they are doing with the server logs. So here it's very important to use Wikipedia. Alternatively you can host the logo yourself somewhere. Perhaps on LBRY. And use a spee.ch link to it.
Also notice the additional `issues` datapoint. It's important to have a list of Anti-Features. Try looking at F-droid.org for inspiration of this. Telegram, by the way, has Anti-Features even though it's Free Software. So we list them.
Again, remember, we are looking for similarities of data. Not documenting everything. Things like `generic_name` plays a big role in finding the replacements / alternatives. File formats and networks play a bit role too. If in `photoshop.json` it will have a generic name "Image Editor" and in `gimp.json` it will have "Editor of Images" it will fail to find the match. So please study the files before adding a new one.
It is quite important to fill as much as possible data about Non-Free Software too. Even though the data will never be shown to the user. Because we want to compare the features and the formats to find Competitors. And later other functions may be added that use such a data.
# Help this project!
To help this project you may do one of three things:
- **Host it:** Open a website with this server software and make it be available to the public. Please tell us if you do it, we will include you in here.
- **Add software:** Add more software into the database. See the files in [apps](apps) for it. Please study multiple files before making new ones. And please check them by running the server and going to `localhost:[port]` in your browser. Sometimes you may make syntax errors in the json. It will fail to load the file. If there will be an error like this, it will output the filename and the line where the error occurred into the terminal.
- **Contribute to Server Software:** We need things like CSS work, better looks. One requirement: it has to not have any JavaScript what so ever. But as long as it HTML5 and CSS it's fine. Also please look at the algorithms themselves. They may need a bit of work.
# Contact info
We hang out on [matrix] in `#freecompetitors:matrix.org`

View file

@ -1,5 +1,5 @@
{"names":["Blender"],
"comment":"Blender is the free and open source 3D creation suite. It supports the entirety of the 3D pipeline-modeling, rigging, animation, simulation, rendering, compositing, motion tracking and video editing.",
"comment":"Blender is a Free Software 3D creation suite. It supports the entirety of the 3D pipeline-modeling, rigging, animation, simulation, rendering, compositing, motion tracking and video editing.",
"links":{"website":"https://www.blender.org/",
"git":"https://git.blender.org/gitweb/gitweb.cgi/blender.git",
"wikipedia":"https://en.wikipedia.org/wiki/Blender_(software)",
@ -46,4 +46,11 @@
"glb",
"gltf",
"x3d"],
"generic_name":["Text Editor", "Video Editor", "3D Modeling tool"]}
"generic_name":["Text Editor",
"Video Editor",
"3D Modeling",
"3D Rigging",
"3D Animation",
"3D Rendering",
"Compositing",
"Motion Tracking"]}