diff --git a/doc/sample-repo/channel/vanilla/component/universe/index.json b/doc/sample-repo/channel/vanilla/component/universe/index.json deleted file mode 100644 index 23eab41..0000000 --- a/doc/sample-repo/channel/vanilla/component/universe/index.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "name": "Universe", - "description": "Officially-supported open-source packages." -} diff --git a/doc/sample-repo/channel/vanilla/index.json b/doc/sample-repo/channel/vanilla/index.json deleted file mode 100644 index e69de29..0000000 diff --git a/doc/sample-repo/channel/vanilla/universe/index b/doc/sample-repo/channel/vanilla/universe/index new file mode 100644 index 0000000..33a231f --- /dev/null +++ b/doc/sample-repo/channel/vanilla/universe/index @@ -0,0 +1,2 @@ +Name: Universe +Description: Officially-supported open-source packages. diff --git a/doc/sample-repo/channel/vanilla/component/universe/packages.json b/doc/sample-repo/channel/vanilla/universe/packages similarity index 100% rename from doc/sample-repo/channel/vanilla/component/universe/packages.json rename to doc/sample-repo/channel/vanilla/universe/packages diff --git a/doc/sample-repo/channel/vanilla/component/universe/release.zst b/doc/sample-repo/channel/vanilla/universe/packages-amd64.zst similarity index 100% rename from doc/sample-repo/channel/vanilla/component/universe/release.zst rename to doc/sample-repo/channel/vanilla/universe/packages-amd64.zst diff --git a/doc/sample-repo/index b/doc/sample-repo/index new file mode 100644 index 0000000..c9553af --- /dev/null +++ b/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 diff --git a/doc/sample-repo/index.json b/doc/sample-repo/index.json deleted file mode 100644 index 4274322..0000000 --- a/doc/sample-repo/index.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "name": "Sample Repository", - "description": "Official Sample Repository", - "system": "sample", - "arch": [ "amd64" ], - "channel": [ "vanilla" ], - "newsItems": [ "20250707.01" ] -} diff --git a/doc/sample-repo/news/20250707.01.news b/doc/sample-repo/news similarity index 61% rename from doc/sample-repo/news/20250707.01.news rename to doc/sample-repo/news index 0bea577..3d2b123 100644 --- a/doc/sample-repo/news/20250707.01.news +++ b/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 file begins with a set of headers that describe certain attributes of the - news, followed by the news content and an optional footer. + The news file has a specific plain-text format, which can be seen in this file. - 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 - user. This section can be formatted in any way you prefer; any plaintext is + Following the header 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 @@ -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 - like vim, you can store these directives in the page footer so that they - aren't shown to the user. + The end of the news content is marked by two line feed characters, followed + by five asterisk characters. If this is the last news item in the file, no + 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