doc: add sample repository directory; repo layout documentation

doc/repo-format.txt

@@ -0,0 +1,10 @@
+Root directory contents:
+  - index.json: Describes the repository, including it's name, description, available channels, the system for which it provides packages, etc.
+  - news: Contains news items. The latest news will be shown to the user when they next refresh their package database.
+  - pool: Contains all the raw package files. If multiple channels provide the same package version/arch, both will point to the same package file within the pool.
+  - channel: The channels that this repository provides.
+
+
+/pool directory contents:
+  - One directory for each letter of the alphabet, plus an extra set of directories for each letter of the alphabet prefixed with 'lib'.
+    When a package is added to the repository, it is stored in one of these subdirectories. Which one depends on the first letter of the package name.

doc/sample-repo/channel/vanilla/component/universe/index.json

@@ -0,0 +1,4 @@
+{
+	"name": "Universe",
+	"description": "Officially-supported open-source packages."
+}

doc/sample-repo/index.json

@@ -0,0 +1,8 @@
+{
+	"name": "Sample Repository",
+	"description": "Official Sample Repository",
+	"system": "sample",
+	"arch": [ "amd64" ],
+	"channel": [ "vanilla" ],
+	"newsItems": [ "20250707.01" ]
+}

doc/sample-repo/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