Text Formatting

This page describes how to format specific types of text in documentation, source code, and UIs.

Common text elements

The following table describes the convention for common text elements, like those referred to in documentation and marketing materials.

Element	Convention	Example
Commands	Use bold formatting for command names. Use sentence-style capitalization unless you need to match the UI.	Go to Tools, and select Change language. On the Design menu, select Colors, and then select a color scheme.
Emphasis	Italic, but use sparingly.	To use ScalarDB Cluster, you must have a valid license.
File name extensions	All lowercase.	.java, .mdx
File names	Source code: Internal title-style capitalization. Documentation: All lowercase, with hyphens instead of spaces (chain case).	Source code: TableMetadataManager.java Documentation: getting-started-with-scalardb.mdx
Folder and directory names	All lowercase, with hyphens instead of spaces (chain case).	integration-test helm-charts/getting-started-scalardl-ledger.mdx
New terms	Use quotation marks on the first mention of a new term that is being defined.	The chain structure that exists between multiple assets and is a constructed by business or application logic is referred to as a "contract" in ScalarDL.
Products, features, and services	Usually title-style capitalization.	ScalarDB Core ScalarDB Analytics ScalarDL Ledger Scalar Manager Consensus Commit
URLs	All lowercase. If you need to separate a URL onto another line, add a line-break before a slash.	www.scalar-labs.com scalardb.scalar-labs.com/docs

Developer text elements

The following table describes the convention for various developer text elements, like those found in source code.

Element	Convention	Example
Attributes	Enclose in backticks (`). Capitalization varies.	`SUPERUSER`
Classes	Enclose in backticks (`). Capitalization varies.	`StateUpdater`
Command-line commands	Enclose in backticks (`). All lowercase.	`copy`
Command-line options	Enclose in backticks (`). Capitalization should match exactly how the option must be typed.	`-r` `-g, --use-gateway`
Data types	Enclose in backticks (`). Capitalization follows that of the API.	`VARCHAR` `INT` `float`
Database names	Enclose in backticks (`). Capitalization varies.	`Test1` database
Environment variables	Enclose in backticks (`). All uppercase.	`${env:SCALAR_DB_USERNAME}`
Error messages	Sentence-style capitalization enclosed in quotation marks.	"The index key is not properly specified." "The format of the contract ID is invalid."
Event names	Enclose in backticks (`). Treatment of event names varies.	In the `OnClick` event procedure, ....
Fields (members of a class or structure)	Enclose in backticks (`). Treatment of field names varies.	`isActive` `biPlanes`
File attributes	Enclose in backticks (`). All lowercase.	The `attrib` command displays, sets, or removes attributes assigned to files or directories.
Functions	Enclose in backticks (`). Capitalization varies.	`CompactDatabase` `CWnd::CreateEx` `FadePic`
Logical operators	Enclose in backticks (`). All uppercase.	`AND` `XOR`
Markup language elements	Enclose in backticks (`). Capitalization varies.	`<img>` `<input type=text>` `<!DOCTYPE html>`
Mathematical constants and variables	Italic.	N>f
Operators	Enclose in backticks (`).	`+` `-` `type`
Parameters	Enclose in backticks (`). Often all lowercase, with underscores instead of spaces.	`default_transaction_mode` `run_for_sec`
Placeholders	Enclose in backticks (`) and angle brackets (<>). All uppercase.	`java -jar scalardb-schema-loader-<VERSION>.jar` `SCALAR_DB_CLUSTER_LICENSE_KEY='<YOUR_LICENSE_KEY>'`
Ports	All uppercase.	LPT1 USB
Properties	Enclose in backticks (`). Often all uppercase.	`scalar.db.transaction_manager` `scalar.dl.ledger.nonce_txid.enabled` `grafana.kubernetesServiceLabelName`
Statements	Enclose in backticks (`). Often all uppercase.	`CREATE TABLE` `DROP VIEW`
Structures	Enclose in backticks (`). Often all uppercase.	`AUTO_INCREMENT` `NOT NULL`
Values	Enclose in backticks (`). Often all lowercase.	`ledger.replicaCount` `auditor.image.repository`
Variables	Enclose in backticks (`). Often all uppercase.	`true` `4.8.0`

UI text elements

The following table describes the convention for various UI text elements, like those found in buttons and text fields.

Element	Convention	Example
Buttons, checkboxes, menus, and other options	Use sentence-style capitalization when naming UI elements. If the label for an option ends with a colon, don't include that ending punctuation in instructions. Avoid including the type of UI element, such as button or checkbox, unless you need to do so for clarity.	In the language dropdown menu, select Japanese. Select the GitHub icon at the top of the page. Clear the Apply filters checkbox.
Dialog boxes	Avoid talking about dialog boxes. Instead, describe what the user needs to do. If you need to refer to the UI element, use dialog. Use sentence-style capitalization unless you need to match the wording in the UI.	When prompted, select Upload, and then choose a file to upload. In the Software update dialog, choose whether you want to update now or after restarting the application.
Error messages	Sentence-style capitalization. Enclose error messages in quotation marks when referring to them in text.	"The index key is not properly specified." If you see the error message "The format of the contract ID is invalid," check the format of the contract ID.
Key names, combinations, and sequences	Capitalize. Use bold formatting for key names and keyboard shortcuts in instructions. Don't put a space around the plus sign (+) in keyboard shortcuts.	Tab, F10 Command+Shift+R Spacebar Press the Insert key. To switch languages, press Shift+Tab.
Menus	Avoid talking about menus. Instead, describe what the user needs to do. Use bold formatting for menu names.	Go to Languages, and select Japanese. On the File menu, select New Window Profile, and then select New Profile.
Strings	Enclose in backticks (`). Sentence-style capitalization unless text is capitalized differently.	In database.properties, find `scalar.db.transaction_manager=consensus-commit`.
Tabs	Use bold formatting for tab names. However, be sure to describe what the user needs to do.	In the "Upgrade versions" section of the Upgrade document, select Upgrade to a minor version, and then select ScalarDL Ledger. Go to the Deploy tab.
Toggles	Use bold formatting for toggle names. However, be sure to describe what the user needs to do.	To make documentation easier to read in low-light situations, you can change the theme to dark mode by selecting the sun icon.
User input	Use bold formatting. Usually lowercase unless case sensitive.	Type hello scalar. Enter -p <PASSWORD>.
Window	Use sentence-style capitalization unless you need to match the UI. However, be sure to describe what the user needs to do.	Open a new browser window.

Common text elements​

Developer text elements​

UI text elements​

Common text elements

Developer text elements

UI text elements