doc: add lots of sample files

doc/sample-package/control/post-install.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/control/post-uninstall.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/control/pre-install.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/control/pre-uninstall.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+echo "Hello, world!"

doc/sample-package/make-package.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+payload_name=payload.tar.zst
+control_name=control.tar.zst
+news_name=news.tar.zst
+manifest_name=manifest.json.zst
+
+payload_dest=$TMPDIR/$payload_name
+control_dest=$TMPDIR/$control_name
+news_dest=$TMPDIR/$news_name
+manifest_dest=$TMPDIR/$manifest_name
+
+pkg_dest=sample-package_0.1_amd64.ropkg
+
+rm -rf $manifest_dest
+
+tar cf $payload_dest --zstd -C payload .
+tar cf $control_dest --zstd -C control .
+tar cf $news_dest --zstd -C news .
+zstd manifest.json -o $manifest_dest
+
+tar cf $pkg_dest -C $TMPDIR $payload_name $control_name $news_name $manifest_name

doc/sample-package/manifest

@@ -0,0 +1,17 @@
+Name: sample-package
+Architecture: amd64
+Version: 1.2.5-2
+Priority: optional
+Category: misc
+Maintainer: John Doe <john@sample.com>
+Provides: sample-api (= 1.2.5)
+Depends: libc (>= 2.0), libstdc++ (>= 2.3), libs1 (>= 1.0) | libs2 (>= 1.2)
+Recommends: sample-cli
+Suggests: sample-gtk | sample-qt, sample-server
+Conflicts: example-package
+Enhances: basic-package
+Description: A sample package
+Installed-Size: 3245
+
+This is a sample package that demonstrates the structure of a Rosetta package,
+as well as the layout of the associated manifest and news files.

doc/sample-package/news/20250707.01.news

@@ -0,0 +1,110 @@
+PublishDate: 2025-07-07 09:00:00
+Importance: Normal
+Title: Welcome to the Rosetta Package Manager
+Category: General
+
++------------------------------------------------------------------------------+
+|                   Welcome to the Rosetta Package Manager!                    |
++------------------------------------------------------------------------------+
+
+   This is a sample news item to introduce you to the Rosetta package manager.
+   These news items can be used to provide information and updates to those who
+   use your repository.
+
+
+1 News File Location
+====================
+
+   News items come from four different sources:
+   -  Repository-wide news items, located in /news
+
+   -  Channel-related news items, located in /channel/<channel-id>/news
+
+   -  Component-related news items, located in
+      /channel/<channel-id>/component/<component-id>/news
+
+   -  Package-related news items, included in individual package files.
+
+   Specific news items can be published in different locations depending on who
+   the news is relevant for. For example, if there is some critical issue that
+   affects all users of a repository, /news would be the perfect place to use.
+   If, instead, the issue only affects users of a particular channel (maybe
+   you have a channel for each release of your operating system),
+   /channel/<channel-id>/news would be more appropriate. It's important that
+   news is targeted to the appropriate audience so that users don't have to sift
+   through news that isn't relevant to them.
+
+
+2 News File Format
+==================
+
+   News items have a specific plain-text format, which can be seen in this file.
+   The file begins with a set of headers that describe certain attributes of the
+   news, followed by the news content and an optional footer.
+
+
+   2.1 Header And Footer
+   ---------------------
+
+   These headers include:
+   -  PublishDate: The date and time on which the news item was published. This
+      is used by clients to determine which news items have been released since
+      the user last checked the news. This is always in UTC.
+
+   -  Title: The title of the news item.
+
+   -  Category: The particular category that the news item is relevant to.
+      Possible values include:
+      *  General
+      *  Security
+
+   -  Importance: How important it is that the user reads this news.
+      Possible values include:
+      *  Low
+      *  Normal
+      *  High
+      *  Critical
+      The user has to go out of their way to read Low and Normal news items, while
+      High and Critical news items will be shown automatically when the user next
+      interacts with the relevant part of the repo.
+
+   Immediately following these headers are two line-feed characters. This
+   denotes the end of the header and the start of the content of the news files.
+   With two line feeds, there should be exactly one blank line visible between
+   the last header line and the first content line.
+
+   At the end of the file is a line with 5 asterisk (*) characters. This denotes
+   the end of the of the news file's content and the start of the footer. Beyond
+   this point, you can put extra data, such as the vim formatting commands
+   visible in this file, that you don't want shown to the user. If no footer is
+   required, the 5-asterisk marker can be omitted, and the news content will
+   simply end where the file ends.
+
+
+   2.2 Content
+   -----------
+
+   Between the header and footer is the actual news content that is shown to the
+   user. This section can be formatted in any way you prefer; any plaintext is
+   acceptable. This news file has been formated in a particular way to provide
+   example formatting that you may wish to use. It features a page header,
+   section and sub-section headings, and list formatting. All paragraphs
+   are indented with three spaces. The gap between a list item marker
+   and list item text is two spaces, with any following lines in that particular
+   list item indented with three spaces. There is one blank line between each
+   paragraph, and two blank lines between the last line in one section and
+   the heading of the next.
+
+   The only formatting rule that should be adhered to is that, like code, lines
+   should be kept to no longer than 80 characters. This is due to the fact that
+   the vast majority of users will be viewing news items within their terminal
+   as they are using the ropkg commands, and 80 cells is the standard width for
+   terminal displays.
+
+   Don't forget that, if your text editor supports in-line formatting directives
+   like vim, you can store these directives in the page footer so that they
+   aren't shown to the user.
+
+*****
+
+vim: shiftwidth=3 expandtab