cfdoc_macros.py: Switch to new hugo-like syntax for CFEngine_ macros

README.md

@@ -325,7 +325,7 @@ The documentation generator will pre-process the markdown content
 before passing it to Hugo for the rendering. The pre-processor
 understands and replaces the macros. Macros all have the form
 
-`[%CFEngine_MACRO(parameters)%]`
+`{{< CFEngine_MACRO(parameters) >}}`
 
 and need to be used as a separate line, as the entire line will be
 replaced by the pre-processor.
@@ -346,11 +346,11 @@ are skipped.
 The generator searches for `filename` in the `core/examples`
 subdirectory of WKRDIR.
 
-- `[%CFEngine_include_example(filename)%]`
+- `{{< CFEngine_include_example(filename) >}}`
 
 Injects the code from `filename`.
 
-- `[%CFEngine_include_snippet(filename, begin_rx, end_rx [optional])%]`
+- `{{< CFEngine_include_snippet(filename, begin_rx, end_rx [optional]) >}}`
 
 Searches `filename` for the first line that matches the regular
 expression `begin_rx`, and injects all lines as a code block from
@@ -360,7 +360,7 @@ omitted, all lines until the end of the file will be injected.
 If the line that matches the regular expression is a comment, then
 it is excluded from the quote, otherwise it is included.
 
-- `[%CFEngine_include_markdown(filename, begin_rx, end_rx [optional])%]`
+- `{{< CFEngine_include_markdown(filename, begin_rx, end_rx [optional]) >}}`
 
 Searches `filename` for the first line that matches the regular
 expression `begin_rx`, and injects all lines **verbatim** from there
@@ -369,7 +369,7 @@ all lines until the end of the file will be injected.
 
 #### Documenting policy libraries
 
-- `[%CFEngine_library_include(filename)%]`
+- `{{< CFEngine_library_include(filename) >}}`
 
 Parses the JSON version of the CFEngine policy in `filename` and generates
 documentation from it.
@@ -411,7 +411,7 @@ The following macros require the syntax map to be generated
 via `cf-promises -s` into a file `syntax_map.json` within the
 `_generated` subdirectory of the documentation generator.
 
-- `[%CFEngine_function_prototype(arg1, arg2, ...)%]`
+- `{{< CFEngine_function_prototype(arg1, arg2, ...) >}}`
 
 Renders the prototype of the function that has the same name as the
 title of the current page. Parameters `arg1` etc are used for the names
@@ -426,7 +426,7 @@ of the parameters:
 Use this before a `**Description:**` section in which the behavior of the
 function as well as the individual parameters are then explained.
 
-- `[%CFEngine_function_attributes(arg1, arg2, ...)%]`
+- `{{< CFEngine_function_attributes(arg1, arg2, ...) >}}`
 
 Renders a list of attributes for the function that has the same name as the
 title of the current page. `arg1` etc are used for the parameter names:
@@ -446,7 +446,7 @@ Document the individual parameters either directly in the `**Description:**`
 section, or as a block after using this macro. You cannot use the macro if
 individual options of option-type parameters need detailed explanation.
 
-- `[%CFEngine_promise_attribute(default)%]`
+- `{{< CFEngine_promise_attribute(default) >}}`
 
 Renders the syntax description of the current promise attribute. The current
 markdown needs to comply with the following:
@@ -467,15 +467,15 @@ title: promise_type
 
 ### attribute1
 
-[%CFEngine_promise_attribute(default)%]
+{{< CFEngine_promise_attribute(default) >}}
 
 This will document "attribute1" of "promise_type"
 
 ### body
 
 #### attribute1
 
-[%CFEngine_promise_attribute(default)%]
+{{< CFEngine_promise_attribute(default) >}}
 
 This will document "attribute1" of "body"
 ```
@@ -494,17 +494,17 @@ The generated markdown is:
 If a `default` parameter is provided, then a `**Default value:**` statement
 is created.
 
-- `[%CFEngine_function_table()%]`
+- `{{< CFEngine_function_table() >}}`
 
 Renders a table of built-in functions, grouped by function category.
 
-- `[%CFEngine_syntax_map(subtree)%]`
+- `{{< CFEngine_syntax_map(subtree) >}}`
 
 Renders a nested tree of CFEngine words, starting at `subtree`.
 
 #### Other macros
 
-- `[%CFEngine_redirect(target)]`
+- `{{< CFEngine_redirect(target) >}}`
 
 Injects javascript that redirects the current page to the HTML page for `target`,
 which needs to be a title or title#section combination as in regular `[text][title#section]`
@@ -545,7 +545,7 @@ requires a body template, then see next section).
     Longer explanation on what it does and why it is useful,
     over multiple paragraphs if necessary.
 
-    [%CFEngine_promise_attribute(default value)%]
+    {{< CFEngine_promise_attribute(default value) >}}
 
     More information about special input values.
 
@@ -581,7 +581,7 @@ body type, with the most relevant attributes set to self-explanatory values.
     Longer explanation on what this body template is used for,
     over multiple paragraphs if necessary.
 
-    [%CFEngine_promise_attribute()%]
+    {{< CFEngine_promise_attribute() >}}
 
     **Example:**
 
@@ -603,7 +603,7 @@ runnable code.
 No header necessary - there is one function per page, and the page's
 title is the name of the function.
 
-    [%CFEngine_function_prototype(parameter1, parameters2, ...)%]
+    {{< CFEngine_function_prototype(parameter1, parameters2, ...) >}}
 
     **Description:** Returns something based on `parameter1` and `parameter2`.
 
@@ -614,7 +614,7 @@ title is the name of the function.
 
     Over multiple paragraphs if necessary.
 
-    [%CFEngine_function_attributes(parameter1, parameter2)%]
+    {{< CFEngine_function_attributes(parameter1, parameter2) >}}
 
     Explain important attribute values, correlations and limitations.
 

cheatsheet.markdown

@@ -486,16 +486,16 @@ Examples from cfengine/core can be rendered using the `CFEngine_include_example`
   `[\%CFEngine_include_example(class-automatic-canonificiation.cf)\%]`
 
   {% raw %}
-  [%CFEngine_include_example(class-automatic-canonificiation.cf)%]
+  {{< CFEngine_include_example(class-automatic-canonificiation.cf) >}}
   {% endraw %}
 
 ### Include snippet of text from a file
 
 Sometimes it's nice to include a snippet from another file. For example, we dynamically generate the `--help` output for each component on each doc build and that output is included on each component page.
 
-`[%CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$)%]`
+`{{< CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$) >}}`
 
-[%CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$)%]
+{{< CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$) >}}
 
 ---
 
@@ -504,18 +504,18 @@ Sometimes it's nice to include a snippet from another file. For example, we dyna
 Sometimes it's nice to include an external file
 
 <pre>
-[%CFEngine_include_markdown(masterfiles/CHANGELOG.md)%]
+{{< CFEngine_include_markdown(masterfiles/CHANGELOG.md) >}}
 </pre>
 
 #### Including chunks of policy from the MPF
 
 Here I am including a bundle named `cfe_autorun_inventory_listening_ports`. It may be a common or an agent bundle (in case the bundle ever changes types).
 
 <pre>
-[%CFEngine_include_snippet(inventory/any.cf, bundle\s+(agent|common)\s+cfe_autorun_inventory_listening_ports, \})%]
+{{< CFEngine_include_snippet(inventory/any.cf, bundle\s+(agent|common)\s+cfe_autorun_inventory_listening_ports, \}) >}}
 </pre>
 
-[%CFEngine_include_snippet(inventory/any.cf, bundle\s+(agent|common)\s+cfe_autorun_inventory_listening_ports, \})%]
+{{< CFEngine_include_snippet(inventory/any.cf, bundle\s+(agent|common)\s+cfe_autorun_inventory_listening_ports, \}) >}}
 
 ### Comments inside documentation
 
@@ -555,21 +555,21 @@ If you are referring to something within UI / screenshots / buttons etc use bold
 
 ### symlink example
 
-[%CFEngine_include_snippet(masterfiles/lib/files.cf, ^body\slink_from\sln_s.*, ^##)%]
+{{< CFEngine_include_snippet(masterfiles/lib/files.cf, ^body\slink_from\sln_s.*, ^##) >}}
 
 ### Self documenting policy
 
 #### For the stdlib:
 
-[%CFEngine_library_include(lib/commands)%]
+{{< CFEngine_library_include(lib/commands) >}}
 
 #### For update.cf?
 
-[%CFEngine_library_include(update)%]
+{{< CFEngine_library_include(update) >}}
 
 #### for promises.cf?
 
-[%CFEngine_library_include(promises)%]
+{{< CFEngine_library_include(promises) >}}
 
 ## Variables
 

content/examples/_index.markdown

@@ -257,4 +257,4 @@ of your main policy.
 For example, the LDAP query in `active_directory.cf` needs a domain name.
 In the variable declaration, replace "cftesting" with your domain name:
 
-[%CFEngine_include_snippet(integrating_the_example_into_your_main_policy.cf, .* )%]
+{{< CFEngine_include_snippet(integrating_the_example_into_your_main_policy.cf, .* ) >}}

content/examples/example-snippets/active_directory.markdown

@@ -6,16 +6,16 @@ sorting: 7
 
 ## Active directory example
 
-[%CFEngine_include_snippet(active_directory_example.cf, .* )%]
+{{< CFEngine_include_snippet(active_directory_example.cf, .* ) >}}
 
 ## Active list users directory example
 
-[%CFEngine_include_snippet(active_list_users_directory_example.cf, .* )%]
+{{< CFEngine_include_snippet(active_list_users_directory_example.cf, .* ) >}}
 
 ## Active directory show users example
 
-[%CFEngine_include_snippet(active_directory_show_users_example.cf, .* )%]
+{{< CFEngine_include_snippet(active_directory_show_users_example.cf, .* ) >}}
 
 ## LDAP interactions
 
-[%CFEngine_include_snippet(ldap_interactions.cf, .* )%]
+{{< CFEngine_include_snippet(ldap_interactions.cf, .* ) >}}

content/examples/example-snippets/basic-file-directory.markdown

@@ -34,65 +34,65 @@ sorting: 6
 
 Create files and directories and set permissions.
 
-[%CFEngine_include_snippet(create_files_and_directories.cf, .* )%]
+{{< CFEngine_include_snippet(create_files_and_directories.cf, .* ) >}}
 
 ## Copy single files
 
 Copy single files, locally (local_cp) or from a remote site (secure_cp). The Community Open Promise-Body Library (COPBL; cfengine_stdlib.cf) should be included in the /var/cfengine/inputs/ directory and input as below.
 
-[%CFEngine_include_snippet(copy_single_files.cf, .* )%]
+{{< CFEngine_include_snippet(copy_single_files.cf, .* ) >}}
 
 ## Copy directory trees
 
 Copy directory trees, locally (local_cp) or from a remote site (secure_cp). (depth_search => recurse("")) defines the number of sublevels to include, ("inf") gets entire tree.
 
-[%CFEngine_include_snippet(copy_directory_trees.cf, .* )%]
+{{< CFEngine_include_snippet(copy_directory_trees.cf, .* ) >}}
 
 ## Disabling and rotating files
 
 Use the following simple steps to disable and rotate files. See the Community Open Promise-Body Library if you wish more details on what disable and rotate does.
 
-[%CFEngine_include_snippet(disabling_and_rotating_files.cf, .* )%]
+{{< CFEngine_include_snippet(disabling_and_rotating_files.cf, .* ) >}}
 
 ## Add lines to a file
 
 There are numerous approaches to adding lines to a file. Often the order of a configuration file is unimportant, we just need to ensure settings within it. A simple way of adding lines is show below.
 
-[%CFEngine_include_snippet(add_lines_to_a_file.cf, .* )%]
+{{< CFEngine_include_snippet(add_lines_to_a_file.cf, .* ) >}}
 
 Also you could write this using a list variable:
 
-[%CFEngine_include_snippet(add_lines_to_a_file_1.cf, .* )%]
+{{< CFEngine_include_snippet(add_lines_to_a_file_1.cf, .* ) >}}
 
 ## Check file or directory permissions
 
-[%CFEngine_include_snippet(check_file_or_directory_permissions.cf, .* )%]
+{{< CFEngine_include_snippet(check_file_or_directory_permissions.cf, .* ) >}}
 
 ## Commenting lines in a file
 
-[%CFEngine_include_snippet(commenting_lines_in_a_file.cf, .* )%]
+{{< CFEngine_include_snippet(commenting_lines_in_a_file.cf, .* ) >}}
 
 ## Copy files
 
-[%CFEngine_include_snippet(copy_files.cf, .* )%]
+{{< CFEngine_include_snippet(copy_files.cf, .* ) >}}
 
 ## Copy and flatten directory
 
-[%CFEngine_include_snippet(copy_and_flatten_directory.cf, .* )%]
+{{< CFEngine_include_snippet(copy_and_flatten_directory.cf, .* ) >}}
 
 ## Copy then edit a file convergently
 
 To convergently chain a copy followed by edit, you need a staging file. First you copy to the staging file. Then you edit the final file and insert the staging file into it as part of the editing. This is convergent with respect to both stages of the process.
 
-[%CFEngine_include_snippet(copy_then_edit_a_file_convergently.cf, .* )%]
+{{< CFEngine_include_snippet(copy_then_edit_a_file_convergently.cf, .* ) >}}
 
 ## Deleting lines from a file
 
-[%CFEngine_include_snippet(deleting_lines_from_a_file.cf, .* )%]
+{{< CFEngine_include_snippet(deleting_lines_from_a_file.cf, .* ) >}}
 
 ## Deleting lines exception
 
-[%CFEngine_include_snippet(deleting_lines_exception.cf, .* )%]
+{{< CFEngine_include_snippet(deleting_lines_exception.cf, .* ) >}}
 
 ## Delete files recursively
 
@@ -104,23 +104,23 @@ This is a huge topic. See also See Add lines to a file, See Editing tabular file
 
 Here is an example of how to comment out lines matching a number of patterns:
 
-[%CFEngine_include_snippet(editing_files.cf, .* )%]
+{{< CFEngine_include_snippet(editing_files.cf, .* ) >}}
 
 ## Editing tabular files
 
-[%CFEngine_include_snippet(editing_tabular_files.cf, .* )%]
+{{< CFEngine_include_snippet(editing_tabular_files.cf, .* ) >}}
 
 ## Inserting lines in a file
 
-[%CFEngine_include_snippet(inserting_lines_in_a_file.cf, .* )%]
+{{< CFEngine_include_snippet(inserting_lines_in_a_file.cf, .* ) >}}
 
 ## Back references in filenames
 
-[%CFEngine_include_snippet(back_references_in_filenames.cf, .* )%]
+{{< CFEngine_include_snippet(back_references_in_filenames.cf, .* ) >}}
 
 ## Add variable definitions to a file
 
-[%CFEngine_include_snippet(add_variable_definitions_to_a_file.cf, .* )%]
+{{< CFEngine_include_snippet(add_variable_definitions_to_a_file.cf, .* ) >}}
 
 Results in:
 
@@ -130,32 +130,32 @@ Results in:
 
 An example of this would be to add variables to /etc/sysctl.conf on Linux:
 
-[%CFEngine_include_snippet(add_variable_definitions_to_a_file_1.cf, .* )%]
+{{< CFEngine_include_snippet(add_variable_definitions_to_a_file_1.cf, .* ) >}}
 
 ## Linking files
 
-[%CFEngine_include_snippet(linking_files.cf, .* )%]
+{{< CFEngine_include_snippet(linking_files.cf, .* ) >}}
 
 ## Listing files-pattern in a directory
 
-[%CFEngine_include_snippet(listing_files-pattern_in_a_directory.cf, .* )%]
+{{< CFEngine_include_snippet(listing_files-pattern_in_a_directory.cf, .* ) >}}
 
 ## Locate and transform files
 
-[%CFEngine_include_snippet(locate_and_transform_files.cf, .* )%]
+{{< CFEngine_include_snippet(locate_and_transform_files.cf, .* ) >}}
 
 ## BSD flags
 
-[%CFEngine_include_snippet(bsd_flags.cf, .* )%]
+{{< CFEngine_include_snippet(bsd_flags.cf, .* ) >}}
 
 ## Search and replace text
 
-[%CFEngine_include_snippet(search_and_replace_text.cf, .* )%]
+{{< CFEngine_include_snippet(search_and_replace_text.cf, .* ) >}}
 
 ## Selecting a region in a file
 
-[%CFEngine_include_snippet(selecting_a_region_in_a_file.cf, .* )%]
+{{< CFEngine_include_snippet(selecting_a_region_in_a_file.cf, .* ) >}}
 
 ## Warn if matching line in file
 
-[%CFEngine_include_snippet(warn_if_matching_line_in_file.cf, .* )%]
+{{< CFEngine_include_snippet(warn_if_matching_line_in_file.cf, .* ) >}}

content/examples/example-snippets/cfengine-administration.markdown

@@ -15,8 +15,8 @@ This shows how dependencies can be chained in spite of the order of promises in
 
 Normally the order of promises in a bundle is followed, within each promise type, and the types are ordered according to normal ordering.
 
-[%CFEngine_include_snippet(ordering_promises.cf, .* )%]
+{{< CFEngine_include_snippet(ordering_promises.cf, .* ) >}}
 
 ## Aborting execution
 
-[%CFEngine_include_snippet(aborting_execution.cf, .* )%]
+{{< CFEngine_include_snippet(aborting_execution.cf, .* ) >}}