WebSVN – SvarDOS – Diff – /website/help/help-en.amb


AMB1index.amaöïwpkg.amaåD0.network.ama)¶lcontact.amaB±°pkgfmt.amaEhJpkgrules.ama­ÊXlicense.amaÇGmeaning.amamUtodo.ama"ÜMfreedos.ama*M
[Âhistory.amae4Þ¥RtitleC;!ÿ
                            %h*** SVARDOS HELP ***
 
This help documentation is a work-in-progress thing. For the time being it
provides only very limited content. (wanna help building it? get in touch with
us on the SvarDOS %lcontact.ama:mailing list%t!)
 
=== Chapters =================================================================
 
 * %lpkg.ama:Packages management (install/remove/update software)
 * %lnetwork.ama:Networking
 
 * %lfreedos.ama:SvarDOS vs FreeDOS: what is the story?
 * %ltodo.ama:The project's "TODO" list
 * %lcontact.ama:How do I get in touch with the SvarDOS community?
 
 * %lhistory.ama:SvarDOS origins
 * %lmeaning.ama:What does "Svarog" mean?
 
==============================================================================
 
%hSvarDOS packages management
 
To install or remove software on your SvarDOS system, use the "pkg" command.
pkg is a package manager to allow installing new software from SvarDOS
packages and removing exising software from the system. To learn about exact
pkg usage, type pkg /? in the SvarDOS command line shell.
 
You may obtain many SvarDOS packages from the SvarDOS web homepage at
<http://svardos.osdn.io>. If your system is connected to the internet, then
you may also use the SvarDOS "pkgnet" command. pkgnet is a network tool that
makes it easy to search for SvarDOS packages in the SvarDOS repository and
download them right away. Type pkgnet /? in the SvarDOS command line shell to
learn about exact pkgnet usage.
 
See also:
 * %lpkgfmt.ama:The technical format of a SvarDOS package
 * %lpkgrules.ama:Packages inclusion rules
 
%hNetworking
 
WRITE ME!
 
%hHow do I get in touch with the project's community?
 
The recommended way to contact the SvarDOS community is through the project's
mailing list: <https://lists.osdn.me/mailman/listinfo/svardos-users>
 
The project's web homepage is <http://svardos.osdn.io>
 
Package files provide an easy way to manage software on SvarDOS. These
packages must adhere to a strict convention so they can be handled properly
by the SvarDOS package manager.
 
 
%hPackage filenames
 
Packages names must follow some basic rules. They shall be max. 8 letters long
(but should not be too short either, since a 1 or 2-letters package name might
be confusing), and must not be composed of characters other than a-b, 0-9 and
'_'. This for backward compatibility with short file names (8+3) and ISO 9660
file systems (used on CDROMs). The package filename is always followed by the
.ZIP extension.
 
 
%hPackage files
 
SvarDOS uses ZIP files as its package file format. This format has been chosen
because ZIP files under DOS have become the de facto way to distribute
collections of files. Also, the ZIP file format is well documented, well
supported, and in the public domain.
 
Here below is the recommended command line that can be used to create a
package for a program named EXAMPLE using info-zip:
 
  zip -9rkD EXAMPLE.ZIP subdir1 subdir2 ... subdirN
 
If you are using 7za to create your packages, then use this:
 
  7za a -mm=deflate -mx=9 -tzip EXAMPLE.ZIP subdir1 subdir2 ... subdirN
 
 
%hPackage directory structure
 
The directory structure of a package depends on the type of packages.
For "core" packages, we have this:
 
  APPINFO            Put the program's LSM file here
  BIN                Binaries, such as exe and com files
  DOC\%PKGNAME%      Package documentation
  HELP               Used ONLY by the "help" package
  NLS\%PKGNAME%      Localizations (NLS language files) of the package
  SOURCE\%PKGNAME%   The source code (optional)
 
Non-core packages use a slightly different directory organization. For
example, if we were to consider a package FOO, we might end up with the
following structure:
 
  APPINFO\FOO.LSM    Package meta file for the FOO program
  PROGS\FOO\FOO.EXE  The program's executable
  PROGS\FOO\FOO.TXT  Some documentation
  PROGS\FOO\FILE.DAT Data file used by the FOO program
  SOURCE\FOO\*       here would be stored the foo's source code (optional)
 
Note the 'PROGS' directory above. This is a category to which the package
belong. The package installer might change this directory at install time,
depending on the user's preferences. Possible categories are listed below:
 
Category | Description
DEVEL    | Development tools (mostly compilers)
DRIVERS  | Drivers
GAMES    | Games
PROGS    | User programs, tools...
 
Note: "DOC", "NLS", "BIN" and "HELP" directories are strictly reserved to
      CORE packages.
 
%hLSM meta-data files
 
Every package MUST contain an LSM file in its "APPINFO" directory. This LSM
file is a text file that contains basic information about the package. Its
format is very simple, it must contain at least two lines:
 
  version: x.y.z
  description: package description
 
Any other lines are ignored by the SvarDOS package manager.
 
                     %h*** Packages inclusion rules ***
 
SvarDOS is a DOS distribution that comes with plenty of third-party packages.
With time, packages get updated and new packages are being added. However,
SvarDOS is not a shareware distribution CD, nor it is a "warez" production of
any kind. Every software that is distributed within SvarDOS must comply to a
few common sense rules, as listed below.
 
%hObjective usefulness
 
The distributed software must be useful. There is no point in distributing
hundreds of "Hello World" programs for example. The software must be useable
as a finished product and provide some features that are proven to be seeked
by at least a subset of the user base. Games are considered useful, as long as
they fulfill their goal of providing actual distraction.
 
%hReasonable quality
 
The packaged program must exhibit traits of reasonable quality. This means
that it should have a deterministic behavior, and be free of undesirable
side-effects to the user's computer (not crashing, freezing, resulting in
unexpected loss of data, etc). It should also provide clear, non-ambiguous
instructions to the user about how the program is meant to be used.
 
%hFree (no cost)
 
The program must be free - that is, available at no financial cost. It doesn't
have to comply to an OSI-approved license or be open-source (even if that
would be preferred), but at the very least it must be free for personal,
non-commercial use.
 
%hDistribution allowed
 
The program must allow distribution without restrictions, and must not forbid
being redistributed in a re-packaged form.
 
 
%!CORE EXCEPTIONS
 
Please note that, while the above rules are valid for all third-party packages
that may be distributed with SvarDOS, it does not apply to the 'core' packages
that contain the operating system itself. SvarDOS being a free (as in "libre")
operating system, all "core" packages must comply to a libre-like license - be
it GPL, BSD, MIT, public domain, or anything that allows for unrestricted
distribution, provides source code and allows to modify it freely.
 
%hSvarDOS licensing
 
SvarDOS is a DOS distribution made of many different software bricks, hence a
single license can hardly be applied to all. However, the CORE system (that
is the SvarDOS installer, bootable floppy image and all core packages) is
carefully assembled from software that is "free" (as in "Freedom"), ie. that
grants the 3 basic FOSS liberties: freedom to use, modify, and redistribute.
This includes, but is not necessarily limited to, software released under
following licenses: GNU GPLv2, GNU GPLv3, BSD, MIT, EUPL and Public domain.
 
Note that, while the above applies to the core of the SvarDOS distribution, it
does not cover all extra packages. Additionnal software packages may or may
not be FOSS, they are only guaranteed to be "gratis for non-commercial use".
 
Read more: %lpkgrules.ama:Packages inclusion rules
 
%hWhat does "Svarog" mean?
 
The "Svar" in SvarDOS refers to "Svarog". SvarDOS is the successor of the
Svarog86 and Svarog386 distributions.
 
Excerpt from Wikipedia, the free encyclopedia:
 
 Svarog is a Slavic deity (...) identified with Hephaestus, the god of the
 blacksmith in ancient Greek religion (...), some researchers conclude that
 Svarog is the Slavic god of celestial fire and of blacksmithing.
 
 The only mention of Svarog comes from the Hypatian Codex, a 15th-century
 compilation of several much older documents from the Ipatiev Monastery in
 Russia. (...) The complete passage, reconstructed from several manuscripts,
 translates as follows:
 
 "(Then) began his reign Feosta (Hephaestus), whom the Egyptians called Svarog
  ... during his rule, from the heavens fell the smith's prongs and weapons
  were forged for the first time; before that, (people) fought with clubs and
  stones."
 
%hSvarDOS: The project's TODO list
 
* Replace the default (FreeDOS) edit with a smaller alternative (?) that is:
  - TINY (a dozen of KiBs or so)
  - relatively simple: no need for advanced text editing features, just enough
    to comfortably edit small (<64K) configuration files
  - 8086-compatible and have modest memory requirements
  - multi-lang (kitten library)
  - capable of (limited) copy/pasting between two files
 
* validate that CORE is 100%% 8086-compatible
 
* Networking setup at install time -> should crynwr be part of the install
  set? Or only selected drivers? Or maybe this could be provided as a
  "supplemental" floppy disk?
 
* bootable USB install image
 
* make the COMMAND package smaller so there is no need for multiple
  lang-dependant copies of the binary
 
* improve installer so user can choose the target disk
 
* add a "link" tool so users can easily create "links" to their favorite
  programs (esp. things like zip/unzip, etc)
 
* install.com - MBR changes could be done by the installer itself instead of
  system()-calling fdisk
 
* help - write more useful content!
  -> basic DOS commands (directories, copy/rename/delete files, etc)
  -> common configuration files (autoexec, config.sys, pkg.cfg, wattcp.cfg..)
  -> networking guide
  -> memory management basics
  -> ...
 
* test new versions of software and update packages accordingly. special care
  must be taken for core things: kernel, freecom, fdisk, himemx...
 
* further NLS support, improvements of existing translations and adding new
  languages -> would be nice to have some kind of web interface for submitting
  and reviewing translations
 
* pkgnet.exe: implement the 'checkup' action for easy update checks
 
* possibly plenty of other things
 
 
                        =============================
                          %hWanna help? %lcontact.ama:Get in touch!
                        =============================
 
        %h*** Why would I want to use SvarDOS instead of FreeDOS? ***
 
The FreeDOS project is a free, open-source operating system that aims to be
100%% compatible with MS-DOS. And it is awesome. So why would I want to use
SvarDOS instead?
 
%hLong release cycles
 
The FreeDOS project began 29 June 1994. Version 1.0 came around in 2006.
Version 1.1 has been released in 2012, and the version 1.2 followed in
December 2016. This translates roughly to a 5-years release cycle. Granted,
the DOS scene is not as active as it used to be, but still, many things happen
during a few years. Such version-centric approach also requires users to
perform full-system upgrades every now and then.
 
SvarDOS is very different in this regard: there are no versions at all.
Whenever a new program is included into or updated within the distribution, it
becomes immediately available through the SvarDOS reposoitory and may be
pulled either through the SvarDOS website or SvarDOS' pkgnet tool. Already
installed systems can be easily kept up-to-date using the distribution's
package manager.
 
%hConstraints of legal nature
 
The FreeDOS project mimicks a proprietary operating system, with all its APIs
and peculiarities. For this reason, the project always had to be extremely
careful about what can and what cannot be included within the FreeDOS
distribution. As a result, only "free software" (as in freedom, think GPL,
BSD, and so on) can make its way into the official distribution. While such
cautious approach is sane and legally safe, it is far from practical for
users. Allowing exclusively free software means that a high number of useful
programs, tools and games are left behind. For example "freeware" tools (as in
"gratis but no source included") are a no-go. Even open-source programs can be
rejected, if they do not clearly state that they comply with an OSI-approved
license.
 
SvarDOS, on the other hand, is much more liberal about including packages.
Basically, anything that is objectively useful, of reasonable quality,
free/gratis and can be legally distributed in the form of a package, can be
included in SvarDOS. The only exception is for the "core" system (ie. the
operating system itself), which must be based exclusively on free/libre
software. Read more about %lpkgrules.ama:SvarDOS package inclusion rules%t.
 
%hFreeDOS included!
 
It must be noted, that altough the goals of SvarDOS and FreeDOS may be
slightly different, SvarDOS wouldn't exist without FreeDOS. Indeed, SvarDOS
uses the excellent FreeDOS kernel, as well as a few other utilities borrowed
from the FreeDOS ecosystem.
 
Read also: %lhistory.ama:SvarDOS history
 
%hSvarDOS origins (history from the point of view of its creator)
 
Mateusz Viste says:
 
In the years 2005-2015 I used to perform packaging work for the FreeDOS
project. I wasn't pleased with the packaging tool that FreeDOS used back then
(FDPKG), so in 2012 I started working on a new package manager, with network
support, automatic updates, etc - I named it FDNPKG. Later I also devised a
scripted way of generating an "always up to date" FreeDOS CD that I
unimaginatively called "all_cd.iso". This CD included FDNPKG and all the
FreeDOS packages available at the given moment.
 
I still wasn't satisfied with how FreeDOS clings to its notion of "releases"
and that it cannot include some software because of licensing issues, so in
2016 I decided to create my own distribution, that I called Svarog386 (there
was also a Svarog86 project that I had created a couple months earlier,
dedicated to 8086 machines). Svarog386 naturally relied on the FreeDOS kernel
and used the FDNPKG package manager.
 
Then, in 2021, I found it increasingly annoying to look after two separate
distributions. Over time, FDNPKG also became a huge piece of protected mode
code, and although it was magnificent code, I was no longer happy with it: too
many features, too much data processing, too much memory required... In a
word: too much fluff. I longed for something simpler, that would do perhaps
less, but with more transparency towards the user - and something that would
work in real mode with not much RAM, so it could run even on ancient 8086
machines.
 
The result of these thoughts was SvarDOS: a distribution that replaced both
Svarog86 and Svarog386, and that came with its own package manager - a much
simpler (and in my opinion much more elegant) tool than FDNPKG.
SVARDOS HELP SYSTEM ver 20210403
 
Subversion Repositories SvarDOS

(root)/website/help/help-en.amb – Rev 306 → 318
