# STYLE GUIDE TO DOCUMENT NODE STRUCTURES # The node documentation in YAML serves two purposes. # a. As human readable documentation in source code. # b. As a data structure to build other data structures by following the # DRY (Don't Repeat Yourself) principle. This means that every relevant # node information such as name, label, type, default value, min/max # values, descriptions, etc. should be defined here. # Any information required in a different format should be created # from these documents via a build process. # YAML RESOURCES # YAML cheat sheet http://www.yaml.org/refcard.html # Easy to read YAML cookbook http://www.yaml.org/YAML_for_ruby.html # Official YAML site http://www.yaml.org/ # Wikipedia http://en.wikipedia.org/wiki/YAML # LAYOUT # Set right margin to 80 columns # Tabs are not allowed in YAML! # Use 2 spaces for indentation. # Keep all text blocks in the infos node between column 25 and 80. # STRINGS AND BLOCK LITERALS # Strings do not require quotation unless they contain a YAML indicator. # In particular, the comma, colon, pound sign, brackets and curly braces must # be used carefully. # If in doubt about YAML indicators in a string use single-quoted # or double-quoted strings. # http://www.yaml.org/YAML_for_ruby.html#single-quoted_strings # http://www.yaml.org/YAML_for_ruby.html#double-quoted_strings # # For text blocks use the greater than ">" symbol to indicate "Newlines folded". # This converts all new lines to spaces and empty lines to newline. The # greater than ">" symbol is used often in multi-line comments which contain # a YAML indicator. # NODE DOCUMENTATION STRUCTURE # with sample values --- file: profiles/$profile_node_name.cfg # The file path and name of a configuration file relative to the # LogAnalysisInfo directory. # Referenced node descriptions, the once referred from another # file, don't need the file key. node: profiles.$profile_node_name # The node path in dot notation as used in Salang code. Variable # file names and node names should start with the $ character, infos_node: profile # The node path used in node documentation up to the node which # is specified in the structure. This node is also the path # to all nodes described in infos, except of the first infos item # which may describe the infos node itself. # The infos_node path should also be used as file name for the # YAML node description. structure: # The structure starts with the node specified in infos_node. If the path # contains more than one node (i.e. profiles.profile.statistics) then the # last node (statistics) is used as root node in structure. profile: label: string database: fields: node-list # Defined in different file cross_reference_groups: node-list # Defined in different file version: created_in_version: string # Structure outlines the node structure. # Subnodes can be omitted, respectively they can be defined in different # files. # The type of the node is given in the value for nodes without subnodes, # respectively if subnodes are specified in another file. # The type "node" is usually not specified because it is visible in # the given structure. # The type "node-list" or "array" is specified as key/value of the parent # node as follows: # some_parent_node: # _: node-list # label: string # count: int # Valid types are: # string # bytes TODO - revise if we should use bytes as type! # charset TODO - revise if we should use charset as type! # permissions TODO - revise if we should use permissions as type! # bool # int # float # node # node-list # array # NODE, NODE_LIST AND ARRAY # node # A node with known subnodes, respectively a fixed number of subnodes, the # order of subnodes doens't matter. This data structure is similar # to a dictionary in Python and object in Javascript. # The type "node" doesn't need to be specified in the structure because # it obvious. # node-list # This is a node with multiple subnodes of the same kind of an item/object # where the order of subnodes matters as in an array (sometimes the order # doesn't matter but we don't want to specify another unordered-node-list). # Each item in the list is accessed by a node/key, the node_name. # Nodes of type node-list are i.e. log fields, database fields, # report fields, reports, columns, schedule, schedule actions, etc. # array # An indexed array. This is similar to a list as in Python or array in # Javascript. infos: # infos is an array of nodes with node details. Each node can be # described with the following keys: - node: version.created_in_version # The node or node path relative to the infos_node # path. label: # Will be added from language modules later. removed: true # removed means that the option no longer works, # is not functional. version_removed: 8.7.1 # The version number in which the option has # been removed. deprecated: true # Something which is deprecated may still work, it is # functional. Features are deprecated—rather than # immediately removed—in order to provide backward # compatibility, and give programmers who have used the # feature time to bring their code into compliance with # the new standard. version_deprecated: 8.7.0 # The version number in which the option has been # deprecated. value: The version number # Description of the value. values: [hello world, foo, bar] # An array of values. Use this style if values fit # in single line. # Note, values(2) and values(3) are alternative # specifications for the same values. values(2): # Values defined as multi line array. Use this style # if values don't fit in a single line. - hello world - foo - bar values(3): # An array of objects with values and comments. # Use this style if one or more values require # a comment. - value: hello world comment: Some comment for hello world ... - value: foo comment: Some comment for foo ... - value: bar comment: Some comment for bar ... default_value: # Default value if appropriate. min_value: # Min value, will be added from option_info later. max_value: # Max value, will be added from option_info later. required_if: # Required or optionally required comments, description # or condition. If required_if key is omitted then we # assume that the node is always required. comment: # A Comment/description intended for developers. short_description: # Short description, intended for users. Will be added # from language modules later. description: # Main description, intended for users. Will be added # from language modules later. shortcut: # Command line option shortcut. will be added from # option_info later. change_log: # A log of changes of the given node. Uses sequence # which starts with a date in ISO8601 order. - 2014-02-10 -- Added - 2014-02-15 -- Some changes ... with a comment over multiple lines - 2014-03-10 -- Removed, option is no longer required. - 2014-03-17 -- Re-added version_added: 8.7.3 # The version where the node has been added. defined_in_file: # File name where subnodes/keys of the given node are # defined. is_infos_root: true # This is the root node as specified in infos_node. # This is required because all nodes are specified # relative to infos_node. ...