List and table presentation ideas


#1

In our snap docs, we have have several long and potentially difficult to parse lists and tables.

The Supported interfaces page contains a good example.

This post experiments with their presentation to see if there’s a better and more comfortable way to approach these large chunks of data.

The rendered HTML output for this page can be found here.

ⓘ We could also use HTML definition/description lists, but we’re reluctant to use inline HTML in our Markdown.

Table

Interface name Description Auto-connect
account-control add/remove user accounts or change passwords no
accounts-service allows communication with the accounts service no
alsa play or record sound no
autopilot-introspection be controlled by Autopilot software no

URL tests

In docs category, not on sitemap:
/t/base-snaps/11198

/t/11198

Outside docs category:

/t/hotplug-implementation-plan/4554

/t/4554

Manual style

accounts-service
allows communication with the accounts service

alsa
play or record sound

autopilot-introspection
be controlled by Autopilot software

account-control
     add/remove user accounts or change passwords

accounts-service
     allows communication with the accounts service

alsa
     play or record sound

autopilot-introspection
     be controlled by Autopilot software

Another manual style

account-control

Type: string

Add/remove user accounts or change passwords.

accounts-service

Allows communication with the accounts service.

alsa

Play or record sound.

autopilot-introspection

Be controlled by Autopilot software.

List styles

Block quotes

account-control
add/remove user accounts or change passwords

accounts-service
allows communication with the accounts service

alsa
play or record sound

autopilot-introspection
be controlled by Autopilot software

Snapcraft.yaml reference

Original

Name Type Description Example Values
name
(mandatory)
string The name of the snap
Restrictions: Max len 40, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter.
my-awesome-app
version
(mandatory)
string A user facing version to display
NOTE: Needs to be wrapped with single-quotes when the value will be intepreted by the YAML parser as non-string
Restrictions: Max len. 32 chars
'1'
'1.2'
1.2.3
git (will be replaced by a git describe based version string)
version-script string A command with working directory of the source tree root that determines and prints the snap’s version string to the standard output.
This replaces the value of the version keyword, however the version keyword is still mandatory (but ignored).
cat version.txt
./snap/local/utilities/set-version.bash
summary
(mandatory)
string A 78 character limited sentence that summarizes the snap The super cat generator
description
(mandatory)
string A multiline description of the snap (use your imagination)

Two rows

Name: name (mandatory) Type: string Description: The name of the snap
Restrictions: Max len 40, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter

With HTML (colspan):

Name Type Description Example values
name
(mandatory)
string The name of the snap
Restrictions: Max len 40, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter.
my-awesome-app

Two columns

Name / type Description
name
string
(mandatory)
The name of the snap.
Restrictions: Max len. 30 chars, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter.
Example values: my-awesome-app
version
string
(mandatory)
A user facing version to display
Restrictions: Max len. 32 chars. Needs to be wrapped with single-quotes when the value will be interpreted by the YAML parser as non-string
Example values: '1', '1.2', '1.2.3', git (will be replaced by a git describe based version string)
version-script
string
A command within the working directory of the source tree root that determines and prints the snap’s version string to the standard output. This replaces the value of the version keyword, however the version keyword remains mandatory but ignored.
Example values: cat version.txt and ./snap/local/utilities/set-version.bash

Three columns

Name Type Description
name mandatory string The name of the snap.
Restrictions: Max len. 30 chars, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter.
Example values: my-awesome-app
version mandatory string A user facing version to display
Restrictions: Max len. 32 chars. Needs to be wrapped with single-quotes when the value will be interpreted by the YAML parser as non-string
Example values: '1', '1.2', '1.2.3', git (will be replaced by a git describe based version string)
version-script mandatory string A command within the working directory of the source tree root that determines and prints the snap’s version string to the standard output. This replaces the value of the version keyword, however the version keyword remains mandatory but ignored.
Example values: cat version.txt and ./snap/local/utilities/set-version.bash

Row style

Name Description
name
mandatory
The name of the snap
Type: string
Max len. 30 chars, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter.
Example: my-awesome-app
 
version
mandatory
A user facing version to display
Type: string
Max len. 32 chars. Needs to be wrapped with single-quotes when the value will be interpreted by the YAML parser as non-string
Examples: '1', '1.2', '1.2.3', git (will be replaced by a git describe based version string)

Padded

Name / type Description
name
string
mandatory
 
 
The name of the snap. Max len. 30 chars, must start with an ASCII character, can only use ASCII lowercase letters, numbers, and hyphens, and must have at least one letter.
Example: my-awesome-app
version
string
mandatory
 
 
 
A user facing version to display. Max len. 32 chars. Needs to be wrapped with single-quotes when the value will be interpreted by the YAML parser as non-string
Examples: '1', '1.2', '1.2.3', git (replaced by a git describe based version string)
version-script
string
optional
 
 
 
 
A command or script within the root of the source tree that determines and prints a version string to the standard output. This replaces the value of the version keyword, however the version keyword is still mandatory (but ignored).
Examples: cat version.txt and ./snap/utilities/set-version.bash

Snapcraft top-level metadata