List and table presentation ideas

degville · October 16, 2018, 12:29pm

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

Programming languages

Go

Plugin name	Description	core20	core/core18
go	integrates projects written in Go and using the go get package installer
godeps	integrates projects written in Go and using the godep dependency tool

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

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

…

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

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`

Diff output

    environment:
-        PERL5LIB:  "$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl-base/:$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl5/5.22/:$SNAP/usr/share/perl5/:$SNAP/usr/share/perl/5.22.1/:$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl/5.22/:$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl/5.22.1/"
+        PERL5LIB:  "$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl-base/:$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl5/5.26/:$SNAP/usr/share/perl5/:$SNAP/usr/share/perl/5.26.1/:$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl/5.26/:$SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/perl/5.26.1/"