Skip to content
CEagle

Writing a listing

The title, summary, description, author, categories and tags a program shows on Roost — written once, reused by every version.

The listing is what a program looks like on Roost. It belongs to the project, not to a release, so publishing a new version needs only a file and a version number.

Where it lives depends on the source:

Repository projects

In the manifest, under the program table. It is read from the commit being built, so a listing change is a commit.

Read on
TI-BASIC projects

In the console, or over the listing endpoint. There is no repository to read it from.

Read on

The fields#

Listing
title1 to 64 charactersRequired

The program name on Roost. Not the calculator variable name.

summaryat most 140 characters

One line. This is what appears in listings, search results and the command palette, so it is doing more work than the description.

descriptionat most 4000 characters

The long text on the program page. Longer input is truncated rather than rejected.

authorat most 64 charactersdefaults to the project owner

Who to credit. Useful when the program has several authors, or when the account name is not the name you publish under.

categories1 to 4 keysRequired

From the live catalog. An unknown key is an error.

tagsup to 12, 32 characters each

Free-form. Normalised, so casing and stray whitespace do not create duplicates.

hiddenbooleandefaults to false

Downloadable at its address, but left out of listings, search and category counts.

Categories#

Fetch the catalog rather than guessing:

curl -s https://roost.ceagle.cc/api/v1/categories
{
  "categories": [
    { "key": "games", "name": "Games", "description": "…", "restricted": false, "count": 42 },
    { "key": "libs", "name": "Libraries", "description": "…", "restricted": false, "count": 9 }
  ],
  "languages": [{ "key": "asm", "name": "ASM/C" }],
  "sorts": ["newest", "oldest", "downloads", "title", "size", "updated"],
  "total": 118
}

Some categories are marked restricted. Only administrators may publish into them, and a manifest that claims one from an ordinary account fails the build rather than silently dropping it.

Writing a good summary#

The summary is the only text most people read. It appears next to the title everywhere.

Do

Say what it is and what makes it different. "Roots, discriminant and vertex, shown step by step."

Do not

Repeat the title, or describe the implementation. "A program for the TI-84 Plus CE written in C."

Hidden programs#

A hidden program is not private. It is downloadable by anyone who knows its address, and its dependency entries still resolve; it is simply left out of every list.

Use it for a library nobody should install directly, a program in a soft launch, or something you publish only to depend on it from elsewhere.

Changing a listing after publishing#

Yes, and it takes effect immediately for the whole program, including versions published before the change. There is no per-version listing.

For a repository project, edit the manifest and push. The change lands with the next successful build, because the listing is read from the commit that was built.

Carried listings#

A TI-BASIC project that was published before its listing was written picks the listing up from the published program the first time the console reads it. That is a backfill, so it happens once and then the listing is the project's own.

CEagle documentation