doc: sample-repo: replace json files with plaintext

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

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

doc/sample-repo/channel/vanilla/universe/index

@@ -0,0 +1,2 @@
+Name: Universe
+Description: Officially-supported open-source packages.

doc/sample-repo/index

@@ -0,0 +1,6 @@
+Name: Sample Repository
+Description: Official Sample Repository
+System: sample
+Architectures: amd64 any
+Components: universe multiverse
+Channels: vanilla

doc/sample-repo/index.json

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

doc/sample-repo/news

@@ -38,18 +38,39 @@ Category: General
 2 News File Format
 ==================
 
-   News items have a specific plain-text format, which can be seen in this file.
+   The news file has 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
+   2.1 General Layout
-   ---------------------
+   ------------------
 
-   These headers include:
+   The news file contains one or more news items. Each news item begins with
+   a header section describing the news item, followed by a content section
+   containing the actual news content. At the end of the last news item is an
+   optional footer section.
+
+
+   2.1 Header
+   ----------
+
+   Each news item begins with a standardised header section describing it. A
+   range of header items are supported.
+
+   These 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.
+      the user last checked the news. This is always in UTC, and is formatted
+      as: YYYY-MM-DD HH:NN:SS
+      where:
+      *  YYYY is the current year.
+      *  MM is the current month number, with a leading 0 if less than 10.
+      *  DD is the current day of the month, with a leading 0 if less than 10.
+      *  HH is the current hour of the day, between 0-24, with a leading 0 if
+         less than 10.
+      *  NN is the current minute of the hour, between 0-59, with a leading 0 if
+         less than 10.
+      *  SS is the current second of the minute, between 0-59, with a leading 0
+         if less than 10.
 
    -  Title: The title of the news item.
 
@@ -84,8 +105,8 @@ Category: General
    2.2 Content
    -----------
 
-   Between the header and footer is the actual news content that is shown to the
+   Following the header is the actual news content that is shown to the user.
-   user. This section can be formatted in any way you prefer; any plaintext is
+   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
@@ -101,10 +122,30 @@ Category: General
    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
+   The end of the news content is marked by two line feed characters, followed
-   like vim, you can store these directives in the page footer so that they
+   by five asterisk characters. If this is the last news item in the file, no
-   aren't shown to the user.
+   end marker is required; the end of the file implicitly marks the end of the
+   final news item.
 
-*****
+
+   2.3 Footer
+   ----------
+
+   The footer is an optional part of the news file, located at the very end. It
+   can be used for data that shouldn't be shown to the user. For example, if you
+   use vim to write your news files, you can include vim in-line formatting
+   directives in the footer to make writing the news file easier, without them
+   being visible to the user.
+
+   Of course, it is up to the program displaying the news item to respect these
+   visibility rules, so while the data in the footer is (ideall) not visible, it
+   is still always public.
+
+   To add a footer to your news file, use a footer marker at the end of the last
+   news item in the file. The footer marker is the same as the content end
+   marker (two linefeeds, followed by five asterisks), but with an additional
+   exclamation mark immediately following the fifth asterisk.
+
+*****!
 
 vim: shiftwidth=3 expandtab