diff --git a/app/3d-viewer/src/main/resources/3d_viewer_preferences.properties b/app/3d-viewer/src/main/resources/3d_viewer_preferences.properties index 459d19e892..8113bf87a1 100644 --- a/app/3d-viewer/src/main/resources/3d_viewer_preferences.properties +++ b/app/3d-viewer/src/main/resources/3d_viewer_preferences.properties @@ -9,9 +9,11 @@ read_timeout=10000 default_dir=$(user.home) # Cone is approximated with these many faces. -# 3: Triangular base, most minimalistic -# 8: Looks pretty good -# Higher: Approaches circular base, -# but adds CPU & memory usage -# and doesn't really look much better -cone_faces=8 \ No newline at end of file +# +# :3: Triangular base, most minimalistic +# :8: Looks pretty good +# :higher: +# Approaches circular base, +# but adds CPU & memory usage +# and doesn't really look much better +cone_faces=8 diff --git a/app/alarm/audio-annunciator/src/main/resources/audio_annunciator_preferences.properties b/app/alarm/audio-annunciator/src/main/resources/audio_annunciator_preferences.properties index c8383b2611..b2bf3df2e7 100644 --- a/app/alarm/audio-annunciator/src/main/resources/audio_annunciator_preferences.properties +++ b/app/alarm/audio-annunciator/src/main/resources/audio_annunciator_preferences.properties @@ -3,12 +3,20 @@ # ---------------------------------------- # The audio annunciator will play the audio files specified for the associated alarm severity levels. -# Currently supported formats are AIFF and WAV files. -# examples of audio file URL's, they can be local or remote files. +# +# Currently supported formats are AIFF and WAV files, +# which can be local or remote. +# +# ```{code-block} +# :caption: Examples +# # file:/C:/tmp/audio/AudioFileWithWavFormat.wav # https://wavlist.com/wav/brass1.wav +# ``` -# default alarm sound, if we don't want severity specific sounds only setting this one preference is enough +# Default alarm sound. +# +# If we don't want severity specific sounds only setting this one preference is enough. alarm_sound_url= minor_alarm_sound_url= @@ -16,8 +24,8 @@ major_alarm_sound_url= invalid_alarm_sound_url= undefined_alarm_sound_url= -# audio clip volume (0-100) +# Audio clip volume (0-100). volume=100 -# max alarm Duration in seconds. -max_alarm_duration=10 \ No newline at end of file +# Max alarm Duration in seconds. +max_alarm_duration=10 diff --git a/app/alarm/logging-ui/src/main/resources/alarm_logging_preferences.properties b/app/alarm/logging-ui/src/main/resources/alarm_logging_preferences.properties index 153c87f406..6920981ba0 100644 --- a/app/alarm/logging-ui/src/main/resources/alarm_logging_preferences.properties +++ b/app/alarm/logging-ui/src/main/resources/alarm_logging_preferences.properties @@ -2,7 +2,11 @@ # Package org.phoebus.applications.alarm.logging.ui # ------------------------------------------------- -# The URL of the REST API exposed by the alarm logger service (not the elasticsearch port as it was prior to Phoebus 4.0) +# The URL of the REST API exposed by the alarm logger service. +# +# :::{versionchanged} 4.0 +# Prior to the 4.0 release, this was the elasticsearch port. +# ::: service_uri = http://localhost:9000 results_max_size = 10000 diff --git a/app/alarm/model/src/main/resources/alarm_preferences.properties b/app/alarm/model/src/main/resources/alarm_preferences.properties index e6e8fa83e3..114a6d89dc 100644 --- a/app/alarm/model/src/main/resources/alarm_preferences.properties +++ b/app/alarm/model/src/main/resources/alarm_preferences.properties @@ -9,13 +9,16 @@ server=localhost:9092 kafka_properties= # Name of alarm tree root. +# # Configures the alarm configuration used by the alarm server. # For the UI, it sets the default alarm configuration. config_name=Accelerator # Names of selectable alarm configurations for UI. -# The `config_name` will be used as the default for newly opened tools, -# and if `config_names` is empty, it remains the only option. +# +# The {prefs:pref}`config_name` will be used as the default for newly opened tools, +# and if {prefs:pref}`config_names` is empty, it remains the only option. +# # When one or more comma-separated configurations are listed, # the UI shows the selected name and allows switching # between them. @@ -27,45 +30,59 @@ connection_timeout=30 # Timeout in seconds for "sevrpv:" updates severity_pv_timeout=5 -## Area Panel +# :::{rubric} Area Panel +# ::: # Item level for alarm area view: -# 1 - Root element -# 2 - Top-level "area" elements just below root -# 3 - Show all the items at level 3 +# +# :1: Root element +# :2: Top-level "area" elements just below root +# :3: Show all the items at level 3 alarm_area_level=2 -# Number of columns in the alarm area view +# Number of columns in the alarm area view. alarm_area_column_count=3 -# Gap between alarm area panel items +# Gap between alarm area panel items. alarm_area_gap=5 -# Font size for the alarm area view +# Font size for the alarm area view. alarm_area_font_size=15 # Limit for the number of context menu items. +# # Separately applied to the number of 'guidance', -# 'display' and 'command' menu entries. +# 'display' and 'command' menu entries. alarm_menu_max_items=10 -# Initial Alarm Tree UI update delay [ms] +# Initial Alarm Tree UI update delay, in milliseconds. # # The initial flurry of alarm tree updates can be slow # to render. By allowing the alarm client to accumulate # alarm tree information for a little time and then # performing an initial bulk representation, the overall # alarm tree startup can be faster, especially when -# the UI is viewed via a remote desktop +# the UI is viewed via a remote desktop. # -# Set to 0 for original implementation where +# Set to `0` for original implementation where # all alarm tree items are added to the model # as they are received in initial flurry of updates. alarm_tree_startup_ms=2000 -# Order of columns in alarm table +# Order of columns in alarm table. +# # Allows re-ordering as well as omitting columns -# The supported columns are: Icon, PV, Description, Alarm Severity, Alarm Message, Alarm Time, Alarm Value, PV Severity, PV Message +# +# The supported columns are: +# - `Icon` +# - `PV` +# - `Description` +# - `Alarm Severity` +# - `Alarm Message` +# - `Alarm Time` +# - `Alarm Value` +# - `PV Severity` +# - `PV Message` alarm_table_columns=Icon, PV, Description, Alarm Severity, Alarm Message, Alarm Time, Alarm Value, PV Severity, PV Message # By default, the alarm table uses the common alarm severity colors @@ -77,70 +94,86 @@ alarm_table_columns=Icon, PV, Description, Alarm Severity, Alarm Message, Alarm # based on brightness. alarm_table_color_legacy_background=true -# Alarm table row limit +# Alarm table row limit. +# # If there are more rows, they're suppressed alarm_table_max_rows=2500 -# Directory used for executing commands -# May use Java system properties like this: $(prop_name) +# Directory used for executing commands. +# +# May use Java system properties like this: `$(prop_name)` command_directory=$(user.home) -# The threshold of messages that must accumulate before the annunciator begins to simply state: "There are X Alarm messages." +# The threshold of messages that must accumulate before the annunciator begins to simply state: +# "There are X Alarm messages." annunciator_threshold=3 -# The number of messages the annunciator will retain before popping messages off the front of the message queue. +# The number of messages the annunciator will retain +# before popping messages off the front of the message queue. annunciator_retention_count=100 # Timeout in seconds at which server sends idle state updates # for the 'root' element if there's no real traffic. +# # Client will wait 3 times this long and then declare a timeout. idle_timeout=10 -# Name of the sender, the 'from' field of automated email actions +# Name of the sender, the 'from' field of automated email actions. automated_email_sender=Alarm Notifier -# Comma-separated list of automated actions on which to follow up -# Options include mailto:, cmd: +# Comma-separated list of automated actions on which to follow up. +# +# Options include `mailto:`, `cmd:` automated_action_followup=mailto:, cmd:, infopv: -# Optional heartbeat PV +# Optional heartbeat PV. +# # When defined, alarm server will set it to 1 every heartbeat_secs -#heartbeat_pv=Demo:AlarmServerHeartbeat +# +# ```{code-block} properties +# :caption: Example +# +# heartbeat_pv=Demo:AlarmServerHeartbeat +# ``` heartbeat_pv= -# Heartbeat PV period in seconds +# Heartbeat PV period in seconds. heartbeat_secs=10 -# Period for repeated annunciation +# Period for repeated annunciation. +# +# If there are active alarms, i.e. alarms that have not been acknowledged, +# a message "There are 47 active alarms" will be issued. # -# If there are active alarms, i.e. alarms that have not been acknowleded, -# a message "There are 47 active alarms" will be issued +# :format: `HH:MM:SS`, for example `00:15:00` to nag every 15 minutes. # -# Format is HH:MM:SS, for example 00:15:00 to nag every 15 minutes. -# Set to 0 to disable +# Set to 0 to disable nag_period=00:15:00 -# Connection validation period in seconds +# Connection validation period in seconds. # # Server will check the Kafka connection at this period. # After re-establishing the connection, it will # re-send the state of every alarm tree item. +# # Set to 0 to disable. connection_check_secs=5 -# To turn on disable notifications feature, set the value to true +# To turn on disable notifications feature, set the value to `true` disable_notify_visible=false -# Options for the "Disable until.." shortcuts in the PV config dialog +# Options for the "Disable until.." shortcuts in the PV config dialog. +# +# :format: +# comma separated, each option needs to comply with `TimeParser.parseTemporalAmount()`: # -# Comma separated, each option needs to comply with TimeParser.parseTemporalAmount(): -# 30 seconds, 5 minutes, 1 hour, 6 hours, 1 day, 30 days, ... +# 30 seconds, 5 minutes, 1 hour, 6 hours, 1 day, 30 days, ... shelving_options=1 hour, 6 hours, 12 hours, 1 day, 7 days, 30 days # Macros for UI display, command or web links # -# Format: M1=Value1, M2=Value2 +# :format: `M1=Value1, M2=Value2` macros=TOP=/home/controls/displays,WEBROOT=http://localhost/controls/displays -# Max time in ms a producer call will block. +# Max time in milliseconds a producer call will block. max_block_ms=10000 diff --git a/app/channel/views/src/main/resources/cv_preferences.properties b/app/channel/views/src/main/resources/cv_preferences.properties index 85dc533874..cf00214617 100644 --- a/app/channel/views/src/main/resources/cv_preferences.properties +++ b/app/channel/views/src/main/resources/cv_preferences.properties @@ -2,5 +2,5 @@ # Package org.phoebus.channel.views.ui # -------------------------------------- -# Show the active PVs only +# Show the active PVs only? show_active_cb=false diff --git a/app/console/src/main/resources/console_preferences.properties b/app/console/src/main/resources/console_preferences.properties index e00d6f8eca..84b891df60 100644 --- a/app/console/src/main/resources/console_preferences.properties +++ b/app/console/src/main/resources/console_preferences.properties @@ -3,34 +3,43 @@ # ---------------------------------------- # Number of output lines to keep. +# # Older output is dropped. output_line_limit=100 # Number of lines to keep in input history, +# # accessible via up/down cursor keys history_size=20 -# Font name and size +# Font name. font_name=Liberation Mono + +# Font size. font_size=14 -# Prompt (may include trailing space) +# Prompt. +# +# May include trailing space. prompt=>>>\ -# Prompt (input field) info +# Prompt (input field) info. prompt_info=Enter console command # 'Shell' to execute. # -# Examples: -# /usr/bin/python -i -# /usr/bin/python -i /path/to/some/initial_file.py -# /bin/bash +# ```{code-block} +# :caption: Examples +# +# /usr/bin/python -i +# /usr/bin/python -i /path/to/some/initial_file.py +# /bin/bash +# ``` # # Value may include properties. shell=/usr/bin/python -i -# Folder where the shell process should be started +# Folder where the shell process should be started. # # Value may include properties. -directory=$(user.home) \ No newline at end of file +directory=$(user.home) diff --git a/app/databrowser-json/src/main/resources/archive_reader_json_preferences.properties b/app/databrowser-json/src/main/resources/archive_reader_json_preferences.properties index 0ac7881f56..5c0e1dbbac 100644 --- a/app/databrowser-json/src/main/resources/archive_reader_json_preferences.properties +++ b/app/databrowser-json/src/main/resources/archive_reader_json_preferences.properties @@ -3,7 +3,7 @@ # --------------------------------------- # Shall a precision of zero for a floating-point value result in this value -# using a number format without fractional digits (true) or shall it be treated +# using a number format without fractional digits (`true`) or shall it be treated # as an indication that the value should be rendered with a default number of -# fractional digits (false)? +# fractional digits (`false`)? honor_zero_precision=true diff --git a/app/databrowser-timescale/src/main/resources/archive_ts_preferences.properties b/app/databrowser-timescale/src/main/resources/archive_ts_preferences.properties index 49f51d5caf..dd12c8b9bb 100644 --- a/app/databrowser-timescale/src/main/resources/archive_ts_preferences.properties +++ b/app/databrowser-timescale/src/main/resources/archive_ts_preferences.properties @@ -2,21 +2,26 @@ # Package org.csstudio.archive.ts # ------------------------------- -# User and password for reading archived data +# User for reading archived data user=report +# Password for reading archived data password=$report -# Timeout [seconds] for certain SQL queries, 0 to disable timeout. +# Timeout in seconds for certain SQL queries, 0 to disable timeout. +# # Fundamentally, the SQL queries for data take as long as they take # and any artificial timeout just breaks queries that would otherwise # have returned OK a few seconds after the timeout. +# # A timeout is used for operations other than getting the actual data, # for example the channel id-by-name query which _should_ return within # a short time. timeout_secs=120 # JDBC Statement 'fetch size': +# # Number of samples to read in one network transfer. +# # Speed tends to increase with fetch size. -# On the other hand, bigger numbers can result in java.lang.OutOfMemoryError. -fetch_size=10000 \ No newline at end of file +# On the other hand, bigger numbers can result in `java.lang.OutOfMemoryError`. +fetch_size=10000 diff --git a/app/databrowser/src/main/resources/databrowser_preferences.properties b/app/databrowser/src/main/resources/databrowser_preferences.properties index e5ecaaef69..1bc8764b59 100644 --- a/app/databrowser/src/main/resources/databrowser_preferences.properties +++ b/app/databrowser/src/main/resources/databrowser_preferences.properties @@ -2,8 +2,11 @@ # Package org.csstudio.trends.databrowser3 # ---------------------------------------- -# Default auto scale value -# Possible values are: true to enable the automatic calculation of the min/max Y-axis, or false to use min/max fixed values. +# Default auto scale value. +# +# Possible values are: +# - `true` to enable the automatic calculation of the min/max Y-axis +# - `false` to use min/max fixed values. use_auto_scale=false # Default time span displayed in plot in seconds @@ -21,15 +24,24 @@ live_buffer_size=5000 # Default line width line_width=2 -# Opacity of 'area' -# 0%: Area totally transparent (invisible) -# 20%: Area quite transparent -# 100%: Area uses solid color +# Opacity of 'area': +# +# :0%: Area totally transparent (invisible) +# :20%: Area quite transparent +# :100%: Area uses solid color opacity=40 # Default trace type for newly created traces. -# Allowed values are defined by org.csstudio.trends.databrowser3.model.TraceType: -# AREA, ERROR_BARS, SINGLE_LINE, AREA_DIRECT, SINGLE_LINE_DIRECT, SQUARES, ... +# +# Allowed values are defined by `org.csstudio.trends.databrowser3.model.TraceType`: +# +# - `AREA` +# - `ERROR_BARS` +# - `SINGLE_LINE` +# - `AREA_DIRECT` +# - `SINGLE_LINE_DIRECT` +# - `SQUARES` +# - ... trace_type=AREA # Delay in milliseconds that delays archive requests when @@ -38,6 +50,7 @@ trace_type=AREA archive_fetch_delay=500 # Number of concurrent archive fetch requests. +# # When more requests are necessary, the background jobs # will wait until the previously submitted jobs complete, # to limit the number of concurrent requests. @@ -48,35 +61,44 @@ archive_fetch_delay=500 # # Note that this does not apply to 'exporting' data # in spreadsheet form, where data for N channels is still -# collected by reading from N concurrent archive readers. +# collected by reading from N concurrent archive readers. concurrent_requests=1000 # Number of binned samples to request for optimized archive access. +# # Negative values scale the display width, # i.e. -3 means: 3 times Display pixel width. plot_bins=-3 -# Suggested data servers -# Format: *| -# List of URLs, separated by '*'. -# Each URL may be followed by an "|alias" +# Suggested data servers. +# +# :format: +# `*|` +# +# List of URLs, separated by `*`. +# +# Each URL may be followed by an `|alias` +# +# RDB URLs: +# +# jdbc:mysql://localhost/archive # -# RDB URLs -# jdbc:mysql://localhost/archive +# Archive Appliance: # -# Archive Appliance -# pbraw\://arcapp01.site.org:17668/retrieval +# pbraw\://arcapp01.site.org:17668/retrieval # -# Channel Archiver Network Data Server -# xnds://localhost/archive/cgi/ArchiveDataServer.cgi +# Channel Archiver Network Data Server: # -# Channel Archiver index file (binary) or index.xml (list of indices) -# cadf:/path/to/index -# cadf:/path/to/index.xml +# xnds://localhost/archive/cgi/ArchiveDataServer.cgi +# +# Channel Archiver index file (binary) or index.xml (list of indices): +# +# cadf:/path/to/index +# cadf:/path/to/index.xml urls=jdbc:mysql://localhost/archive|RDB*xnds://localhost/archive/cgi/ArchiveDataServer.cgi # Default data sources for newly added channels -# Format: Same as 'urls' +# Format: Same as {prefs:pref}`urls` archives=jdbc:mysql://localhost/archive|RDB*xnds://localhost/archive/cgi/ArchiveDataServer.cgi # When opening existing data browser plot, @@ -86,55 +108,62 @@ use_default_archives=false # If there is an error in retrieving archived data, # should that archive data source be dropped from the channel? +# # This is meant to avoid needless queries to archives that cannot be accessed. -# Note that archive data sources which clearly report a channel as "not found" +# +# :::{note} +# Archive data sources which clearly report a channel as "not found" # will still be dropped. This option only configures if data sources which # return an error (cannot connect, ...) should be queried again for the given channel. +# ::: drop_failed_archives=true # With EPICS IOCs from release 7 on, the PVs -# "xxx", "ca://xxx" and "pva://xxx" all refer -# to the same record "xxx" on the IOC. +# `xxx`, `ca://xxx` and `pva://xxx` all refer +# to the same record `xxx` on the IOC. # -# When the plot requests "pva://xxx", the archive might still -# trace that channel as "ca://xxx" or "xxx". +# When the plot requests `pva://xxx`, the archive might still +# trace that channel as `ca://xxx` or `xxx`. # Alternatively, the archive might already track the channel -# as "pva://xxx" while data browser plots still use "ca://xxx" -# or just "xxx". +# as `pva://xxx` while data browser plots still use `ca://xxx` +# or just `xxx`. # This preference setting instructs the data browser # to try all equivalent variants. If any types are listed, -# just "xxx" without any prefix will also be checked in addition +# just `xxx` without any prefix will also be checked in addition # to the listed types. # -# The default of setting of "ca, pva" supports the seamless +# The default of setting of `ca, pva` supports the seamless # transition between the key protocols. # # When `equivalent_pv_prefixes` is empty, # the PV name is used as is without looking for any equivalent names. equivalent_pv_prefixes=ca, pva -# Re-scale behavior when archived data arrives: NONE, STAGGER +# Re-scale behavior when archived data arrives: `NONE`, `STAGGER` archive_rescale=STAGGER # Shortcuts offered in the Time Axis configuration -# Format: -# Text for shortcut,start_spec|Another shortcut,start_spec +# +# :format: `Text for shortcut,start_spec|Another shortcut,start_spec` time_span_shortcuts=30 Minutes,-30 min|1 Hour,-1 hour|12 Hours,-12 hour|1 Day,-1 days|7 Days,-7 days -#It is a path to the directory where the PLT files for WebDataBrowser are placed. +# Path to the directory where the PLT files for WebDataBrowser are placed. plt_repository=/opt/codac/opi/databrowser/ -# Automatically refresh history data when the liver buffer is full +# Automatically refresh history data when the liver buffer is full. +# # This will prevent the horizontal lines in the shown data when the buffer -# is too small to cover the selected time range +# is too small to cover the selected time range. automatic_history_refresh=true # Scroll step, i.e. size of the 'jump' left when scrolling, in seconds. -# (was called 'future_buffer') +# (was called `future_buffer`) scroll_step = 5 -# Display the trace names on the Value Axis -# the default value is "true". "false" to not show the trace names on the Axis +# Display the trace names on the Value Axis. +# +# The default value is `true`. +# Set it to `false` to not show the trace names on the Axis use_trace_names = true # Prompt / warn when trying to request raw data? @@ -144,20 +173,25 @@ prompt_for_raw_data_request = true prompt_for_visibility = true # Shortcuts offered in the Time Axis configuration -# Format: -# Text for shortcut,start_spec|Another shortcut,start_spec +# +# :format: `Text for shortcut,start_spec|Another shortcut,start_spec` time_span_shortcuts=30 Minutes,-30 min|1 Hour,-1 hour|12 Hours,-12 hour|1 Day,-1 days|7 Days,-7 days -# Determines if the plot runtime config dialog is supported. Defaults to false as the Data Browser +# Determines if the plot runtime config dialog is supported. +# +# Defaults to `false` as the Data Browser # offers the same functionality through its configuration tabs. config_dialog_supported=false -# Determines default value axis label policy. Supported options: -# pv-name: classic policy. Default if this property is not set or set to an unsupported value. -# pv-desc: use DESC field, if available from PV and non-empty. Works only with pva. +# Determines default value axis label policy. +# +# Supported options: +# +# - `pv-name`: classic policy. Default if this property is not set or set to an unsupported value. +# - `pv-desc`: use `DESC` field, if available from PV and non-empty. Works only with pva. value_axis_label_policy=pv-name # Determines whether, by default, in the "Add PV(s) from the Clipboard"-window, the option to add -# all PVs to the same axis is enabled (when 'true'), or whether the option to add all PVs to -# different axes is enabled (when 'false'). +# all PVs to the same axis is enabled (when `true`), or whether the option to add all PVs to +# different axes is enabled (when `false`). assign_pvs_from_clipboard_to_the_same_axis_by_default=false diff --git a/app/display/convert-edm/src/main/resources/edm_converter_preferences.properties b/app/display/convert-edm/src/main/resources/edm_converter_preferences.properties index a34115e0f7..0621084a80 100644 --- a/app/display/convert-edm/src/main/resources/edm_converter_preferences.properties +++ b/app/display/convert-edm/src/main/resources/edm_converter_preferences.properties @@ -4,76 +4,89 @@ # Path to the directory where the auto-converter will # generate auto-converted files. -# May include system properties like $(user.home). +# +# May include system properties like `$(user.home)`. +# # Target directory must be in the file system. # The folder is created if it doesn't exist. -# +# # When left empty, the auto-converter is disabled. auto_converter_dir= # Path (prefix) that will be stripped from the original # EDM file name before converting. +# # When empty, the complete path will be stripped. # # For example, assume we need to convert -# /path/to/original/vacuum/segment1/vac1.edl +# {file}`/{path/to/original}/vacuum/segment1/vac1.edl`. # -# With an empty auto_converter_strip, -# this will be converted into {auto_converter_dir}/vac1.edl +# With an empty `auto_converter_strip`, +# this will be converted into {file}`{auto_converter_dir}/vac1.edl`. # -# With auto_converter_strip=/path/to/original, -# it will be converted into {auto_converter_dir}/vacuum/segment1/vac1.edl +# With `auto_converter_strip=/path/to/original`, +# it will be converted into {file}`{auto_converter_dir}/vacuum/segment1/vac1.edl`. auto_converter_strip= -# EDM colors.list file +# EDM `colors.list` file. +# # Must be defined to use converter. -# May be a file system path or http:/.. link +# May be a file system path or an `http://` link colors_list= # Font mappings # -# Format: EDMFontPattern=DisplayBuilderFont,Pattern=Font,... -# EDMFontPattern is regular expression for the name used by EDM +# :format: `EDMFontPattern=DisplayBuilderFont,Pattern=Font,...` +# +# `EDMFontPattern` is regular expression for the name used by EDM # # Patterns are checked in the order in which they're listed in here, -# so a catch-all ".*" pattern should be at the end +# so a catch-all `.*` pattern should be at the end font_mappings=helvetica=Liberation Sans,courier=Liberation Mono,times=Liberation Serif,.*=Liberation Sans # Path to text file that lists EDM search paths. -# May be a file system path or http:/.. link. +# +# May be a file system path or an `http://` link. # # In the file, each line in the text file contains a path, -# which may be a file system path or a http:// link. -# When trying to open an *.edl file, +# which may be a file system path or a `http://` link. +# +# When trying to open a {file}`{display}.edl` file, # converter will try each path in the order # listed in the file. -# Lines starting with "#" are ignored. # -# When the edm_paths_config is left empty, +# Lines starting with `#` are ignored. +# +# When the `edm_paths_config` is left empty, # the converter won't find files. edm_paths_config= -# Pattern and replacement for patching paths to *.stp (StripTool) files +# Pattern for patching paths to {file}`{name}.stp` (StripTool) files. # -# 'Shell Command' buttons in EDM that invoke a command of the form +# 'Shell Command' buttons in EDM that invoke a command of the form: # # StripTool /some/path/to/plot.stp # -# are converted into ActionButtons which open the `/some/path/to/plot.stp` file. +# are converted into `ActionButtons` which open the `/some/path/to/plot.stp` file. # Data Browser will then open the file when the action is invoked. # # The following regular expression pattern and replacement can be used -# to patch `/some/path/to/plot.stp`. +# to patch {file}`/{some/path/to/plot}.stp`. # By default, both are empty, so the path remains unchanged. # # Example for transforming all absolute paths into a web location: # -# stp_path_patch_pattern=^(/) -# stp_path_patch_replacement=https://my_web_server/stripcharts$1 +# org.csstudio.display.converter.edm/stp_path_patch_pattern=^(/) +# org.csstudio.display.converter.edm/stp_path_patch_replacement=https://my_web_server/stripcharts$1 # # Note how the pattern may include group markers (..) # and the replacement can reference them via $1, $2, ... stp_path_patch_pattern= + +# Replacement for patching paths to {file}`{name}.stp` (StripTool) files. +# +# See {prefs:pref}`stp_path_patch_pattern` +# for more information. stp_path_patch_replacement= # Strip "close" buttons which are not needed in Phoebus tabs and windows diff --git a/app/display/convert-medm/doc/index.rst b/app/display/convert-medm/doc/index.rst index 31ce4bfda8..8e5329ca85 100644 --- a/app/display/convert-medm/doc/index.rst +++ b/app/display/convert-medm/doc/index.rst @@ -71,7 +71,9 @@ To use the EDM converter, add the following to your settings:: org.csstudio.display.converter.edm/edm_paths_config=/path/to/edm_paths.txt org.csstudio.display.converter.edm/colors_list=/path/to/edm/colors.list -For details, see full description of :ref:`preference_settings`. +.. seealso:: + + For details, see the :prefs:pack:`org.csstudio.display.converter.edm` preferences. Each time you now try to open an ``*.edl`` file, the converter will create a ``*.bob`` file in the same location and then open it. diff --git a/app/display/editor/src/main/resources/display_editor_preferences.properties b/app/display/editor/src/main/resources/display_editor_preferences.properties index ab5a17f848..2c3028c248 100644 --- a/app/display/editor/src/main/resources/display_editor_preferences.properties +++ b/app/display/editor/src/main/resources/display_editor_preferences.properties @@ -4,18 +4,18 @@ # Widget types to hide from the palette # -# Comma separated list of widget types that will not be shown -# in the palette. +# :format: Comma separated list of widget types that will not be shown in the palette. +# # Existing displays that use these widgets can still be edited # and executed, but widgets do not appear in the palette to # discourage adding them to new displays. - -# Hiding widgets where representation has not been imported because of dependencies -hidden_widget_types=linear-meter,gauge,clock,digital_clock -# # +# The default value is hiding widgets where representation has not been +# imported because of dependencies. +hidden_widget_types=linear-meter,gauge,clock,digital_clock + # GUI Menu action Applications / Display / New Display opens the following template new_display_template=examples:/initial.bob -# Size of undo stack. Defaults to 50 if not set. +# Size of the undo stack. undo_stack_size=50 diff --git a/app/display/model/src/main/resources/display_model_preferences.properties b/app/display/model/src/main/resources/display_model_preferences.properties index ef9f42738d..25321dfbb4 100644 --- a/app/display/model/src/main/resources/display_model_preferences.properties +++ b/app/display/model/src/main/resources/display_model_preferences.properties @@ -4,18 +4,24 @@ # Widget classes -# One or more *.bcf files, separated by ';' -# Defaults to built-in copy of examples/classes.bcf +# +# :format: One or more {file}`{name}.bcf` files, separated by `;` +# +# Defaults to the built-in copy of `examples/classes.bcf` class_files=examples:classes.bcf # Named colors -# One or more *.def files, separated by ';' -# Defaults to built-in copy of examples/color.def +# +# :format: One or more {file}`{name}.def` files, separated by `;` +# +# Defaults to built-in copy of `examples/color.def` color_files=examples:color.def # Named fonts -# One or more *.def files, separated by ';' -# Defaults to built-in copy of examples/font.def +# +# :format: One or more {file}`{name}.def` files, separated by `;` +# +# Defaults to built-in copy of `examples/font.def` font_files=examples:font.def # Global macros, used for all displays. @@ -24,27 +30,32 @@ font_files=examples:font.def # and can then add new macros or overwrite # the values of these macros. # -# Format: -# Entries where the XML tag name is the macro name, -# and the XML content is the macro value. +# :format: +# Entries where the XML tag name is the macro name, +# and the XML content is the macro value. +# # The macro name must be a valid XML tag name: +# # * Must start with character # * May then contain characters or numbers # * May also contain underscores -# E.g. -# macros=Value from Preferencestrue +# +# E.g.: +# +# macros=Value from Preferencestrue macros= -# Timeout [ms] for loading files: Displays, but also color, font, widget class files +# Timeout in milliseconds for loading files: Displays, but also color, font, widget class files read_timeout=10000 -# Timeout [sec] for caching files loaded from a URL +# Timeout in seconds for caching files loaded from a URL cache_timeout=60 -# 'BOY' *.opi files provide the font size in 'points'. +# 'BOY' {file}`{display}.opi` files provide the font size in 'points'. # All other positions and sizes are in 'pixels'. +# # A point is meant to represent 1/72th of an inch. # The actual on-screen size display settings. # Plugging a different monitor into the computer can @@ -57,10 +68,9 @@ cache_timeout=60 # This factor is used to translate legacy font sizes # from 'points' into 'pixel': # -# legacy_points = pixel * legacy_font_calibration +# legacy_points = pixel * legacy_font_calibration # -# The test program -# org.csstudio.display.builder.representation.swt.SWTFontCalibation +# The test program `org.csstudio.display.builder.representation.swt.SWTFontCalibation` # can be used to obtain the factor when executed on the original # platform where the legacy display files were created. # @@ -69,14 +79,15 @@ cache_timeout=60 # result in _smaller_ fonts in the display builder legacy_font_calibration=1.01 -# Maximum re-parse operations +# Maximum re-parse operations. +# +# When reading legacy {file}`{display}.opi` files and for example +# finding a `TextUpdate` widget that has no ``, +# it will be changed into a `Label` widget and then re-parsed. # -# When reading legacy *.opi files and for example -# finding a "TextUpdate" widget that has no , -# it will be changed into a "Label" widget and then re-parsed. # If more than a certain number of re-parse operations are triggered # within one 'level' of the file (number of widgets at the root of the display, -# or number of childred for a "Group" widget), +# or number of childred for a `Group` widget), # the parser assumes that it entered an infinite re-parse loop # and aborts. max_reparse_iterations=5000 @@ -91,6 +102,7 @@ skip_defaults=true enable_saved_on_comments=false # Enable the "SVG Rendering Resolution Factor" widget property to the Symbol and Picture widgets. +# # This functionality can enable a sharper image when zooming in, at the expense of a quadratic # increase in memory consumption. E.g., by setting the SVG rendering resolution factor to 2.0, an # SVG can be rendered at twice the width and twice the height, but the memory required to diff --git a/app/display/representation-javafx/src/main/resources/jfx_repr_preferences.properties b/app/display/representation-javafx/src/main/resources/jfx_repr_preferences.properties index 11081928b7..bc39f7e5ce 100644 --- a/app/display/representation-javafx/src/main/resources/jfx_repr_preferences.properties +++ b/app/display/representation-javafx/src/main/resources/jfx_repr_preferences.properties @@ -5,7 +5,8 @@ # When clicking on the 'slider' widget 'track', # should the value increment/decrement, # matching the behavior of EDM, BOY, ...? -# Otherwise, jump to the clicked value right away. +# +# Otherwise, jump to the clicked value right away. inc_dec_slider=true # How does mouse need to hover until tool tip appears? @@ -14,11 +15,13 @@ tooltip_delay_ms=250 # Once displayed, how long does the tool tip remain visible? tooltip_display_sec=30 -# Note that for historic reasons tool tips are also influenced +# :::{note} +# For historic reasons tool tips are also influenced # by the property `org.csstudio.display.builder.disable_tooltips`. # When `true`, tool tips are disabled. +# ::: # Determines whether the mouse can interact with the bounds -# of the symbol widget. If false, interaction is +# of the symbol widget. If `false`, interaction is # limited to the visible area of the element. pick_on_bounds=false diff --git a/app/display/representation/src/main/resources/display_representation_preferences.properties b/app/display/representation/src/main/resources/display_representation_preferences.properties index 4a0dee2507..32724cbba7 100644 --- a/app/display/representation/src/main/resources/display_representation_preferences.properties +++ b/app/display/representation/src/main/resources/display_representation_preferences.properties @@ -2,7 +2,7 @@ # Package org.csstudio.display.builder.representation # --------------------------------------------------- -## Representation Tuning +# Representation Tuning. # # The representation 'throttles' updates to widgets. # When a widget requests an update, a little accumulation time @@ -26,18 +26,21 @@ performance_log_period_secs = 5 # UI thread durations above this threshold are logged performance_log_threshold_ms = 20 -# Pause between updates of plots (XY, lines) -# Limit to 250ms=4 Hz +# Pause between updates of plots (XY, lines). +# +# Limit to {math}`250ms = 4Hz` plot_update_delay = 250 -# Pause between updates of image plots -# Limit to 250ms=4 Hz +# Pause between updates of image plots. +# +# Limit to {math}`250ms = 4Hz` image_update_delay = 250 -# Length limit for tool tips +# Length limit for tool tips. +# # Tool tips that are too long can be a problem # on some window systems. tooltip_length=200 -# Timeout for load / unload of Embedded Widget content [ms] +# Timeout for load / unload of Embedded Widget content, in milliseconds. embedded_timeout=5000 diff --git a/app/display/runtime/src/main/resources/display_runtime_preferences.properties b/app/display/runtime/src/main/resources/display_runtime_preferences.properties index 9e23ee7bd5..f334911a03 100644 --- a/app/display/runtime/src/main/resources/display_runtime_preferences.properties +++ b/app/display/runtime/src/main/resources/display_runtime_preferences.properties @@ -3,46 +3,61 @@ # -------------------------------------------- # Search path for Jython scripts used by the display runtime. +# # Note that format depends on the OS. -# On UNIX systems, path entries are separated by ':', on Windows by ';'. +# On UNIX systems, path entries are separated by `:`, on Windows by `;`. +# +# ```{code-block} properties +# :caption: Example +# # python_path=/home/controls/displays/scripts:/home/fred/my_scripts +# ``` python_path= # PV Name Patches # # Translate PV names based on regular expression pattern and replacement # -# Format: pattern@replacement@pattern@replacement +# :format: {samp}`{pattern}@{replacement}@{pattern}@{replacement}` # # Setting must contain a sequence of pattern & replacement pairs, -# all separated by '@'. +# all separated by `@`. # -# The regular expression for the pattern can includes "( )" groups, -# which are then used in the replacement via "$1", "$2", .. +# The regular expression for the pattern can includes `( )` groups, +# which are then used in the replacement via `$1`, `$2`, .. # -# If the item separator character '@' itself is required within the pattern or replacement, -# use '[@]' to distinguish it from the item separator, i.e. -# -# [@]work@[@]home +# If the item separator character `@` itself is required within the pattern or replacement, +# use `[@]` to distinguish it from the item separator, i.e. # -# will patch "be@work" -> "be@home" +# [@]work@[@]home +# +# will patch `be@work` to `be@home` # # Patches are applied in the order they're listed in the preference, i.e. # later patches are applied to names already patched by earlier ones. # -# Example: -# Remove PVManager's longString modifier, 'some_pv {"longString":true}' -> 'some_pv' -# turn constant formula into constant local variable, '=42' -> 'loc://const42(42)' -# as well as constant name into constant local var, '="Fred"' -> 'loc://strFred("Fred")' +# The default value leads to the following substitutions: +# +# Remove PVManager's longString modifier: +# : `some_pv {"longString":true}` -> `some_pv` +# +# Turn constant formula into constant local variable: +# : `=42` -> `loc://const42(42)` +# +# Turn constant name into constant local var: +# : `="Fred"` -> `loc://strFred("Fred")` pv_name_patches=\\{"longString":true\\}"@@^="([a-zA-Z]+)"@loc://str$1("$1") -# PV update throttle in millisecs -# 250ms = 4 Hz +# PV update throttle in milliseconds. +# +# {math}`250ms = 4Hz` update_throttle=250 # "Probe Display" +# # Added to context menu for ProcessVariables, # invoked with macro PV set to the PV name. +# # When left empty, the "Probe Display" # context menu entry is disabled. probe_display=examples:/probe.bob diff --git a/app/errlog/src/main/resources/errlog_preferences.properties b/app/errlog/src/main/resources/errlog_preferences.properties index e800a4504e..b9756b4a99 100644 --- a/app/errlog/src/main/resources/errlog_preferences.properties +++ b/app/errlog/src/main/resources/errlog_preferences.properties @@ -2,5 +2,5 @@ # Package org.phoebus.applications.errlog # --------------------------------------- -# Number of lines to keep in error log -max_lines = 500 \ No newline at end of file +# Number of lines to keep in error log. +max_lines = 500 diff --git a/app/filebrowser/src/main/resources/filebrowser_preferences.properties b/app/filebrowser/src/main/resources/filebrowser_preferences.properties index 76a14fc606..c9d50f4655 100644 --- a/app/filebrowser/src/main/resources/filebrowser_preferences.properties +++ b/app/filebrowser/src/main/resources/filebrowser_preferences.properties @@ -2,11 +2,13 @@ # Package org.phoebus.applications.filebrowser # -------------------------------------------- -# Initial root directory for newly opened file browser -# May use system properties like "$(user.home)". +# Initial root directory for newly opened file browser. +# +# May use system properties like `$(user.home)`. +# # At runtime, user can select a different base directory, # but pressing the "Home" button reverts to this one. default_root=$(user.home) -# Show hidden files (File.isHidden)? -show_hidden=false \ No newline at end of file +# Show hidden files (`File.isHidden`)? +show_hidden=false diff --git a/app/logbook/olog/client-es/src/main/resources/olog_es_preferences.properties b/app/logbook/olog/client-es/src/main/resources/olog_es_preferences.properties index 1153ca956b..486c41cd65 100644 --- a/app/logbook/olog/client-es/src/main/resources/olog_es_preferences.properties +++ b/app/logbook/olog/client-es/src/main/resources/olog_es_preferences.properties @@ -2,15 +2,24 @@ # Package org.phoebus.olog.es.api # -------------------------------------- -# The olog url +# The Olog URL. +# +# :format: `http(s)://foo.com/Olog` +# +# :::{important} +# The `Olog` path element may *not* be omitted. +# ::: olog_url=http://localhost:8080/Olog -# The connection timeout for HttpClient, in ms. 0 = infinite. +# The connection timeout for HttpClient, in milliseconds. +# +# 0 = infinite. connectTimeout=0 -# Enable a permissive hostname verifier +# Enable a permissive hostname verifier. permissive_hostname_verifier=true # Comma separated list of "Levels" in the create logbook entry UI. +# # Sites may wish to customize (and localize) this. -levels=Urgent,Suggestion,Info,Request,Problem \ No newline at end of file +levels=Urgent,Suggestion,Info,Request,Problem diff --git a/app/logbook/olog/client/src/main/resources/olog_preferences.properties b/app/logbook/olog/client/src/main/resources/olog_preferences.properties index 0b7dca0f1d..fb0af5f53b 100644 --- a/app/logbook/olog/client/src/main/resources/olog_preferences.properties +++ b/app/logbook/olog/client/src/main/resources/olog_preferences.properties @@ -2,15 +2,19 @@ # Package org.phoebus.olog.api # -------------------------------------- -# The olog url +# The Olog URL. olog_url=localhost:9092 -# User credentials for olog +# User name credential for Olog. username=user + +# User password credential for Olog password=**** -# Enable debugging of http request and resposnsed +# Enable debugging of HTTP requests and responses. debug=false -# The connection timeout for the Jersey client, in ms. 0 = infinite. +# The connection timeout for the Jersey client, in milliseconds. +# +# 0 = infinite. connectTimeout=0 diff --git a/app/logbook/olog/ui/doc/index.rst b/app/logbook/olog/ui/doc/index.rst index b69b287a43..ba1d8ef429 100644 --- a/app/logbook/olog/ui/doc/index.rst +++ b/app/logbook/olog/ui/doc/index.rst @@ -7,6 +7,7 @@ https://github.com/ControlSystemStudio/phoebus/tree/master/phoebus-product. Features -------- + - Arbitrary number of "logbooks", configured in the service. A logbook entry is contained in one or several logbooks. - Arbitrary number of "tags", configured in the service. A logbook entry may be associated with zero or several tags. @@ -14,9 +15,9 @@ Features - Arbitrary number of "properties", configured on the service. A property is a named list of key/value pairs. The user may define values for the items in a property. A logbook entry is associated with zero or several properties. - Arbitrary number of attachments, i.e. images or other file types. - + - Markup as defined by the Commonmark specification (https://commonmark.org). - + - Log entry editor invocation from context menu whereby context specific attachments or data are automatically appended to the log entry. - Log entry viewers offer search capabilities based on meta data and content. @@ -29,15 +30,17 @@ be rendered as plain text. Launching the log entry editor ------------------------------ + The log entry editor is launched as a non-modal window using one of the following methods: - From the dedicated button in the application toolbar. -- From application menu Applications -> Utility -> Send to Logbook. +- From application menu :menuselection:`Applications --> Utility --> Send to Logbook`. - Using the New Log Entry button in the log entry details view of the logbook application. -- Using the New Log Entry context menu item in the search result list view of the logbook application. This option also supports the keyboard combination CTRL+N. +- Using the New Log Entry context menu item in the search result list view of the logbook application. + This option also supports the keyboard combination :kbd:`CTRL-N`. The log entry editor may also be launched from context menus, where applicable. For instance, with a right click on the background of an OPI the launched context menu will include the Create Log item: @@ -54,9 +57,9 @@ The log entry editor is a non-modal dialog: Mandatory data are: - Username and password, see also preferences_. - + - Title - + - At least one logbook, see also preferences_. Additional logbooks - configured in the service - can be added from a list shown when pressing the down button: .. image:: images/LogbookSelection.png @@ -73,19 +76,26 @@ Additional images (or other type of attachments) may be added by expanding the A .. image:: images/Attachments.png Here user may attach any number of files of arbitrary types: -- ``Add Files`` will launch the native file browser dialog from which user may select any number of files. -- ``Clipboard`` will attach the file - if any - currently copied to the host OS clipboard. -- ``CSS Window`` will attach an image of the current application window. -- ``Embed New`` will launch the dialog to embed an image to the log entry body, see below. -- ``Embed Selected`` will embed user selected image files previously added to the list of attachments. +- :guilabel:`Add Files` will launch the native file browser dialog from which user may select any number of files. +- :guilabel:`Clipboard` will attach the file - if any - currently copied to the host OS clipboard. +- :guilabel:`CSS Window` will attach an image of the current application window. +- :guilabel:`Embed New` will launch the dialog to embed an image to the log entry body, see below. +- :guilabel:`Embed Selected` will embed user selected image files previously added to the list of attachments. -**NOTE**: The Olog service will not accept upload of attachments larger than the configured limit of 50MB. The Olog service -can be configured to use a different limit, but users should keep in mind that download of large attachments to -the log viewer may incur delays in terms of UI updates. +.. note:: -**NOTE**: Since iOS 11 the default camera image format is HEIC/HEIF (High-Efficiency Image Format). This type of -image file is not supported. Consequently upload of HEIC files is blocked by the application. Moreover, HEIC files converted to JPEG -in native Mac OS applications (e.g. Preview) may also fail to render and are also blocked from upload. + The Olog service will not accept upload of attachments larger than the configured limit of 50MB. + The Olog service can be configured to use a different limit, + but users should keep in mind that download of large attachments to the log viewer + may incur delays in terms of UI updates. + +.. note:: + + Since iOS 11 the default camera image format is HEIC/HEIF (High-Efficiency Image Format). + This type of image file is not supported. + Consequently upload of HEIC files is blocked by the application. + Moreover, HEIC files converted to JPEG in native Mac OS applications (e.g. Preview) + may also fail to render and are also blocked from upload. Embedded images --------------- @@ -112,14 +122,15 @@ User may select what properties to include in the log entry, and edit the values Log entry viewer ---------------- -The menu item Applications -> Utility -> Log Entry Table will launch an application (in a new tab) in which the user may -search and view log entries: + +The menu item :menuselection:`Applications --> Utility --> Log Entry Table` will launch an application (in a new tab) +in which the user may search and view log entries: .. image:: images/LogEntryTable.png User may choose to hide some details of each log entry in the list in order to fit more items in the view and to reduce the need -for scrolling. This can be done using the keyboard shortcut ``CTRL+SHIFT+D``, or by selecting the -``Show/Hide Details`` item from the context menu invoked through a right click in the table view. The choice +for scrolling. This can be done using the keyboard shortcut :kbd:`CTRL-SHIFT-D`, or by selecting the +:guilabel:`Show/Hide Details` item from the context menu invoked through a right click in the table view. The choice to show or hide details is persisted between restarts of the application. .. image:: images/ContextMenuLogEntryTable.png @@ -180,8 +191,6 @@ The navigation buttons are not rendered if hit count less or equal to the page s .. image:: images/pagination.png -.. _preferences: - Periodic Search ^^^^^^^^^^^^^^^ @@ -206,14 +215,16 @@ If user double-clicks on a OPI file attachment (.bob file), the application will If user double-clicks on a Data Browser attachment (.plt file), the application will launch the Data Browser. Preview of non-image files is not offered in the application. However, external viewers may be configured for -arbitrary file extensions, see preference_settings_ (framework.workbench) for more information. +arbitrary file extensions, see :prefs:pack:`org.phoebus.framework.workbench` preferences for more information. Log Entry Grouping ------------------ -The preference setting ``log_entry_groups_support`` - if set to ``true`` - will enable the "log entry grouping" -feature. With this users will be able to reply to individual log entries implicitly creating a group of log entries. To use this -feature user can choose to: +The preference setting :prefs:pref:`org.phoebus.logbook.olog.ui/log_entry_groups_support`, +if set to ``true``, +will enable the "log entry grouping" feature. +With this users will be able to reply to individual log entries implicitly creating a group of log entries. +To use this feature user can choose to: - Press the Reply button shown in the log entry view: @@ -231,10 +242,13 @@ In the log entry view, the "Show/Hide Group" button (see screen shot above) can ordered on created date with oldest log entry on top. In this merged view attachments and properties are not shown. Clicking on a header in the merged view will show that log entry in full. -**NOTE**: To be able to group log entries user must be authenticated in one of the following manners: +.. important:: -* Use "credentials caching" through preference setting ``org.phoebus.logbook.olog.ui/save_credentials``. Once a log entry has been created, credentials will be reused when creating a group. -* Use the Credentials Management app to sign in to the logbook context. + To be able to group log entries user must be authenticated in one of the following manners: + + * Use "credentials caching" through preference setting :prefs:pref:`org.phoebus.ui/save_credentials`. + Once a log entry has been created, credentials will be reused when creating a group. + * Use the Credentials Management app to sign in to the logbook context. Limitations ^^^^^^^^^^^ @@ -246,25 +260,19 @@ Please consider the following limitations of the log entry group feature: - There is no parent-child relation between log entries in a group, i.e. there is no internal structure of the log entries in a group. - A log entry may be included in only one log entry group. It is hence not possible to create a new group of log entries if these are already contained in different groups. +.. _preferences: + Preferences ----------- -Preferences related to the electronic logbook are the following: - -- ``org.phoebus.olog.es.api/olog_url``. This should be on the format ``http(s)://foo.com/Olog``, where the path element ``Olog`` may not be omitted. - -- ``org.phoebus.logbook.olog.ui/default_logbooks``. This is a comma separated list of logbooks automatically associated with a new log entry. - -- ``org.phoebus.logbook.olog.ui/level_field_name``. The text shown next to the drop-down below the password field. Sites may wish to customize this to override the default value "Level". - -- ``org.phoebus.olog.es.api/levels``. List of items shown in the "Level" drop-down. - -- ``org.phoebus.logbook.ui/save_credentials``. Indicates if user credentials should be cached. If ``true``, the user will - have to specify credentials only for the first new log entry after launch of CS Studio. The side effect of credentials caching is that all entries will be created with the same user (owner) identity. - -- ``search_result_page_size``. The maximum number of hits per page to fetch and render in a search. User may override in the UI. Value must be 1 - 999, default is 30. - -- ``log_entry_groups_support``. If true, user may reply to log entries and create a log entry group from a selection of existing log entries. - +See the :prefs:pack:`org.phoebus.olog.es.api` and :prefs:pack:`org.phoebus.logbook.olog.ui` preference packages, +in particular: +- :prefs:pref:`org.phoebus.olog.es.api/olog_url` +- :prefs:pref:`org.phoebus.olog.es.api/levels` +- :prefs:pref:`org.phoebus.logbook.olog.ui/default_logbooks` +- :prefs:pref:`org.phoebus.logbook.olog.ui/level_field_name` +- :prefs:pref:`org.phoebus.logbook.olog.ui/search_result_page_size` +- :prefs:pref:`org.phoebus.logbook.olog.ui/log_entry_groups_support` +The :prefs:pref:`org.phoebus.ui/save_credentials` is also used. diff --git a/app/logbook/olog/ui/src/main/resources/log_olog_ui_preferences.properties b/app/logbook/olog/ui/src/main/resources/log_olog_ui_preferences.properties index 937392d288..f54ad10878 100644 --- a/app/logbook/olog/ui/src/main/resources/log_olog_ui_preferences.properties +++ b/app/logbook/olog/ui/src/main/resources/log_olog_ui_preferences.properties @@ -2,63 +2,104 @@ # Package org.phoebus.logbook.olog.ui # ------------------------------ -# Comma-separated list of default logbooks for new log entries. +# Comma-separated list of logbooks automatically associated with a new log entry. default_logbooks=Scratch Pad -# The default query for logbook applications +# The default query for logbook applications. default_logbook_query=desc=*&start=12 hours&end=now -# Stylesheet for the items in the log calendar view +# Stylesheet for the items in the log calendar view. calendar_view_item_stylesheet=Agenda.css -# Text to render for the "LogEntryLevel" field of a log entry. Sites may wish to customize this with respect to -# its wording and its implied purpose. +# Text to render for the "LogEntryLevel" field of a log entry. +# +# The text is shown next to the drop-down below the password field. +# +# Sites may wish to customize this with respect to its wording and its implied purpose. level_field_name=Level: -# Name of markup help. Language resolution and file extension is handled on service. +# Name of markup help. +# +# Language resolution and file extension is handled on service. markup_help=CommonmarkCheatsheet -# Root URL of the Olog web client, if one exists. Set this to the empty string -# to suppress rendering of the "Copy URL" button for a log entry. +# Root URL of the Olog web client, if one exists. +# +# Set this to the empty string to suppress rendering +# of the "Copy URL" button for a log entry. web_client_root_URL= -# Log entry groups support. If set to false user will not be able to create replies -# to log entries, and consequently UI elements and views related to log entry -# groups will not be shown. +# Log entry groups support. +# +# If set to `false` user will not be able to create replies to log entries, +# and consequently UI elements and views related to log entry groups will not be shown. +# +# If set to `true`, user may reply to log entries and create a log entry group +# from a selection of existing log entries. log_entry_groups_support=false -# Log entry update support. If set to false user will not be able to update log entries -# , and consequently UI elements and views related to updating log entry and viewing log history -# will not be displayed. +# Log entry update support. +# +# If set to false user will not be able to update log entries, +# and consequently UI elements and views related to updating log entry and viewing log history +# will not be displayed. log_entry_update_support=true -# Comma separated list of "hidden" properties. For instance, properties that serve internal -# business logic, but should not be rendered in the properties view. +# Comma separated list of "hidden" properties. +# +# For instance, properties that serve internal business logic, +# but should not be rendered in the properties view. hidden_properties=Log Entry Group -# Log Entry Table display name. If non-empty it overrides default "Log Entry Table" +# Log Entry Table display name. +# +# If non-empty it overrides default "Log Entry Table". log_entry_table_display_name= -# Log Entry Calendar display name. If non-empty it overrides default "Log Entry Calendar" +# Log Entry Calendar display name. +# +# If non-empty it overrides default "Log Entry Calendar" log_entry_calendar_display_name= # Log Entry property attribute types. +# # The preference should be a URL pointing to an attribute_type.properties file. -# e.g. log_attribute_desc=file:///C:/phoebus/app/logbook/olog/ui/src/main/resources/org/phoebus/logbook/olog/ui/log_property_attributes.properties -# Classpath resource is supported if specified like log_attribute_desc=classpath:my_attr.properties. In this -# example the my_attr.properties file must be bundled as a classpath resource in the package org.phoebus.logbook.olog.ui. +# +# For example: +# +# ```{code-block} properties +# +# org.phoebus.logbook.olog.ui/log_attribute_desc=file:///C:/phoebus/app/logbook/olog/ui/src/main/resources/org/phoebus/logbook/olog/ui/log_property_attributes.properties +# ``` +# +# Classpath resource is supported if specified like this: +# +# ```{code-block} properties +# +# org.phoebus.logbook.olog.ui/log_attribute_desc=classpath:my_attr.properties +# ``` +# +# In this example the `my_attr.properties` file must be bundled as a classpath resource +# in the package `org.phoebus.logbook.olog.ui`. # This optional file describing special types associated with some property attributes. -# log_attribute_desc= -# Limit used in "paginated" search, i.e. the number of search results per page +# Limit used in "paginated" search, i.e. the number of search results per page. +# +# :format: value must be 1-999 +# +# User may override in the UI. search_result_page_size=30 -# Number of queries maintained by the OlogQueryManager. To make sense: must be >= 5 and <=30. +# Number of queries maintained by the `OlogQueryManager`. +# +# To make sense: must be >= 5 and <=30. query_list_size=15 -# Name of the search help content. Language resolution and file extension is handled on service. +# Name of the search help content. +# +# Language resolution and file extension is handled on service. search_help=SearchHelp -# Whether or not to show the watermark by default -show_log_watermark=true \ No newline at end of file +# Whether or not to show the watermark by default. +show_log_watermark=true diff --git a/app/logbook/ui/src/main/resources/log_ui_preferences.properties b/app/logbook/ui/src/main/resources/log_ui_preferences.properties index 83034f3a2a..c5d943f99c 100644 --- a/app/logbook/ui/src/main/resources/log_ui_preferences.properties +++ b/app/logbook/ui/src/main/resources/log_ui_preferences.properties @@ -5,12 +5,13 @@ # Comma-separated list of default logbooks for new log entries. default_logbooks=Scratch Pad -# The default query for logbook applications +# The default query for logbook applications. default_logbook_query=search=*&start=12 hours&end=now -# Stylesheet for the items in the log calendar view +# Stylesheet for the items in the log calendar view. calendar_view_item_stylesheet=Agenda.css -# Text to render for the "LogEntryLevel" field of a log entry. Sites may wish to customize this with respect to -# its wording and its implied purpose. -level_field_name=Level: \ No newline at end of file +# Text to render for the `LogEntryLevel` field of a log entry. +# +# Sites may wish to customize this with respect to its wording and its implied purpose. +level_field_name=Level: diff --git a/app/pvtable/src/main/resources/pv_table_preferences.properties b/app/pvtable/src/main/resources/pv_table_preferences.properties index 3a40b2e060..6c6c2fed2f 100644 --- a/app/pvtable/src/main/resources/pv_table_preferences.properties +++ b/app/pvtable/src/main/resources/pv_table_preferences.properties @@ -2,20 +2,20 @@ # Package org.phoebus.applications.pvtable # ---------------------------------------- -# Should all BYTE[] values be considered "long strings" +# Should all `BYTE[]` values be considered "long strings"? treat_byte_array_as_string=true # Show the units when displaying values? show_units=true -# Show a "Description" column that reads xxx.DESC? +# Show a "Description" column that reads `xxx.DESC`? show_description=true -# Default tolerance for newly added items +# Default tolerance for newly added items. tolerance=0.1 -# Maximum update period for PVs in millisecs +# Maximum update period for PVs in millisecs. max_update_period=500 -#Display a text area editor for add a pv list instead of single pv +# Display a text area editor for add a pv list instead of single pv. textarea_editor=false diff --git a/app/pvtree/src/main/resources/pv_tree_preferences.properties b/app/pvtree/src/main/resources/pv_tree_preferences.properties index 89d10601c8..491f2edaf0 100644 --- a/app/pvtree/src/main/resources/pv_tree_preferences.properties +++ b/app/pvtree/src/main/resources/pv_tree_preferences.properties @@ -2,34 +2,40 @@ # Package org.phoebus.applications.pvtree # --------------------------------------- -# The channel access DBR_STRING has a length limit of 40 chars. -# Since EPICS base R3.14.11, reading fields with an added '$' returns -# their value as a char[] without length limitation. +# The channel access `DBR_STRING` has a length limit of 40 chars. +# +# Since EPICS base R3.14.11, reading fields with an added `$` returns +# their value as a `char[]` without length limitation. +# # For older IOCs, this will however fail, so set this option # only if all IOCs are at least version R3.14.11 read_long_fields=true # For each record type, list the fields to read and trace as 'links'. -# Format: record_type (field1, field2) ; record_type (...) # -# Fields can simply be listed as 'INP', 'DOL'. -# The syntax INPA-L is a shortcut for INPA, INPB, INPC, ..., INPL -# The syntax INP001-128 is a shortcut for INP001, INP002, ..., INP128 -# The general syntax is "FIELDxxx-yyy", -# where "xxx" and "yyy" are the initial and final value. -# "xxx" and "yyy" need to be of the same length, i.e. "1-9" or "01-42", NOT "1-42". -# For characters, only single-char "A-Z" is supported, NOT "AA-ZZ", -# where it's also unclear if that should turn into AA, AB, AC, .., AZ, BA, BB, BC, .., ZZ -# or AA, BB, .., ZZ +# :format: `record_type (field1, field2) ; record_type (...)` # -# bigASub is a CSIRO/ASCAP record type, doesn't hurt to add that to the shared configuration +# Fields can simply be listed as `INP`, `DOL`. # -# scalcout is a bit unfortunate since there is no shortcut for INAA-INLL. +# The syntax `INPA-L` is a shortcut for `INPA`, `INPB`, `INPC`, ..., `INPL` # -# alarm record has INP1-10. 1-9 handled by pattern, INP10 listed - +# The syntax `INP001-128` is a shortcut for `INP001`, `INP002`, ..., `INP128` +# +# The general syntax is {samp}`FIELD{xxx}-{yyy}`, +# where _xxx_ and _yyy_ are the initial and final value. +# _xxx_ and _yyy_ need to be of the same length, i.e. `1-9` or `01-42`, NOT `1-42`. +# +# For characters, only single-char `A-Z` is supported, NOT `AA-ZZ`, +# where it's also unclear if that should turn into `AA`, `AB`, `AC`, .., `AZ`, `BA`, `BB`, `BC`, .., `ZZ` +# or `AA`, `BB`, .., `ZZ`. +# +# `bigASub` is a CSIRO/ASCAP record type, doesn't hurt to add that to the shared configuration. +# +# `scalcout` is a bit unfortunate since there is no shortcut for `INAA-INLL`. +# +# `alarm` record has `INP1-10`. `1-9` handled by pattern, `INP10` listed fields=aai(INP);ai(INP);bi(INP);compress(INP);longin(INP);int64in(INP);mbbi(INP);mbbiDirect(INP);mbboDirect(INP);stringin(INP);lsi(INP);subArray(INP);waveform(INP);aao(DOL);ao(DOL);bo(DOL);fanout(DOL);longout(DOL);int64out(DOL);mbbo(DOL);stringout(DOL);sub(INPA-L);genSub(INPA-L);calc(INPA-L);calcout(INPA-L);aSub(INPA-U);seq(SELN);bigASub(INP001-128);scalcout(INPA-L,INAA,INBB,INCC,INDD,INEE,INFF,INGG,INHH,INII,INJJ,INKK,INLL);alarm(INP1-9,INP10) -# Max update period in seconds -update_period=0.5 \ No newline at end of file +# Max update period in seconds. +update_period=0.5 diff --git a/app/queue-server/src/main/resources/queueserver_preferences.properties b/app/queue-server/src/main/resources/queueserver_preferences.properties index 9d7c69a4ca..71cda0bb3e 100644 --- a/app/queue-server/src/main/resources/queueserver_preferences.properties +++ b/app/queue-server/src/main/resources/queueserver_preferences.properties @@ -2,15 +2,18 @@ # Package org.phoebus.applications.queueserver # -------------------------------------- -# The queue server url +# The queue server url. queue_server_url=http://localhost:60610 -# API key for queue server authentication -# Uses environment variable BLUESKY_API_KEY or default value 'a' +# API key for queue server authentication. +# +# Uses environment variable `BLUESKY_API_KEY` or default value `a` api_key=$(BLUESKY_API_KEY) -# Enable debugging of http request and responses +# Enable debugging of http request and responses. debug=false -# The connection timeout for the HTTP client, in ms. 0 = infinite. -connectTimeout=5000 \ No newline at end of file +# The connection timeout for the HTTP client, in milliseconds. +# +# 0 = infinite. +connectTimeout=5000 diff --git a/app/rtplot/src/main/resources/rt_plot_preferences.properties b/app/rtplot/src/main/resources/rt_plot_preferences.properties index 474d236998..3e9e4587e1 100644 --- a/app/rtplot/src/main/resources/rt_plot_preferences.properties +++ b/app/rtplot/src/main/resources/rt_plot_preferences.properties @@ -3,15 +3,20 @@ # ---------------------------------- # Coloring used to shade plot region beyond 'now' -# in time-based plots. RGBA (all values 0..255) +# in time-based plots. +# +# :format: RGBA (all values 0..255) +# # Painted on on top of grid, before traces are drawn. # # Half-transparent, average of black & white, # works for both white and black backgrounds +# +# If you prefer a rose-colored future: +# +# shady_future=255, 128, 128, 25 +# +# If you prefer to not highlight the plot region beyond 'now': +# +# shady_future=128, 128, 128, 0 shady_future=128, 128, 128, 128 - -# If you prefer a rose-colored future -# shady_future=255, 128, 128, 25 - -# If you prefer to not highlight the plot region beyond 'now' -# shady_future=128, 128, 128, 0 \ No newline at end of file diff --git a/app/save-and-restore/app/src/main/resources/save_and_restore_client_preferences.properties b/app/save-and-restore/app/src/main/resources/save_and_restore_client_preferences.properties index 56138ca424..49ef0c530e 100644 --- a/app/save-and-restore/app/src/main/resources/save_and_restore_client_preferences.properties +++ b/app/save-and-restore/app/src/main/resources/save_and_restore_client_preferences.properties @@ -2,11 +2,11 @@ # Package org.phoebus.applications.saveandrestore.client # ------------------------------------------------------ -# The URL to the save-and-restore service +# The URL to the save-and-restore service. jmasar.service.url=http://localhost:8080/save-restore -# Read timeout (in ms) used by the Jersey client +# Read timeout in milliseconds used by the Jersey client. httpClient.readTimeout=5000 -# Connect timeout in (ms) used by the Jersey client +# Connect timeout in milliseconds used by the Jersey client. httpClient.connectTimeout=5000 diff --git a/app/save-and-restore/app/src/main/resources/save_and_restore_preferences.properties b/app/save-and-restore/app/src/main/resources/save_and_restore_preferences.properties index bda0f1c9f3..f05356604a 100644 --- a/app/save-and-restore/app/src/main/resources/save_and_restore_preferences.properties +++ b/app/save-and-restore/app/src/main/resources/save_and_restore_preferences.properties @@ -2,31 +2,43 @@ # Package org.phoebus.applications.saveandrestore # ----------------------------------------------- -# Sort snapshots in reverse order of created time. Last item comes first. +# Sort snapshots in reverse order of created time. +# +# Last item comes first. sortSnapshotsTimeReversed=false -# Read timeout (in ms) when taking snapshot +# Read timeout in milliseconds when taking snapshot. readTimeout=5000 # Limit used in "paginated" search, i.e. the number of search results per page search_result_page_size=30 -# Default save-and-restore search query. Used unless a saved query is located. +# Default save-and-restore search query. +# +# Used unless a saved query is located. default_search_query=tags=golden # If declared add a date automatically in the name of the snapshot "Take Snapshot" -#default_snapshot_name_date_format=yyyy-MM-dd HH:mm:ss - -# Defines the default snapshot mode -# READ_PVS: the classic mode where PV values are read from IOCs -# FROM_ARCHIVER: PV values read from archiver at point in time selected by user +# +# ```{code-block} properties +# :caption: Example +# +# org.phoebus.applications.saveandrestore/default_snapshot_name_date_format=yyyy-MM-dd HH:mm:ss +# ``` +default_snapshot_name_date_format= + +# Defines the default snapshot mode. +# +# - `READ_PVS`: the classic mode where PV values are read from IOCs +# - `FROM_ARCHIVER`: PV values read from archiver at point in time selected by user default_snapshot_mode=READ_PVS -# Defines the default restore mode -# CLIENT_RESTORE: the restore operation is performed by the client -# SERVICE_RESTORE: the restore operation is performed by the server +# Defines the default restore mode. +# +# - `CLIENT_RESTORE`: the restore operation is performed by the client +# - `SERVICE_RESTORE`: the restore operation is performed by the server default_restore_mode=CLIENT_RESTORE # Allow leaving the description / comment field empty for Configs / (Composite) -# Snapshots +# Snapshots. allow_empty_descriptions=false diff --git a/app/save-and-restore/util/src/main/resources/save_and_restore_util_preferences.properties b/app/save-and-restore/util/src/main/resources/save_and_restore_util_preferences.properties index e2b9fa1382..195e24cf11 100644 --- a/app/save-and-restore/util/src/main/resources/save_and_restore_util_preferences.properties +++ b/app/save-and-restore/util/src/main/resources/save_and_restore_util_preferences.properties @@ -2,8 +2,8 @@ # Package org.phoebus.saveandrestore.util # ----------------------------------------------- -# connection timeout (in ms) when taking snapshot +# Connection timeout, in milliseconds, when taking snapshot. connectionTimeout=5000 -# write timeout (in ms) when restoring snapshot -writeTimeout=5000 \ No newline at end of file +# Write timeout, in milliseconds, when restoring snapshot. +writeTimeout=5000 diff --git a/app/scan/client/src/main/resources/scan_client_preferences.properties b/app/scan/client/src/main/resources/scan_client_preferences.properties index ab20517447..d1010f891d 100644 --- a/app/scan/client/src/main/resources/scan_client_preferences.properties +++ b/app/scan/client/src/main/resources/scan_client_preferences.properties @@ -8,5 +8,5 @@ host=localhost # TCP port of scan server REST interface port=4810 -# Poll period [millisecs] of the scan client (scan monitor, plot, ...) -poll_period=1000 \ No newline at end of file +# Poll period in milliseconds of the scan client (scan monitor, plot, ...) +poll_period=1000 diff --git a/app/trends/archive-reader/src/main/resources/appliance_preferences.properties b/app/trends/archive-reader/src/main/resources/appliance_preferences.properties index 04a791eb6f..17c55c3225 100644 --- a/app/trends/archive-reader/src/main/resources/appliance_preferences.properties +++ b/app/trends/archive-reader/src/main/resources/appliance_preferences.properties @@ -5,5 +5,5 @@ useStatisticsForOptimizedData=true useNewOptimizedOperator=true -# Use 'https://..' instead of plain 'http://..' ? +# Use 'https://..' instead of plain 'http://..'? useHttps=false diff --git a/app/trends/archive-reader/src/main/resources/archive_reader_rdb_preferences.properties b/app/trends/archive-reader/src/main/resources/archive_reader_rdb_preferences.properties index a542079bcc..35a6c245ad 100644 --- a/app/trends/archive-reader/src/main/resources/archive_reader_rdb_preferences.properties +++ b/app/trends/archive-reader/src/main/resources/archive_reader_rdb_preferences.properties @@ -2,76 +2,94 @@ # Package org.phoebus.archive.reader.rdb # -------------------------------------- -# User and password for reading archived data +# User for reading archived data user=archive + +# Password for reading archived data password=$archive -# Table prefix +# Table prefix. +# # For Oracle, this is typically the schema name, -# including "." +# including `.`. prefix= -# Timeout [seconds] for certain SQL queries +# Timeout in seconds for certain SQL queries. +# # Fundamentally, the SQL queries for data take as long as they take # and any artificial timeout just breaks queries that would otherwise # have returned OK a few seconds after the timeout. +# # We've seen Oracle lockups, though, that caused JDBC to hang forever # because the SAMPLE table was locked. No error/exception, just hanging. +# # A timeout is used for operations other than getting the actual data, # for example the channel id-by-name query which _should_ return within # a shot time, to catch that type of RDB lockup. -timeout_secs=120 +# # Setting the timeout to 0 disables calls to setQueryTimeout, -# which may be required for PostgreSQL where the setQueryTimeout API is not implemented. -# timeout_secs=0 - +# which may be required for PostgreSQL where the `setQueryTimeout` API is not implemented. +timeout_secs=120 # Use a BLOB to read array samples? # -# The original SAMPLE table did not contain an ARRAY_VAL column -# for the array blob data, but instead used a separate ARRAY_VAL table. -# When running against an old database, this parameter must be set to false. +# The original `SAMPLE` table did not contain an `ARRAY_VAL` column +# for the array blob data, but instead used a separate `ARRAY_VAL` table. +# When running against an old database, this parameter must be set to false. use_array_blob=true # Use stored procedures and functions for 'optimized' data readout? +# # Set to procedure name, or nothing to disable stored procedure. +# +# :::{rubric} Examples +# ::: +# +# ```{code-block} properties +# :caption: MySQL +# +# org.phoebus.archive.reader.rdb/stored_procedure=archive.get_browser_data +# ``` +# +# ```{code-block} properties +# :caption: PostgreSQL +# +# org.phoebus.archive.reader.rdb/stored_procedure=public.get_browser_data +# ``` +# +# ```{code-block} properties +# :caption: Oracle +# +# org.phoebus.archive.reader.rdb/stored_procedure=chan_arch.archive_reader_pkg.get_browser_data +# org.phoebus.archive.reader.rdb/starttime_function=SELECT chan_arch.archive_reader_pkg.get_actual_start_time (?, ?, ?) FROM DUAL +# ``` stored_procedure= starttime_function= -# MySQL: -# stored_procedure=archive.get_browser_data - -# PostgreSQL -# stored_procedure=public.get_browser_data - -# Oracle: -# stored_procedure=chan_arch.archive_reader_pkg.get_browser_data -# starttime_function=SELECT chan_arch.archive_reader_pkg.get_actual_start_time (?, ?, ?) FROM DUAL - - # JDBC Statement 'fetch size': # Number of samples to read in one network transfer. -# +# # For Oracle, the default is 10. # Tests resulted in a speed increase up to fetch sizes of 1000. -# On the other hand, bigger numbers can result in java.lang.OutOfMemoryError. +# On the other hand, bigger numbers can result in `java.lang.OutOfMemoryError`. fetch_size=1000 # With EPICS IOCs from release 7 on, the PVs -# "xxx", "ca://xxx" and "pva://xxx" all refer -# to the same record "xxx" on the IOC. +# `xxx`, `ca://xxx` and `pva://xxx` all refer +# to the same record `xxx` on the IOC. # -# When the plot requests "pva://xxx", the archive might still -# trace that channel as "ca://xxx" or "xxx". +# When the plot requests `pva://xxx`, the archive might still +# trace that channel as `ca://xxx` or `xxx`. # Alternatively, the archive might already track the channel -# as "pva://xxx" while data browser plots still use "ca://xxx" -# or just "xxx". +# as `pva://xxx` while data browser plots still use `ca://xxx` +# or just `xxx`. +# # This preference setting instructs the data browser # to try all equivalent variants. If any types are listed, -# just "xxx" without any prefix will also be checked in addition +# just `xxx` without any prefix will also be checked in addition # to the listed types. # -# The default of setting of "ca, pva" supports the seamless +# The default of setting of `ca, pva` supports the seamless # transition between the key protocols. # # When `equivalent_pv_prefixes` is empty, diff --git a/app/trends/archive-reader/src/main/resources/channelarchiver_preferences.properties b/app/trends/archive-reader/src/main/resources/channelarchiver_preferences.properties index 4b20b2b9f5..a580cb5779 100644 --- a/app/trends/archive-reader/src/main/resources/channelarchiver_preferences.properties +++ b/app/trends/archive-reader/src/main/resources/channelarchiver_preferences.properties @@ -2,5 +2,5 @@ # Package org.phoebus.archive.reader.channelarchiver # -------------------------------------------------- -# Use 'https://..' instead of plain 'http://..' ? +# Use 'https://..' instead of plain 'http://..'? use_https=false diff --git a/app/update/src/main/resources/update_preferences.properties b/app/update/src/main/resources/update_preferences.properties index cc08438da7..3990f0a4fe 100644 --- a/app/update/src/main/resources/update_preferences.properties +++ b/app/update/src/main/resources/update_preferences.properties @@ -2,13 +2,13 @@ # Package org.phoebus.applications.update # ---------------------------------------- -# Time to wait [seconds] for update check -# to allow more important tools to start +# Time to wait, in seconds, for update check +# to allow more important tools to start. delay=10 -# Version time/date +# Version time/date. # -# If the distribution found at the `update_url` +# If the distribution found at the {prefs:pref}`update_url` # is later than this date, an update will be performed. # # The updated distribution must contain a new value for @@ -18,63 +18,90 @@ delay=10 # that's one month ahead, you can suppress minor updates # for a month. # -# Format: YYYY-MM-DD HH:MM -#current_version=2018-06-18 13:10 +# :format: `YYYY-MM-DD HH:MM` +# +# ```{code-block} properties +# :caption: Example +# +# org.phoebus.applications.update/current_version=2018-06-18 13:10 +# ``` current_version= - -# Location where updates can be found +# Location where updates can be found. # -# The file:, http: or https: URL is checked. -# If it exists, and its modification time is after `current_version`, +# The `file:`, `http:`, or `https:` URL is checked. +# If it exists, and its modification time is after {prefs:pref}`current_version`, # the updated distribution is downloaded -# and the current Locations.install() is replaced. +# and the current `Locations.install()` is replaced. # # Location may include system properties -# and $(arch) will be replaced by "linux", "mac" or "win" +# and `$(arch)` will be replaced by `linux`, `mac` or `win` # to allow locations specific to each architecture. +# +# ```{code-block} properties +# :caption: Example +# +# org.phoebus.applications.update/update_url=https://controlssoftware.sns.ornl.gov/css_phoebus/nightly/product-sns-$(arch).zip +# ``` update_url= -# update_url=https://controlssoftware.sns.ornl.gov/css_phoebus/nightly/product-sns-$(arch).zip -#gitlab_api_url=https://HOST/api/v4 -#gitlab_project_id= +# Path to the "V4 API" of your GitLab instance. +# +# ```{code-block} properties +# :caption: Example +# +# org.phoebus.applications.update/gitlab_api_url=https://HOST/api/v4 +# ``` +gitlab_api_url= + +# The numeric ID of the GitLab project. +gitlab_project_id= + +# The package name used in the registry. gitlab_package_name=phoebus-$(arch) -#gitlab_token= + +# Access token for the project's API and registry. +# +# Required if access to the gitlab project is not public. +gitlab_token= # List of regular expressions, comma-separated, which will be # removed from the ZIP file entry. +# # If result is empty string, the entry is skipped. # # The update ZIP file can have various formats. # # Basic ZIP file: -# phoebus-{site, version}/* +# : `phoebus-{site, version}/*` # -# => Remove 'phoebus-.*' from entry name -# to install _content_ of zip into install_location -# without creating yet another subdir +# Remove `phoebus-.*` from entry name +# to install _content_ of zip into `install_location` +# without creating yet another subdir # # ZIP that's packaged for Windows, including JDK: -# product-sns-0.0.1/* -# jdk/* +# : `product-sns-0.0.1/*`, `jdk/*` +# +# Remove `product-sns-*` from entry name, +# skip `jdk`. +# +# ZIP that's packaged for Mac: +# : Either: +# - `phoebus.app/product-sns-0.0.1/*`: Remove `.../` +# - `phoebus.app/jdk/*`: Skip +# - `phoebus.app/Contents/*`: Skip # -# => Remove 'product-sns-*' from entry name, -# skip 'jdk'. +# or: +# - `CSS_Phoebus.app/product-sns-0.0.1/*`: Remove `.../` +# - `CSS_Phoebus.app/jdk/*`: Skip +# - `CSS_Phoebus.app/Contents/*`: Skip # -# ZIP that's packaged for Mac: Either -# phoebus.app/product-sns-0.0.1/* => Remove .../ -# phoebus.app/jdk/* => Skip -# phoebus.app/Contents/* => Skip -# or: -# CSS_Phoebus.app/product-sns-0.0.1/* => Remove .../ -# CSS_Phoebus.app/jdk/* => Skip -# CSS_Phoebus.app/Contents/* => Skip +# Examples: # -# Example: -# phoebus\.app/ - Strip Mac "phoebus.app/" from entries -# so they look more like the Windows example +# - `phoebus\.app/`: Strip Mac "phoebus.app/" from entries +# so they look more like the Windows example # -# phoebus-[^/]+/ - Strip phoebus product name from ZIP entry +# - `phoebus-[^/]+/`: Strip phoebus product name from ZIP entry # -# jdk/.* - Remove complete jdk entry to skip it +# - `jdk/.*`: Remove complete jdk entry to skip it removals=CSS_Phoebus\\.app/Contents/.*,CSS_Phoebus\\.app/,phoebus\\.app/Contents/.*,phoebus\\.app/,phoebus-[^/]+/,product-[^/]+/,jdk/.* diff --git a/core/email/src/main/resources/email_preferences.properties b/core/email/src/main/resources/email_preferences.properties index c34486241c..7e44660053 100644 --- a/core/email/src/main/resources/email_preferences.properties +++ b/core/email/src/main/resources/email_preferences.properties @@ -2,17 +2,20 @@ # Package org.phoebus.email # ------------------------- -# smtp host -# When set to "DISABLE", email support is disabled +# SMTP host. +# +# When set to `DISABLE`, email support is disabled. mailhost=smtp.bnl.gov -# smtp port +# SMTP port. mailport=25 -# User and password for connecting to the mail host, usually left empty +# User for connecting to the mail host, usually left empty username= +# Password for connecting to the mail host, usually left empty password= -# Default address to be used for From: -# if it is left empty then the last used from address is used -from= \ No newline at end of file +# Default address to be used for {mailheader}`From:`. +# +# If left empty then the last used {mailheader}`From` address is used. +from= diff --git a/core/framework/src/main/resources/autocomplete_preferences.properties b/core/framework/src/main/resources/autocomplete_preferences.properties index 799a6902b2..b297d03650 100644 --- a/core/framework/src/main/resources/autocomplete_preferences.properties +++ b/core/framework/src/main/resources/autocomplete_preferences.properties @@ -3,6 +3,7 @@ # ------------------------------------------ # Enable the built-in PV proposal providers? + enable_loc_pv_proposals=true enable_sim_pv_proposals=true enable_sys_pv_proposals=true @@ -10,5 +11,7 @@ enable_pva_pv_proposals=true enable_mqtt_pv_proposals=false enable_formula_proposals=true -# Site-specific proposal providers can be added via PVProposalProvider SPI, +# :::{note} +# Site-specific proposal providers can be added via `PVProposalProvider` SPI, # and disabled by removing the contribution. +# ::: diff --git a/core/framework/src/main/resources/workbench_preferences.properties b/core/framework/src/main/resources/workbench_preferences.properties index 39e800da0b..186810d58d 100644 --- a/core/framework/src/main/resources/workbench_preferences.properties +++ b/core/framework/src/main/resources/workbench_preferences.properties @@ -2,43 +2,62 @@ # Package org.phoebus.framework.workbench # --------------------------------------- -# External applications +# External applications. # # Defines applications to use for specific file extensions # -# Format: +# :::{rubric} Format +# ::: # -# Each definition consists of name, file extensions, command. +# Each definition consists of {samp}`{name}, {file extensions}, {command}`. # -# Name is the name of the definition, used to register the application. -# File extensions is a '|'-separated list of file extensions (not including the 'dot'). -# Command is the path to the command. +# _Name_ is the name of the definition, used to register the application. +# +# _File extensions_ is a `|`-separated list of file extensions (not including the 'dot'). +# +# _Command_ is the path to the command. # The command will be invoked with the full path to the resource as an argument. # -# Each definition must use a key that starts with "external_app_" - -# Examples: +# Each definition must use a key that starts with `external_app_` +# +# :::{rubric} Examples +# ::: +# +# ```{code-block} properties +# :caption: Start 'gedit' for text files +# +# org.phoebus.framework.workbench/external_app_text=Text Editor,txt|dat|py|ini|db|xml|xsl|css|cmd|sh|st|log|out|md|shp,gedit +# ``` # -# Start 'gedit' for text files -# external_app_text=Text Editor,txt|dat|py|ini|db|xml|xsl|css|cmd|sh|st|log|out|md|shp,gedit +# ```{code-block} properties +# :caption: Start 'eog' for images, 'firefox' for PDF files:: # -# Start 'eog' for images, 'firefox' for PDF files -# external_app_image=Image Viewer,png|jpg|gif|jpeg,eog +# org.phoebus.framework.workbench/external_app_image=Image Viewer,png|jpg|gif|jpeg,eog +# ``` # -# Start 'firefox' to view PDFs -# external_app_pdf=PDF Viewer,pdf,firefox +# ```{code-block} properties +# :caption: Start 'firefox' to view PDFs # -# Example for some site-specific tool that opens 'alog' files -# external_app_alog=Alignment Log,alog,/path/to/alog_viewer +# org.phoebus.framework.workbench/external_app_pdf=PDF Viewer,pdf,firefox +# ``` +# +# ```{code-block} properties +# :caption: Example for some site-specific tool that opens 'alog' files +# +# org.phoebus.framework.workbench/external_app_alog=Alignment Log,alog,/path/to/alog_viewer +# ``` # Directory where external applications are started -# May use system properties $(user.home) +# +# May use system properties `$(user.home)`. external_apps_directory=$(user.home) -# Phoebus folder name by default .phoebus -# May use system properties $(phoebus.folder.name.preference) +# Phoebus folder name by default `.phoebus`. +# +# May use system properties `$(phoebus.folder.name.preference)` phoebus_folder_name=$(phoebus.folder.name.preference) -# Phoebus user home directory path name by default $HOME or %USERPROFILE% -# May use system properties $(phoebus.folder.name.preference +# Phoebus user home directory path name by default `$HOME` or `%USERPROFILE%`. +# +# May use system properties `$(phoebus.folder.name.preference)`. phoebus_user=$(phoebus.user) diff --git a/core/logbook/src/main/resources/logbook_preferences.properties b/core/logbook/src/main/resources/logbook_preferences.properties index 75d0744c47..8784458984 100644 --- a/core/logbook/src/main/resources/logbook_preferences.properties +++ b/core/logbook/src/main/resources/logbook_preferences.properties @@ -3,6 +3,7 @@ # ------------------------------ # Site specific log book client implementation name. +# # When empty, logbook submissions are disabled logbook_factory=inmemory @@ -16,4 +17,4 @@ auto_body=true # Determines if a log entry created from context menu (e.g. display or data browser) # should auto generate properties (e.g. "resources.file"). -auto_property=false \ No newline at end of file +auto_property=false diff --git a/core/pv-ca/src/main/resources/pv_ca_preferences.properties b/core/pv-ca/src/main/resources/pv_ca_preferences.properties index aa214cb00a..9287225a0b 100644 --- a/core/pv-ca/src/main/resources/pv_ca_preferences.properties +++ b/core/pv-ca/src/main/resources/pv_ca_preferences.properties @@ -3,17 +3,17 @@ # ------------------------- # By default, we use the following preferences settings, -# but when the System property "jca.use_env" is "true", -# JCA falls back to the EPICS_CA_... environment variables. +# but when the System property `jca.use_env` is `true`, +# JCA falls back to the `EPICS_CA_...` environment variables. # -# Sites that prefer to use the EPICS_CA_... environment variables +# Sites that prefer to use the `EPICS_CA_...` environment variables # thus need to add # -# -Djca.use_env=true +# -Djca.use_env=true # # to their launcher script. -# Channel Access address list +# Channel Access address list. addr_list= auto_addr_list=true @@ -29,20 +29,22 @@ beacon_period=15 connection_timeout=30 # Support variable length arrays? -# auto, true, false +# +# :format: one of `auto`, `true`, `false` variable_length_array=auto # Connect at lower priority for arrays -# with more elements than this threshold +# with more elements than this threshold. large_array_threshold= 100000 -# Is the DBE_PROPERTY subscription supported +# Is the `DBE_PROPERTY` subscription supported # to monitor for changes in units, limits etc? dbe_property_supported=false -# Mask to use for subscriptions -# VALUE, ALARM, ARCHIVE +# Mask to use for subscriptions. +# +# :format: one of `VALUE`, `ALARM`, `ARCHIVE` monitor_mask=VALUE -# Name server list +# Name server list. name_servers= diff --git a/core/pv-jackie/src/main/resources/pv_jackie_preferences.properties b/core/pv-jackie/src/main/resources/pv_jackie_preferences.properties index 4e1c561798..bd06cbdedc 100644 --- a/core/pv-jackie/src/main/resources/pv_jackie_preferences.properties +++ b/core/pv-jackie/src/main/resources/pv_jackie_preferences.properties @@ -4,38 +4,42 @@ # List of servers that shall be queried via UDP when looking for channels. # -# This setting is equivalent to the EPICS_CA_ADDR_LIST environment variable. It -# is only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_ADDR_LIST` environment variable. +# +# It is only used when {prefs:pref}`use_env` is false. ca_address_list= # Shall the broadcast addresses of local interfaces automatically be added to # the list of addresses that shall be used when looking for a channel? # -# This setting is equivalent to the EPICS_CA_AUTO_ADDR_LIST environment -# variable, but expects a value of true or false instead of YES or NO. It is -# only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_AUTO_ADDR_LIST` environment +# variable, but expects a value of `true` or `false` instead of `YES` or `NO`. +# +# It is only used when {prefs:pref}`use_env` is false. # # The default value is true. ca_auto_address_list= -# Shall the size of values transferred via Channel Access be limited (false) or -# not (true)? +# Shall the size of values transferred via Channel Access be limited (`false`) or +# not (`true`)? # # If false, the value of ca_max_array_bytes limits the size of serialized # values that are transferred via Channel Access. # -# This setting is equivalent to the EPICS_CA_AUTO_ARRAY_BYTES environment -# variable, but expects a value of true or false instead of YES or NO. This -# setting is only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_AUTO_ARRAY_BYTES` environment +# variable, but expects a value of `true` or `false` instead of `YES` or `NO`. # -# The default value is true. +# This setting is only used when {prefs:pref}`use_env` is false. +# +# The default value is `true`. ca_auto_array_bytes= # Interval between sending echo packages to a Channel Access server (in # seconds). # -# This setting is equivalent to the EPICS_CA_CONN_TMO environment variable. It -# is only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_CONN_TMO` environment variable. +# +# It is only used when {prefs:pref}`use_env` is false. # # The default value is 30. ca_echo_interval= @@ -43,40 +47,48 @@ ca_echo_interval= # Maximum size (in bytes) of a value that can be transferred via Channel # Access. # -# This setting is equivalent to the EPICS_CA_MAX_ARRAY_BYTES environment -# variable. It is only used when use_env is false. and ca_auto_array_bytes is -# false. +# This setting is equivalent to the `EPICS_CA_MAX_ARRAY_BYTES` environment +# variable. +# +# It is only used when {prefs:pref}`use_env` is `false` +# and {prefs:pref}`ca_auto_array_bytes` is `false`. # # The default value is 16384. ca_max_array_bytes= # Interval of the longest search period (in seconds). # -# This setting is equivalent to the EPICS_CA_MAX_SEARCH_PERIOD environment -# variable. It is only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_MAX_SEARCH_PERIOD` environment +# variable. +# +# It is only used when {prefs:pref}`use_env` is false. # # The default value (and smallest allowed value) is 60. ca_max_search_period= # TTL for UDP packets that are sent to multicast addresses. # -# This setting is equivalent to the EPICS_CA_MCAST_TTL environment variable. It -# is only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_MCAST_TTL` environment variable. +# +# It is only used when {prefs:pref}`use_env` is false. # -# The default value (and smallest allowed value) is 1. The greatest allowed -# value is 255. +# The default value (and smallest allowed value) is 1. +# The greatest allowed value is 255. ca_multicast_ttl= # List of servers that shall be queried via UDP when looking for channels. # -# This setting is equivalent to the EPICS_CA_NAME_SERVERS environment variable. -# It is only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_NAME_SERVERS` environment variable. +# +# It is only used when {prefs:pref}`use_env` is false. ca_name_servers= # UDP port that is used when connecting to the Channel Access repeater. # -# This setting is equivalent to the EPICS_CA_REPEATER_PORT environment -# variable. It is only used when use_env is false. +# This setting is equivalent to the `EPICS_CA_REPEATER_PORT` environment +# variable. +# +# It is only used when {prefs:pref}`use_env` is false. # # The default value is 5065. ca_repeater_port= @@ -84,8 +96,9 @@ ca_repeater_port= # UDP and TCP port on which Channel Access servers are expected to listen. # # This setting is used when sending search requests and when connecting to -# serves that did not explicitly specify a port in search responses. It is -# only used when use_env is false. +# serves that did not explicitly specify a port in search responses. +# +# It is only used when {prefs:pref}`use_env` is false. # # The default value is 5064. ca_server_port= @@ -96,27 +109,30 @@ ca_server_port= charset= # Time that a CID is blocked from being used again in milliseconds. +# # After destroying a channel, the CID may not be reused for some time because # there might still be late responses to old search requests, which would be -# used for the wrong channel if the CID was reused too early. A value of 0 (or -# a negative value) means that CIDs can be reused immediately. +# used for the wrong channel if the CID was reused too early. +# +# A value of 0 (or a negative value) means that CIDs can be reused immediately. cid_block_reuse_time=900000 -# Shall meta-data monitors using DBE_PROPERTY be created? +# Shall meta-data monitors using `DBE_PROPERTY` be created? # # This ensures that the meta-data for PVs is updated when it changes on the -# server, but some servers do not correctly support using DBE_PROPERTY. When +# server, but some servers do not correctly support using `DBE_PROPERTY`. When # experiencing problems with such a server, try setting this to false. dbe_property_supported=true # Shall a precision of zero for a floating-point value result in this value -# being rendered without a fractional digits (true) or shall it be treated as +# being rendered without a fractional digits (`true`) or shall it be treated as # an indication that the value should be rendered with a default number of -# fractional digits (false)? +# fractional digits (`false`)? honor_zero_precision=true -# Hostname that is sent to the Channel Access server. If empty, the system?s -# hostname is determined automatically. +# Hostname that is sent to the Channel Access server. +# +# If empty, the system's hostname is determined automatically. hostname= # How to process write operations specifying a long value that is greater than @@ -133,28 +149,30 @@ long_conversion_mode=COERCE_AND_WARN # Mask that shall be used when registering monitors for DBR_TIME_* values. # -# This can be a combination of DBE_ALARM, DBE_ARCHIVE, DBE_PROPERTY, and -# DBE_VALUE, where multiple flags can be combined using the ?|? character. +# :format: +# a combination of `DBE_ALARM`, `DBE_ARCHIVE`, `DBE_PROPERTY`, and +# `DBE_VALUE`, separated by `|`. monitor_mask=DBE_VALUE|DBE_ALARM -# Shall PVs referencing a record?s RTYP field be treated like any other PV -# (false) or shall the monitor registered for the channel request the value -# only, without any meta-data like a time-stamp (true)? +# Shall PVs referencing a record's `RTYP` field be treated like any other PV +# (`false`) or shall the monitor registered for the channel request the value +# only, without any meta-data like a time-stamp (`true`)? # # In general, setting this to false is preferred, but there are certain -# versions of EPICS where requesting a DBR_TIME_STRING for the RTYP field +# versions of EPICS where requesting a `DBR_TIME_STRING` for the `RTYP` field # results in invalid data being returned by the server. In this case, this -# setting should be changed to true. +# setting should be changed to `true`. rtyp_value_only=false -# Shall Channel Access client settings be read from the CA_* environment +# Shall Channel Access client settings be read from the `CA_*` environment # variables? # -# If true, the ca_* settings from the preferences are ignored and the values -# from the process?s environment are used instead. If false, the preferences +# If true, the `ca_*` settings from the preferences are ignored and the values +# from the process's environment are used instead. If `false`, the preferences # are used and the environment variables are ignored. use_env=true -# Username that is sent to the Channel Access server. If empty, the username -# for the current process is determined automatically. +# Username that is sent to the Channel Access server. +# +# If empty, the username for the current process is determined automatically. username= diff --git a/core/pv-mqtt/src/main/resources/pv_mqtt_preferences.properties b/core/pv-mqtt/src/main/resources/pv_mqtt_preferences.properties index 26eb783884..d96b9cfc82 100644 --- a/core/pv-mqtt/src/main/resources/pv_mqtt_preferences.properties +++ b/core/pv-mqtt/src/main/resources/pv_mqtt_preferences.properties @@ -2,6 +2,7 @@ # Package org.phoebus.pv.mqtt # --------------------------- -# MQTT Broker -# All "mqtt://some/tag" PVs will use this broker -mqtt_broker=tcp://localhost:1883 \ No newline at end of file +# MQTT Broker. +# +# All `mqtt://some/tag` PVs will use this broker. +mqtt_broker=tcp://localhost:1883 diff --git a/core/pv-pva/src/main/resources/pv_pva_preferences.properties b/core/pv-pva/src/main/resources/pv_pva_preferences.properties index 5a62ac2f95..41f763cc89 100644 --- a/core/pv-pva/src/main/resources/pv_pva_preferences.properties +++ b/core/pv-pva/src/main/resources/pv_pva_preferences.properties @@ -1,55 +1,63 @@ -# ------------------------- +# -------------------------- # Package org.phoebus.pv.pva -# ------------------------- +# -------------------------- + # By default, these preference settings are empty, # and the PVA library will then honor the commonly used -# environment variables like EPICS_PVA_ADDR_LIST, -# EPICS_PVA_AUTO_ADDR_LIST etc. +# environment variables like `EPICS_PVA_ADDR_LIST`, +# `EPICS_PVA_AUTO_ADDR_LIST` etc. +# # Defining preference values will override the environment # variables which allows consolidating PVA settings # with all the CS-Studio preference settings. # -# # Network clients typically need to configure the first # three settings to successfully connect to PVA servers # on the local network. -# PVAccess address list -epics_pva_addr_list +# PVAccess address list; +epics_pva_addr_list= -# PVAccess auto address list - true/false -epics_pva_auto_addr_list +# PVAccess auto address list. +# +# :format: `true` or `false` +epics_pva_auto_addr_list= -# Name servers used for TCP name resolution -epics_pva_name_servers +# Name servers used for TCP name resolution. +epics_pva_name_servers= +# :::{caution} # The following parameters should best be left # at their default. # -# For details, see PVASettings in PV Access library. +# For details, see `PVASettings` in PV Access library. +# ::: -# Port used for UDP name searches and beacons -epics_pva_broadcast_port +# Port used for UDP name searches and beacons. +epics_pva_broadcast_port= -# PV server's first TCP port -epics_pva_server_port +# PV server's first TCP port. +epics_pva_server_port= -# Connection timeout in seconds -epics_pva_conn_tmo +# Connection timeout in seconds. +epics_pva_conn_tmo= -# TCP socket creation timeout in seconds -epics_pva_tcp_socket_tmo +# TCP socket creation timeout in seconds. +epics_pva_tcp_socket_tmo= -# Maximum number of array elements shown when printing data -epics_pva_max_array_formatting +# Maximum number of array elements shown when printing data. +epics_pva_max_array_formatting= -# TCP buffer size for sending data -epics_pva_send_buffer_size +# TCP buffer size for sending data. +epics_pva_send_buffer_size= # Timeout used by plain "put" type of write # when checking success or failure. -# Note this is not used with asyncWrite, +# +# :::{note} +# This is not used with `asyncWrite`, # the "put-callback" which returns a Future # for awaiting the completion, -# but only with the plain "put" that returns ASAP -epics_pva_write_reply_timeout_ms=1000 \ No newline at end of file +# but only with the plain "put" that returns ASAP. +# ::: +epics_pva_write_reply_timeout_ms=1000 diff --git a/core/pv/doc/index.rst b/core/pv/doc/index.rst index e1cf9197ae..9b58320969 100644 --- a/core/pv/doc/index.rst +++ b/core/pv/doc/index.rst @@ -1,4 +1,3 @@ - Process Variables ================= @@ -20,11 +19,9 @@ Examples:: ca://SomePVName SomeMotor.RBV -Channel Access settings are configured via :ref:`preference_settings`, most important:: - - # Channel Access address list - org.phoebus.pv.ca/addr_list=... - +Channel Access settings are configured via settings +under the :prefs:pack:`org.phoebus.pv.ca` package, +such as :prefs:pref:`org.phoebus.pv.ca/addr_list`. PV Access --------- diff --git a/core/pv/src/main/resources/pv_formula_preferences.properties b/core/pv/src/main/resources/pv_formula_preferences.properties index db932342d3..1352c8d140 100644 --- a/core/pv/src/main/resources/pv_formula_preferences.properties +++ b/core/pv/src/main/resources/pv_formula_preferences.properties @@ -2,5 +2,5 @@ # Package org.phoebus.pv.formula # ------------------------------ -# Update throttle for input PVs +# Update throttle for input PVs. throttle_ms=500 diff --git a/core/pv/src/main/resources/pv_preferences.properties b/core/pv/src/main/resources/pv_preferences.properties index 3e39e95cea..56aabe3a56 100644 --- a/core/pv/src/main/resources/pv_preferences.properties +++ b/core/pv/src/main/resources/pv_preferences.properties @@ -2,6 +2,6 @@ # Package org.phoebus.pv # ---------------------- -# Default PV Type +# Default PV Type. default=ca diff --git a/core/security/src/main/resources/phoebus_security_preferences.properties b/core/security/src/main/resources/phoebus_security_preferences.properties index cad1248fef..226f2aab01 100644 --- a/core/security/src/main/resources/phoebus_security_preferences.properties +++ b/core/security/src/main/resources/phoebus_security_preferences.properties @@ -4,26 +4,22 @@ # Authorization file # -# If left empty, the built-in core/security/authorization.conf is used. +# If left empty, the built-in `core/security/authorization.conf` is used. # -# When specifying a plain file name like "authorization.conf", -# the install location (Locations.install()) is searched for that file name. +# When specifying a plain file name like `authorization.conf`, +# the install location (`Locations.install()`) is searched for that file name. # -# The file name can also be an absolute path like /some/path/auth.conf. +# The file name can also be an absolute path like `/some/path/auth.conf`. # -# Finally, the file name may use a system property like $(auth_file) +# Finally, the file name may use a system property like `$(auth_file)` # which in turn could be set to either BUILTIN, a file in the install location, # or an absolute path. # # When set to an invalid file, the user will have no authorizations at all. - -# Use built-in core/security/authorization.conf authorization_file= -# Use authorization.conf in the install location -#authorization_file=authorization.conf - # Secure store underlying implementation. -# Can be 'FILE' or 'IN_MEMORY' +# +# :format: one of `FILE` or `IN_MEMORY` secure_store_target=FILE diff --git a/core/ui/src/main/resources/phoebus_ui_preferences.properties b/core/ui/src/main/resources/phoebus_ui_preferences.properties index 1802bd12e0..c2de97ebeb 100644 --- a/core/ui/src/main/resources/phoebus_ui_preferences.properties +++ b/core/ui/src/main/resources/phoebus_ui_preferences.properties @@ -3,16 +3,22 @@ # ---------------------- # Show the splash screen? -# Can also be set via '-splash' resp. '-nosplash' command line options +# +# Can also be set via `-splash` resp. `-nosplash` command line options. splash=true -# 'Welcome' URL +# 'Welcome' URL. # # When left empty, the built-in welcome.html resource is used. +# # Site-specific products can set this to their desired URL, # which may include Java system properties to bundle content -# with the product, for example -# file:$(phoebus.install)/welcome_to_hawkins_labs.html +# with the product, for example: +# +# ```{code-block} properties +# +# org.phoebus.ui/welcome=file:$(phoebus.install)/welcome_to_hawkins_labs.html +# ``` welcome= # Default applications @@ -20,118 +26,208 @@ welcome= # When there are multiple applications that handle # a resource, the setting determines the one used by default. # -# Format is comma-separated list with sub-text of default application names. -# For example, "run, exe" would pick "display_runtime" over "display_editor", -# and "foo_executor" over "foo_creator". -# The patterns "edit, creat" would inversely open the editor-type apps. +# :format: comma-separated list with sub-text of default application names. # -# This makes the display_runtime and the 3d_viewer default apps, -# using display_editor and a potentially configured text editor for *.shp files secondary +# For example, `run, exe` would pick `display_runtime` over `display_editor`, +# and `foo_executor` over `foo_creator`. +# +# The patterns `edit, creat` would inversely open the editor-type apps. +# +# This makes the `display_runtime` and the `3d_viewer` default apps, +# using `display_editor` and a potentially configured text editor for {file}`{name}.shp` files secondary. default_apps=run,3d,convert_edm -# Hide SPI-provided menu entries -# Comma-separated list of class names +# Hide SPI-provided menu entries. +# +# :format: comma-separated list of class names. hide_spi_menu=org.phoebus.ui.monitoring.FreezeUI # Top resources to show in "File" menu and toolbar # -# Format: -# uri1 | uri2,Display name 2 | uri3,Display name 3 +# :format: {samp}`{uri1} | {uri2},{Display name 2} | {uri3},{Display name 3}` top_resources=examples:/01_main.bob?app=display_runtime,Example Display | pv://?sim://sine&app=probe,Probe Example | pv://?sim://sine&loc://x(10)&app=pv_table,PV Table Example | http://www.google.com?app=web, Google -# Home display file. "Home display" button will navigate to this display. +# Home display file. +# +# "Home display" button will navigate to this display. home_display=examples:/01_main.bob?app=display_runtime,Example Display -# Toolbar entries +# Toolbar entries. # # Apps like the file browser contribute a toolbar entry. # This setting can control which toolbar entries are shown # and for the most part also in which order. # -# Format: Comma-separated list of entries. +# :format: Comma-separated list of entries. # -# The special entry "*" adds all remaining available toolbar entries. -# An entry starting with "!" removes that item from the available entries. -# The order of the initial buttons "Home, Top Resources, Layouts, Add Layouts" -# cannot be changed, but they can be suppressed by adding "!", -# for example "Home, !Top Resources, !Layouts, !Add Layouts". +# The special entry `*` adds all remaining available toolbar entries. +# An entry starting with `!` removes that item from the available entries. +# The order of the initial buttons `Home, Top Resources, Layouts, Add Layouts` +# cannot be changed, but they can be suppressed by adding `!`, +# for example `Home, !Top Resources, !Layouts, !Add Layouts`. # -# The special entry "Add Layouts" is NOT added to the toolbar by default. It -# can be added to the toolbar by specifying "Add Layouts". +# The special entry `Add Layouts` is NOT added to the toolbar by default. It +# can be added to the toolbar by specifying `Add Layouts`. # # The strings in the list of entries MUST match what is returned from -# ToolbarEntry#getId(). This allows for customization/localization of app name +# `ToolbarEntry#getId()`. This allows for customization/localization of app name # without the need to adjust the list. # -# Examples: +# :::{rubric} Examples +# ::: # -# Default buttons, then all remaining available items: +# ```{code-block} properties +# :caption: Default buttons, then all remaining available items # -# Home, Top Resources, Layouts, * +# Home, Top Resources, Layouts, * +# ``` # -# Default buttons, then assert that File Browser comes next: +# ```{code-block} properties +# :caption: Default buttons, then assert that File Browser comes next # -# Home, Top Resources, Layouts, File Browser, * +# Home, Top Resources, Layouts, File Browser, * +# ``` # -# Only Home and File Browser: +# ```{code-block} properties +# :caption: Only Home and File Browser: # -# Home, !Top Resources, !Layouts, File Browser +# Home, !Top Resources, !Layouts, File Browser +# ``` toolbar_entries=Home, Top Resources, Layouts, File Browser, * # How many array elements to show when formatting as text? max_array_formatting=256 -# UI Responsiveness Monitor Period -# Period between tests [millisec], -# i.e. the minimum detected UI freeze duration -# Set to 0 to disable +# UI Responsiveness Monitor Period. +# +# Period between tests in milliseconds, +# i.e. the minimum detected UI freeze duration. +# +# Set to 0 to disable. ui_monitor_period=500 # Show user ID in status bar? status_show_user=true -# Set default save path +# Set default save path. default_save_path= -# Set the path to a folder with default layouts +# Set the path to a folder with default layouts. layout_dir= -# Set default layout at start absolutepath +# Set default layout at start absolutepath. layout_default= -# If enable layout are saved in layout_dir instead of default user location +# If enable layout are saved in `layout_dir` instead of default user location. save_layout_in_layout_dir=false # Compute print scaling in 'landscape' mode? +# # Landscape mode is generally most suited for printouts # of displays or plots, because the monitor tends to be 'wide'. +# # At least on Mac OS X, however, the printing always appears to use # portrait mode, so print layouts computed in landscape mode # get cropped. +# # Details can also depend on the printer driver. print_landscape=true -# Color for text and the background for 'OK' alarm severity (R,G,B or R,G,B,A values in range 0..255) +# When Picture- and/or Symbol widgets are present in an OPI, +# zooming in under Windows using the D3D graphics library can +# cause excessive VRAM usage. Setting a cache hint can work as +# a workaround. Since it has been observed that the cache hints +# also can cause graphical errors, the setting of a cache hint +# is a configurable option, which must explicitly be set to +# have effect. +# +# The setting defaults to the default caching behavior. +# +# :format: +# one of: +# +# The empty string or `NONE` +# : The default caching behavior: caching is DISABLED, +# and the cache hint is set to `CacheHint.DEFAULT`. +# +# `DEFAULT` +# : Caching is ENABLED, and the cache hint is set to `CacheHint.DEFAULT`. +# +# `SPEED` +# : Based on very limited testing, +# this option seems to work the best as a workaround for the excessive VRAM usage. +# +# `SCALE` +# : This option has been observed to cause graphical errors on several systems: +# rotated widgets have been observed to be translated instead of rotated. +# +# or `QUALITY`, `ROTATE`, `SCALE_AND_ROTATE`. +# +# If an invalid option is entered, a warning is logged, and the +# default caching behavior is used (i.e., caching is DISABLED, +# and the cache hint is set to `CacheHint.DEFAULT`). +cache_hint_for_picture_and_symbol_widgets= + + +# Whether or not to save user credentials to file or memory so they only have to be entered once. +# +# :::{note} +# This applies to all scopes/applications prompting for credentials. +# ::: +# +# :::{seealso} +# The preference {prefs:pref}`org.phoebus.security/secure_store_target` +# ::: +save_credentials=false + +# Location of the Phoebus documentation +documentation_location= + +# How to format the window title. +# The string is formatted with the current active tab as argument. +# The default is `CS-Studio: %s`, where `%s` is replaced by the name of the active tab. +# +# Setting it to just `%s` will show only the active tab. +# Omitting the %s will always show a static title. +# When there is no active tab, the {prefs:pref}`default_window_title` is used instead. +window_title_format=CS-Studio: %s + +# The window title when no active tab is open. +default_window_title=CS-Studio + +# :::{rubric} Colors +# ::: +# +# Colors are of the format `R,G,B` or `R,G,B,A` values in range 0..255 + +# Color of the text for 'OK' alarm severity. ok_severity_text_color=0,255,0 +# Color of the background for 'OK' alarm severity. ok_severity_background_color=255,255,255 -# Color for text and the background for 'MINOR' alarm severity +# Color of the text for 'MINOR' alarm severity minor_severity_text_color=255,128,0 +# Color of the background for 'MINOR' alarm severity minor_severity_background_color=255,255,255 -# Color for text and the background for 'MAJOR' alarm severity +# Color of the text for 'MAJOR' alarm severity major_severity_text_color=255,0,0 +# Color of the background for 'MAJOR' alarm severity major_severity_background_color=255,255,255 -# Color for text and the background for 'INVALID' alarm severity +# Color of the text for 'INVALID' alarm severity invalid_severity_text_color=255,0,255 +# Color of the background for 'INVALID' alarm severity invalid_severity_background_color=255,255,255 -# Color for text and the background for 'UNDEFINED' alarm severity +# Color of text for 'UNDEFINED' alarm severity undefined_severity_text_color=200,0,200,200 +# Color of background for 'UNDEFINED' alarm severity undefined_severity_background_color=255,255,255 -# Color Configuration for the application "Alarm Area Panel" (R,G,B or R,G,B,A values in range 0..255): +# :::{rubric} Color Configuration for the application "Alarm Area Panel" +# ::: + alarm_area_panel_ok_severity_text_color=255,255,255 alarm_area_panel_ok_severity_background_color=0,255,0 @@ -193,4 +289,4 @@ default_window_title=CS-Studio # default stylings.Set the full path to the .css file # For a system file use syntax; 'file:' # For a file served over http use syntax: 'http://' -custom_css_styling= \ No newline at end of file +custom_css_styling= diff --git a/docs/source/conf.py b/docs/source/conf.py index b36edb2fd4..600ab1a195 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -30,6 +30,7 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ + "myst_parser", "preferences_listing", ] @@ -187,6 +188,22 @@ def find_phoebus_version() -> str: htmlhelp_basename = 'Phoebusdoc' +# -- Options for MyST's markdown ----------------------------------------------- +# https://myst-parser.readthedocs.io/en/latest/configuration.html + +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_image", + "replacements", + "smartquotes", + "strikethrough", + "tasklist", +] + # -- Options for LaTeX output -------------------------------------------------- latex_elements = { diff --git a/docs/source/preference_properties.md b/docs/source/preference_properties.md new file mode 100644 index 0000000000..51d4adf42e --- /dev/null +++ b/docs/source/preference_properties.md @@ -0,0 +1,16 @@ +(preference_settings)= +# Preferences Listing + +The following preference settings are available for the various application features. +To use them in your settings file, remember to prefix each setting with the package name. + +For example, +for the `drop_failed_archives` preference in the `trends.databrowser3` section +(package name `org.csstudio.trends.databrowser3`) add a line like: + +```properties +org.csstudio.trends.databrowser3/drop_failed_archives=true +``` + +```{prefs:listing} +``` diff --git a/docs/source/preference_properties.rst b/docs/source/preference_properties.rst deleted file mode 100644 index 8c7116a516..0000000000 --- a/docs/source/preference_properties.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _preference_settings: - -Preferences Listing -=================== - -The following preference settings are available for the various application features. -To use them in your settings file, remember to prefix each setting with the package name. - -eg. for the 'drop_failed_archives' preference in the 'trends.databrowser3' section -(package name 'org.csstudio.trends.databrowser3') add a line like: :: - - org.csstudio.trends.databrowser3/drop_failed_archives=true - - -.. prefs:listing:: diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt index fd8d5ba08f..e654ebd0b1 100644 --- a/docs/source/requirements.txt +++ b/docs/source/requirements.txt @@ -1,2 +1,3 @@ sphinx==8.2.3 sphinx_rtd_theme==3.0.2 +myst-parser==4.0.1 diff --git a/services/archive-engine/doc/index.rst b/services/archive-engine/doc/index.rst index 9d4348ad7a..5dfac510f9 100644 --- a/services/archive-engine/doc/index.rst +++ b/services/archive-engine/doc/index.rst @@ -146,6 +146,10 @@ change these settings in your :ref:`preference_settings` :: org.phoebus.archive.reader.rdb/user=report org.phoebus.archive.reader.rdb/password=$report +See the :prefs:pack:`org.csstudio.trends.databrowser3` +and :prefs:pack:`org.phoebus.archive.reader.rdb` preferences +for more information. + The ``MySQL.dbd`` used to install the archive tables adds a few demo samples for ``sim://sine(0, 10, 50, 0.1)`` around 2004-01-10 13:01, so you can simply add that channel to a Data Browser and find data at that time. @@ -221,9 +225,8 @@ To start the archive engine for a configuration:: The engine name ('Demo') needs to match a previously imported configuration name, and the port number (4812) needs to match the port number used when importing the configuration. -The settings (my_settings.ini) typically contain the EPICS CA address list settings -as well as archive engine configuration details, see archive engine settings -in :ref:`preference_settings`. +The settings (``my_settings.ini``) typically contain the EPICS CA address list settings +as well as archive engine configuration details, see the :prefs:pack:`org.csstudio.archive` settings. In a production setup, the archive engine is best run under ``procServ`` (https://github.com/ralphlange/procServ). diff --git a/services/archive-engine/src/main/resources/archive_preferences.properties b/services/archive-engine/src/main/resources/archive_preferences.properties index 8d255c10bf..46c45ebc5d 100644 --- a/services/archive-engine/src/main/resources/archive_preferences.properties +++ b/services/archive-engine/src/main/resources/archive_preferences.properties @@ -4,128 +4,149 @@ # RDB URL for archived data # -# Oracle example -# url=jdbc:oracle:thin:user/password@//172.31.73.122:1521/prod +# ```{code-block} properties +# :caption: Oracle example: # -# PostgreSQL example -# url=jdbc:postgresql://localhost/archive +# org.csstudio.archive/url=jdbc:oracle:thin:user/password@//172.31.73.122:1521/prod +# ``` # -# MySQL example +# ```{code-block} properties +# :caption: PostgreSQL example: +# +# org.csstudio.archive/url=jdbc:postgresql://localhost/archive +# ``` +# +# The default value is a MySQL example url=jdbc:mysql://localhost/archive?rewriteBatchedStatements=true -# RDB user and password +# RDB user and password. +# # Some applications also provide command-line option to override. user=archive +# RDB password. +# +# Some applications also provide command-line option to override. password=$archive # Schema name. Used with an added "." as prefix for table names. # For now this is only used with Oracle URLs and ignored for MySQL schema= -# Timeout [seconds] for certain SQL queries +# Timeout in seconds for certain SQL queries +# # Fundamentally, the SQL queries for data take as long as they take # and any artificial timeout just breaks queries that would otherwise # have returned OK few seconds after the timeout. +# # We've seen Oracle lockups, though, that caused JDBC to hang forever # because the SAMPLE table was locked. No error/exception, just hanging. +# # A timeout is used for operations other than getting the actual data, # for example the channel id-by-name query which _should_ return within # a shot time, to catch that type of RDB lockup. -# timeout_secs=120 -# With PostgreSQL, the setQueryTimeout API is not implemented, +# +# org.csstudio.archive/timeout_secs=120 +# +# With PostgreSQL, the `setQueryTimeout` API is not implemented, # and calling it results in an exception. -# Setting the timeout to 0 disables calls to setQueryTimeout. +# Setting the timeout to 0 disables calls to `setQueryTimeout`. timeout_secs=0 # Use a blob to read/write array samples? # -# The original SAMPLE table did not contain an ARRAY_VAL column -# for the array blob data, but instead used a separate ARRAY_VAL table. -# When running against an old database, this parameter must be set to false. +# The original `SAMPLE` table did not contain an `ARRAY_VAL` column +# for the array blob data, but instead used a separate `ARRAY_VAL` table. +# +# When running against an old database, this parameter must be set to `false`. use_array_blob=true # Name of sample table for writing write_sample_table=sample -# Maximum length of text samples written to SAMPLE.STR_VAL +# Maximum length of text samples written to `SAMPLE.STR_VAL` max_text_sample_length=80 # Use postgres copy instead of insert use_postgres_copy=false -# Channel names use a prefix ca://, pva://, loc://, ... +# Channel names use a prefix `ca://`, `pva://`, `loc://`, ... # to select the type of PV or network protocol. # The preference setting # -# org.phoebus.pv/default=ca +# org.phoebus.pv/default=ca # # determines the default type when no prefix is provided. # # With EPICS IOCs from release 7 on, the PVs -# "xxx", "ca://xxx" and "pva://xxx" all refer -# to the same record "xxx" on the IOC. +# `xxx`, `ca://xxx` and `pva://xxx` all refer +# to the same record `xxx` on the IOC. # # The archive configuration stores the PV name as given. # It is used as such when connecting to the live data source, -# resulting in "ca://.." or "pva://.." connections as requested. +# resulting in `ca://..` or `pva://..` connections as requested. # Samples are written to the archive under that channel name. # # This archive engine preference setting establishes one or more prefixes # as equal when importing an engine configuration. # For example, assume # -# equivalent_pv_prefixes=ca, pva +# org.csstudio.archive/equivalent_pv_prefixes=ca, pva # -# When adding a PV "pva://xxx" to the configuration, -# we check if the archive already contains a channel "xxx", "ca://xxx" or "pva://xxx". -# If any of them are found, the `-import` will consider "pva://xxx" as a duplicate. +# When adding a PV `pva://xxx` to the configuration, +# we check if the archive already contains a channel `xxx`, `ca://xxx` or `pva://xxx`. +# If any of them are found, the `-import` will consider `pva://xxx` as a duplicate. # -# When importing a PV "pva://xxx" into a sample engine configuration that already -# contains the channel "ca://xxx" or "xxx", the channel will be renamed, -# so that engine will from now on use "pva://xxx". +# When importing a PV `pva://xxx` into a sample engine configuration that already +# contains the channel `ca://xxx` or `xxx`, the channel will be renamed, +# so that engine will from now on use `pva://xxx`. # -# When importing a PV "pva://xxx" into a configuration that already -# contains a different engine setup with the channel "ca://xxx" or "xxx", -# the channel will by default rename unchanged, so "ca://xxx" or "xxx" -# will remain in their original engine setup, "pva://xxx" will be skipped. +# When importing a PV `pva://xxx` into a configuration that already +# contains a different engine setup with the channel `ca://xxx` or `xxx`, +# the channel will by default rename unchanged, so `ca://xxx` or `xxx` +# will remain in their original engine setup, `pva://xxx` will be skipped. # # When using `-import` with the additional `-steal_channels` option, -# the existing "...xxx" channel will be renamed to "pva://xxx" and moved +# the existing `...xxx` channel will be renamed to `pva://xxx` and moved # to the imported engine configuration. # # When `equivalent_pv_prefixes` is empty, # any PV name is used as is without looking for equivalent names. -# So "xxx", "ca://xxx" and "pva://xxx" can then all be imported +# So `xxx`, `ca://xxx` and `pva://xxx` can then all be imported # as separate channels, which is likely wrong because it would simply # store data from the same underlying record more than once. # # This default should be the most practical setting when adding -# EPICS 7 IOCs and starting to transition towards "pva://..". -# Existing "xxx" or "ca://xxx" channels can thus be renamed -# to "pva://xxx" while retaining their sample history. +# EPICS 7 IOCs and starting to transition towards `pva://..`. +# Existing `xxx` or `ca://xxx` channels can thus be renamed +# to `pva://xxx` while retaining their sample history. # # Note that the data browser has a similar `equivalent_pv_prefixes` # setting to search for a channel name in several variants. equivalent_pv_prefixes=ca, pva -# Seconds between log messages for Not-a-Number, futuristic, back-in-time values, buffer overruns -# 24h = 24*60*60 = 86400 +# Seconds between log messages for Not-a-Number, futuristic, back-in-time values. +# +# {math}`24h = 24*60*60 = 86400` log_trouble_samples=86400 + +# Seconds between log messages buffer overruns. +# +# {math}`24h = 24*60*60 = 86400` log_overrun=86400 -# Write period in seconds +# Write period in seconds. write_period=30 -# Maximum number of repeat counts for scanned channels +# Maximum number of repeat counts for scanned channels. max_repeats=60 -# Write batch size +# Write batch size. batch_size=500 -# Buffer reserve (N times what's ideally needed) +# Buffer reserve (*N* times what's ideally needed). buffer_reserve=2.0 # Samples with time stamps this far ahead of the local time # are ignored -# 24*60*60 = 86400 = 1 day +# {math}`24h = 24*60*60 = 86400` ignored_future=86400