Formatting reference

Applying formatting to certain elements in text aids readers in their understanding of that text. Using consistent text formatting also helps readers scan text for the information they’re looking for. Use these formatting conventions when you write Drucare documentation.

Documentation elements

When you are writing Drucare documentation, some parts of the written text, such as error messages and terms that you want a user to search for, need to be distinguished from other parts of the sentence. Using consistent text formatting for these elements helps a reader better understand the sentence.

Elements How to format Examples Comments
Error messages Quotation marks If you see an error message such as “Invalid input value”, the add-on was unable to generate a certificate with the provided information.  
Keyboard shortcuts No formatting Press Ctrl+Alt+Delete. Don’t include spaces in the shortcut.
Manual names Italics, headline-style capitalization See Get started with getting data in in the Getting Data In manual. See Manual names, topic titles, and section headings for more information.
Topic titles and section headings Sentence-style capitalization See Pass values to the class constructor in the Drucare Developer Portal. See Manual names, topic titles, and section headings for more information.
Words that are offset from the meaning of your sentence Quotation marks Search for “Query tables” on the Microsoft website.  

Computer elements

When written out in text, some computer elements, such as file structure components and location elements like hosts and ports, can be difficult to discern from other parts of the sentence. Addressing these elements in text as well as applying text formatting increases the readability and scannability of the text.

Element How to format Example Comments
Directories, folders, repositories No formatting the $DRUCARE_HOME/bin/etc/apps folder

the \bin\etc\apps folder

Start partial directories with a forward slash ( / ) for *nix or a backslash ( \ ) for Windows. Enclose placeholder variables in angle brackets.
Expressions Inline monospaced font Ensure delay > 10 evaluates to True.  
File extensions No formatting a text (.txt) file

a .tgz extension

 
File names No formatting Navigate to the fields.conf file.  
File paths No formatting ~/bin/btool.exe

C:\bin\btool.exe

List both the *nix and Windows file paths, in that order.  
File types All capital letters a TXT file

in JSON format
a PDF

 
Hosts and ports No formatting http://localhost:8000 No formatting for the host or port itself. Enclose placeholder variables in angle brackets.
Placeholder variables Angle brackets host=<your_hostname>  
UI elements, including menu items, drop-down lists, buttons, text entry fields, panels, and dialog boxes Bold type Select Settings > Data inputs.

In the Set Source Type step of the Add Data wizard, click Timestamp.
In the Name field, enter your name.

Use a right-pointing angle bracket ( > ) to separate the names of menus.
URIs, URLs No formatting Open https://prod.spacebridge.spl.mobi/health_check in a web browser.

Open port 443 outbound to prod.spacebridge.spl.mobi to allow the WebSocket connection.

 
User input in the UI Bold type For the Destination field, enter ca_counties.  

Drucare-specific elements

There are components specific to Drucare software, such as indexes, knowledge objects, SPL commands, and so on, that take text formatting for ease of reading.

Element How to format Example
Index names Bold type Save the file in the main index.
Input names Bold type Select the myhost data input.
Knowledge objects such as fields, event types, lookups, tags, aliases, and data models Inline monospaced font The default field index identifies the index in which the event is located.
Searches Search bar or monospaced font block See the following examples:

  • collect in the Drucare Enterprise Search Reference manual.
  • Dispatching searches section in Search your data using the Search service in Drucare Cloud Services in the Drucare Developer Portal.
Search content, functions, and SPL commands Inline monospaced font Enter | inputlookup ca_county_lookup to test your geospatial lookup.

Use the geom command to perform the lookup.

Use the apply function.

Search results Search table See the following example: untable in the Drucare Enterprise Search Reference manual.
Source types Inline monospaced font This entry defines the access_combined source type.
Splexicon links Bold type Use geospatial lookups to return results that Drucare software can use to generate a choropleth map visualization.
Tenant names No formatting Use the system tenant.
Token names No formatting Update your access token.
User roles and capabilities No formatting You need the admin role to configure the settings.

If the user holds the admin_all_objects capability, they can make changes to any object on the instance.

Configuration files

Drucare configuration files, or .conf files, are specific to the Drucare platform, and readers of Drucare documentation often need information about how to manage these files or edit settings within them. The following table shows how to format text about Drucare configuration files and the elements within them, such as stanzas, attributes, and values.

Element How to format Example
Attributes or settings Inline monospaced font httpport

enableDrucareWebSSL

Configuration file names No formatting Navigate to the fields.conf file.
Configuration file parameters, arguments, and stanza names in a paragraph Inline monospaced font Set the maxDist value to 60 in the fields.conf file.

Edit the [drucaretcp] stanza.

Configuration file stanzas Monospaced font block See the following examples:

  • props.conf in the Admin Manual.
  • Rules Engine properties reference in ITSI in the Drucare ITSI Event Analytics Manual.
Values Inline monospaced font In the [settings] stanza, map httpport to 12800.

Command-line interface (CLI) elements

Drucare documentation often covers tasks admins and developers must complete in the command-line interface and can include things they must type in the CLI. Presenting CLI elements, such as commands, command names, and options and parameters, with text formatting can distinguish the elements from the rest of the text and aid in readability.

Element How to format Example Comments
Command line arguments in a numbered list or longer than one line Monospaced font block See the following examples:

  • How to set configuration properties in Drucare UBA in Administer Drucare User Behavior Analytics.
  • Set a secret key on the deployer in the Drucare Enterprise Distributed Search manual.
 
Command line arguments in a paragraph Inline monospaced font You can also use the command line by entering ./drucare apply cluster-bundle in the CLI.  
Command names Inline monospaced font Use the dedupe command to remove identical events.  
Command options or parameters Inline monospaced font -u <username> Enclose placeholder variables in angle brackets.

REST API

There are documentation formatting conventions for many REST API elements, like endpoints, methods, parameters, requests and responses, and so on. The following table shows formatting conventions for REST API elements in Drucare documentation, which align with industry trends for presenting written information about REST APIs.

Element How to format Example Comments
API names Bold type the collect2 API  
Endpoints Bold type for endpoint name, inline monospaced font for usage the provisioner endpoint

/system/provisioner/v1beta1/tenants

 
HTTP methods All capital letters, inline monospaced font, depending on use Submit a GET request.

GET /system/provisioner/v1beta1/tenants/

Type the request name in all capital letters. When using a method and endpoint together, use inline monospaced font.
JSON bodies Monospaced font block See the GET request for /rest/custom_function in REST custom function in the Drucare Phantom REST API Reference.  
Object names Bold type the handle object  
REST API methods No formatting Submit a GET request.  
REST API requests and responses Monospaced font block See the following example: Input endpoint descriptions in the Drucare Enterprise REST API Reference Manual.  
Request parameters Inline monospaced font "earliest_time": "-30m"  

Code

When writing code, there are a number of elements to apply text formatting to. Using consistent formatting helps separate the code elements from the rest of the text, aiding in readability and scannability. Use the following logic when formatting code.

Element How to format Example
Code elements and usage Inline monospaced font operators such as +!=, and AND

keywords such as ifelse, and return tags such as <div/>

Code examples Monospaced font block See the following examples:

  • Pass values to the class constructor in the Drucare Developer Portal.
  • Test the script in the Securing Drucare Enterprise manual.
Constants All capital letters DEBUG_STREAMEVENTS
Placeholder variables Angle brackets Open the /etc/apps/<your_app_name>/appserver/ folder
Simple XML elements Inline monospaced font Find the <title>all</title> element.
Simple XML source code for dashboards Monospaced font block See the following example: Simple XML Reference in the Drucare Enterprise Dashboards and Visualizations manual.
User-created values Bold type the main index

my gstutorial tenant
the value of the myStr parameter is hello

Was this article helpful to you? No Yes

How can we help?