Fix some Markdown formatting issues

Address miscellaneous issues with Markdown formatting in comments which
are consumed by shocco when generating the online documentation.

Change-Id: I953075cdbddbf1f119c6c7e35f039e2e54b79078

exercises/aggregates.sh

@@ -3,12 +3,13 @@
 # **aggregates.sh**
 
 # This script demonstrates how to use host aggregates:
-#  *  Create an Aggregate
-#  *  Updating Aggregate details
-#  *  Testing Aggregate metadata
-#  *  Testing Aggregate delete
-#  *  Testing General Aggregates (https://blueprints.launchpad.net/nova/+spec/general-host-aggregates)
-#  *  Testing add/remove hosts (with one host)
+#
+# *  Create an Aggregate
+# *  Updating Aggregate details
+# *  Testing Aggregate metadata
+# *  Testing Aggregate delete
+# *  Testing General Aggregates (https://blueprints.launchpad.net/nova/+spec/general-host-aggregates)
+# *  Testing add/remove hosts (with one host)
 
 echo "**************************************************"
 echo "Begin DevStack Exercise: $0"

exercises/boot_from_volume.sh

@@ -3,8 +3,9 @@
 # **boot_from_volume.sh**
 
 # This script demonstrates how to boot from a volume.  It does the following:
-#  *  Create a bootable volume
-#  *  Boot a volume-backed instance
+#
+# *  Create a bootable volume
+# *  Boot a volume-backed instance
 
 echo "*********************************************************************"
 echo "Begin DevStack Exercise: $0"

functions

@@ -1,16 +1,17 @@
 # functions - Common functions used by DevStack components
 #
 # The following variables are assumed to be defined by certain functions:
-# ``ENABLED_SERVICES``
-# ``ERROR_ON_CLONE``
-# ``FILES``
-# ``GLANCE_HOSTPORT``
-# ``OFFLINE``
-# ``PIP_DOWNLOAD_CACHE``
-# ``PIP_USE_MIRRORS``
-# ``RECLONE``
-# ``TRACK_DEPENDS``
-# ``http_proxy``, ``https_proxy``, ``no_proxy``
+#
+# - ``ENABLED_SERVICES``
+# - ``ERROR_ON_CLONE``
+# - ``FILES``
+# - ``GLANCE_HOSTPORT``
+# - ``OFFLINE``
+# - ``PIP_DOWNLOAD_CACHE``
+# - ``PIP_USE_MIRRORS``
+# - ``RECLONE``
+# - ``TRACK_DEPENDS``
+# - ``http_proxy``, ``https_proxy``, ``no_proxy``
 
 
 # Save trace setting

lib/apache

@@ -2,15 +2,16 @@
 # Functions to control configuration and operation of apache web server
 
 # Dependencies:
-# ``functions`` file
-# is_apache_enabled_service
-# install_apache_wsgi
-# config_apache_wsgi
-# enable_apache_site
-# disable_apache_site
-# start_apache_server
-# stop_apache_server
-# restart_apache_server
+#
+# - ``functions`` file
+# - is_apache_enabled_service
+# - install_apache_wsgi
+# - config_apache_wsgi
+# - enable_apache_site
+# - disable_apache_site
+# - start_apache_server
+# - stop_apache_server
+# - restart_apache_server
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -116,6 +117,7 @@ function restart_apache_server() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/baremetal

@@ -1,19 +1,19 @@
-# vim: tabstop=4 shiftwidth=4 softtabstop=4
+## vim: tabstop=4 shiftwidth=4 softtabstop=4
 
-# Copyright (c) 2012 Hewlett-Packard Development Company, L.P.
-# All Rights Reserved.
-#
-#    Licensed under the Apache License, Version 2.0 (the "License"); you may
-#    not use this file except in compliance with the License. You may obtain
-#    a copy of the License at
-#
-#         http://www.apache.org/licenses/LICENSE-2.0
-#
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#    License for the specific language governing permissions and limitations
-#    under the License.
+## Copyright (c) 2012 Hewlett-Packard Development Company, L.P.
+## All Rights Reserved.
+##
+##    Licensed under the Apache License, Version 2.0 (the "License"); you may
+##    not use this file except in compliance with the License. You may obtain
+##    a copy of the License at
+##
+##         http://www.apache.org/licenses/LICENSE-2.0
+##
+##    Unless required by applicable law or agreed to in writing, software
+##    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+##    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+##    License for the specific language governing permissions and limitations
+##    under the License.
 
 
 # This file provides devstack with the environment and utilities to
@@ -24,7 +24,8 @@
 # control physical hardware resources on the same network, if you know
 # the MAC address(es) and IPMI credentials.
 #
-# At a minimum, to enable the baremetal driver, you must set these in loclarc:
+# At a minimum, to enable the baremetal driver, you must set these in localrc:
+#
 #    VIRT_DRIVER=baremetal
 #    ENABLED_SERVICES="$ENABLED_SERVICES,baremetal"
 #
@@ -38,11 +39,13 @@
 # Below that, various functions are defined, which are called by devstack
 # in the following order:
 #
-#  before nova-cpu starts:
+# before nova-cpu starts:
+#
 #  - prepare_baremetal_toolchain
 #  - configure_baremetal_nova_dirs
 #
-#  after nova and glance have started:
+# after nova and glance have started:
+#
 #  - build_and_upload_baremetal_deploy_k_and_r $token
 #  - create_baremetal_flavor $BM_DEPLOY_KERNEL_ID $BM_DEPLOY_RAMDISK_ID
 #  - upload_baremetal_image $url $token
@@ -58,11 +61,13 @@ set +o xtrace
 # -------------------
 
 # sub-driver to use for kernel deployment
-#  - nova.virt.baremetal.pxe.PXE
-#  - nova.virt.baremetal.tilera.TILERA
+#
+# - nova.virt.baremetal.pxe.PXE
+# - nova.virt.baremetal.tilera.TILERA
 BM_DRIVER=${BM_DRIVER:-nova.virt.baremetal.pxe.PXE}
 
 # sub-driver to use for remote power management
+#
 # - nova.virt.baremetal.fake.FakePowerManager, for manual power control
 # - nova.virt.baremetal.ipmi.IPMI, for remote IPMI
 # - nova.virt.baremetal.tilera_pdu.Pdu, for TilePro hardware
@@ -84,11 +89,11 @@ BM_POSEUR_EXTRA_OPTS=${BM_POSEUR_EXTRA_OPTS:-}
 # dedicated to baremetal. When enable this, make sure these conditions are
 # fulfilled:
 #
-#  1) nova-compute and nova-network runs on the same host
-#  2) nova-network uses FlatDHCPManager
+# 1) nova-compute and nova-network runs on the same host
+# 2) nova-network uses FlatDHCPManager
 #
 # NOTE: the other BM_DNSMASQ_* have no effect on the behavior if this option
-#       is enabled.
+# is enabled.
 BM_DNSMASQ_FROM_NOVA_NETWORK=`trueorfalse False $BM_DNSMASQ_FROM_NOVA_NETWORK`
 
 # BM_DNSMASQ_IFACE should match FLAT_NETWORK_BRIDGE
@@ -105,9 +110,9 @@ fi
 # BM_DNSMASQ_DNS provide dns server to bootstrap clients
 BM_DNSMASQ_DNS=${BM_DNSMASQ_DNS:-}
 
-# BM_FIRST_MAC *must* be set to the MAC address of the node you will boot.
-#              This is passed to dnsmasq along with the kernel/ramdisk to
-#              deploy via PXE.
+# BM_FIRST_MAC *must* be set to the MAC address of the node you will
+# boot.  This is passed to dnsmasq along with the kernel/ramdisk to
+# deploy via PXE.
 BM_FIRST_MAC=${BM_FIRST_MAC:-}
 
 # BM_SECOND_MAC is only important if the host has >1 NIC.
@@ -121,9 +126,9 @@ BM_PM_ADDR=${BM_PM_ADDR:-0.0.0.0}
 BM_PM_USER=${BM_PM_USER:-user}
 BM_PM_PASS=${BM_PM_PASS:-pass}
 
-# BM_FLAVOR_* options are arbitrary and not necessarily related to physical
-#             hardware capacity. These can be changed if you are testing
-#             BaremetalHostManager with multiple nodes and different flavors.
+# BM_FLAVOR_* options are arbitrary and not necessarily related to
+# physical hardware capacity. These can be changed if you are testing
+# BaremetalHostManager with multiple nodes and different flavors.
 BM_CPU_ARCH=${BM_CPU_ARCH:-x86_64}
 BM_FLAVOR_CPU=${BM_FLAVOR_CPU:-1}
 BM_FLAVOR_RAM=${BM_FLAVOR_RAM:-1024}
@@ -288,8 +293,8 @@ function create_baremetal_flavor() {
 
 }
 
-# pull run-time kernel/ramdisk out of disk image and load into glance
-# note that $file is currently expected to be in qcow2 format
+# Pull run-time kernel/ramdisk out of disk image and load into glance.
+# Note that $file is currently expected to be in qcow2 format.
 # Sets KERNEL_ID and RAMDISK_ID
 #
 # Usage: extract_and_upload_k_and_r_from_image $token $file
@@ -432,7 +437,7 @@ function clear_baremetal_of_all_nodes() {
     done
 }
 
-# inform nova-baremetal about nodes, MACs, etc
+# Inform nova-baremetal about nodes, MACs, etc.
 # Defaults to using BM_FIRST_MAC and BM_SECOND_MAC if parameters not specified
 #
 # Usage: add_baremetal_node <first_mac> <second_mac>
@@ -461,6 +466,7 @@ function add_baremetal_node() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/ceilometer

@@ -10,6 +10,7 @@
 #   enable_service ceilometer-alarm-notifier ceilometer-alarm-evaluator
 
 # Dependencies:
+#
 # - functions
 # - OS_AUTH_URL for auth in api
 # - DEST set to the destination directory
@@ -18,12 +19,12 @@
 
 # stack.sh
 # ---------
-# install_ceilometer
-# configure_ceilometer
-# init_ceilometer
-# start_ceilometer
-# stop_ceilometer
-# cleanup_ceilometer
+# - install_ceilometer
+# - configure_ceilometer
+# - init_ceilometer
+# - start_ceilometer
+# - stop_ceilometer
+# - cleanup_ceilometer
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -156,6 +157,7 @@ function stop_ceilometer() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/cinder

@@ -2,19 +2,20 @@
 # Install and start **Cinder** volume service
 
 # Dependencies:
+#
 # - functions
 # - DEST, DATA_DIR, STACK_USER must be defined
-# SERVICE_{TENANT_NAME|PASSWORD} must be defined
-# ``KEYSTONE_TOKEN_FORMAT`` must be defined
+# - SERVICE_{TENANT_NAME|PASSWORD} must be defined
+# - ``KEYSTONE_TOKEN_FORMAT`` must be defined
 
 # stack.sh
 # ---------
-# install_cinder
-# configure_cinder
-# init_cinder
-# start_cinder
-# stop_cinder
-# cleanup_cinder
+# - install_cinder
+# - configure_cinder
+# - init_cinder
+# - start_cinder
+# - stop_cinder
+# - cleanup_cinder
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -82,7 +83,8 @@ VOLUME_NAME_PREFIX=${VOLUME_NAME_PREFIX:-volume-}
 # Functions
 # ---------
 # _clean_lvm_lv removes all cinder LVM volumes
-# _clean_lvm_lv $VOLUME_GROUP $VOLUME_NAME_PREFIX
+#
+# Usage: _clean_lvm_lv $VOLUME_GROUP $VOLUME_NAME_PREFIX
 function _clean_lvm_lv() {
     local vg=$1
     local lv_prefix=$2
@@ -98,7 +100,8 @@ function _clean_lvm_lv() {
 
 # _clean_lvm_backing_file() removes the backing file of the
 # volume group used by cinder
-# _clean_lvm_backing_file() $VOLUME_GROUP
+#
+# Usage: _clean_lvm_backing_file() $VOLUME_GROUP
 function _clean_lvm_backing_file() {
     local vg=$1
 
@@ -546,6 +549,7 @@ function stop_cinder() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/database

@@ -124,6 +124,7 @@ function database_connection_url {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/databases/mysql

@@ -2,7 +2,8 @@
 # Functions to control the configuration and operation of the **MySQL** database backend
 
 # Dependencies:
-# DATABASE_{HOST,USER,PASSWORD} must be defined
+#
+# - DATABASE_{HOST,USER,PASSWORD} must be defined
 
 # Save trace setting
 MY_XTRACE=$(set +o | grep xtrace)

lib/databases/postgresql

@@ -2,7 +2,8 @@
 # Functions to control the configuration and operation of the **PostgreSQL** database backend
 
 # Dependencies:
-# DATABASE_{HOST,USER,PASSWORD} must be defined
+#
+# - DATABASE_{HOST,USER,PASSWORD} must be defined
 
 # Save trace setting
 PG_XTRACE=$(set +o | grep xtrace)

lib/glance

@@ -2,20 +2,21 @@
 # Functions to control the configuration and operation of the **Glance** service
 
 # Dependencies:
-# ``functions`` file
-# ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
-# ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
-# ``SERVICE_HOST``
-# ``KEYSTONE_TOKEN_FORMAT`` must be defined
+#
+# - ``functions`` file
+# - ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
+# - ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
+# - ``SERVICE_HOST``
+# - ``KEYSTONE_TOKEN_FORMAT`` must be defined
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_glance
-# configure_glance
-# init_glance
-# start_glance
-# stop_glance
-# cleanup_glance
+# - install_glance
+# - configure_glance
+# - init_glance
+# - start_glance
+# - stop_glance
+# - cleanup_glance
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -209,6 +210,7 @@ function stop_glance() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/heat

@@ -2,21 +2,23 @@
 # Install and start **Heat** service
 
 # To enable, add the following to localrc
-# ENABLED_SERVICES+=,heat,h-api,h-api-cfn,h-api-cw,h-eng
+#
+#   ENABLED_SERVICES+=,heat,h-api,h-api-cfn,h-api-cw,h-eng
 
 # Dependencies:
+#
 # - functions
 
 # stack.sh
 # ---------
-# install_heatclient
-# install_heat
-# configure_heatclient
-# configure_heat
-# init_heat
-# start_heat
-# stop_heat
-# cleanup_heat
+# - install_heatclient
+# - install_heat
+# - configure_heatclient
+# - configure_heat
+# - init_heat
+# - start_heat
+# - stop_heat
+# - cleanup_heat
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -198,6 +200,7 @@ function disk_image_create {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/horizon

@@ -1,21 +1,20 @@
 # lib/horizon
 # Functions to control the configuration and operation of the horizon service
-# <do not include this template file in ``stack.sh``!>
 
 # Dependencies:
-# ``functions`` file
-# ``apache`` file
-# ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
-# <list other global vars that are assumed to be defined>
+#
+# - ``functions`` file
+# - ``apache`` file
+# - ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_horizon
-# configure_horizon
-# init_horizon
-# start_horizon
-# stop_horizon
-# cleanup_horizon
+# - install_horizon
+# - configure_horizon
+# - init_horizon
+# - start_horizon
+# - stop_horizon
+# - cleanup_horizon
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -25,8 +24,6 @@ set +o xtrace
 # Defaults
 # --------
 
-# <define global variables here that belong to this project>
-
 # Set up default directories
 HORIZON_DIR=$DEST/horizon
 
@@ -183,6 +180,7 @@ function stop_horizon() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/infra

@@ -5,12 +5,13 @@
 # requirements as a global list
 
 # Dependencies:
-# ``functions`` file
+#
+# - ``functions`` file
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# unfubar_setuptools
-# install_infra
+# - unfubar_setuptools
+# - install_infra
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -51,6 +52,7 @@ function install_infra() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/ironic

@@ -2,21 +2,21 @@
 # Functions to control the configuration and operation of the **Ironic** service
 
 # Dependencies:
-# ``functions`` file
-# ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
-# ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
-# ``SERVICE_HOST``
-# ``KEYSTONE_TOKEN_FORMAT`` must be defined
+#
+# - ``functions`` file
+# - ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
+# - ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
+# - ``SERVICE_HOST``
+# - ``KEYSTONE_TOKEN_FORMAT`` must be defined
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_ironic
-# install_ironicclient
-# configure_ironic
-# init_ironic
-# start_ironic
-# stop_ironic
-# cleanup_ironic
+# - install_ironic
+# - install_ironicclient
+# - init_ironic
+# - start_ironic
+# - stop_ironic
+# - cleanup_ironic
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -225,6 +225,7 @@ function stop_ironic() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/keystone

@@ -2,25 +2,26 @@
 # Functions to control the configuration and operation of **Keystone**
 
 # Dependencies:
-# ``functions`` file
-# ``DEST``, ``STACK_USER``
-# ``IDENTITY_API_VERSION``
-# ``BASE_SQL_CONN``
-# ``SERVICE_HOST``, ``SERVICE_PROTOCOL``
-# ``SERVICE_TOKEN``
-# ``S3_SERVICE_PORT`` (template backend only)
+#
+# - ``functions`` file
+# - ``DEST``, ``STACK_USER``
+# - ``IDENTITY_API_VERSION``
+# - ``BASE_SQL_CONN``
+# - ``SERVICE_HOST``, ``SERVICE_PROTOCOL``
+# - ``SERVICE_TOKEN``
+# - ``S3_SERVICE_PORT`` (template backend only)
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_keystone
-# configure_keystone
-# _config_keystone_apache_wsgi
-# init_keystone
-# start_keystone
-# create_keystone_accounts
-# stop_keystone
-# cleanup_keystone
-# _cleanup_keystone_apache_wsgi
+# - install_keystone
+# - configure_keystone
+# - _config_keystone_apache_wsgi
+# - init_keystone
+# - start_keystone
+# - create_keystone_accounts
+# - stop_keystone
+# - cleanup_keystone
+# - _cleanup_keystone_apache_wsgi
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -393,6 +394,7 @@ function stop_keystone() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/ldap

@@ -2,7 +2,8 @@
 # Functions to control the installation and configuration of **ldap**
 
 # ``lib/keystone`` calls the entry points in this order:
-# install_ldap()
+#
+# - install_ldap()
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -91,6 +92,7 @@ function clear_ldap_state() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/neutron

@@ -7,24 +7,24 @@
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_neutron
-# install_neutronclient
-# install_neutron_agent_packages
-# install_neutron_third_party
-# configure_neutron
-# init_neutron
-# configure_neutron_third_party
-# init_neutron_third_party
-# start_neutron_third_party
-# create_nova_conf_neutron
-# start_neutron_service_and_check
-# create_neutron_initial_network
-# setup_neutron_debug
-# start_neutron_agents
+# - install_neutron
+# - install_neutronclient
+# - install_neutron_agent_packages
+# - install_neutron_third_party
+# - configure_neutron
+# - init_neutron
+# - configure_neutron_third_party
+# - init_neutron_third_party
+# - start_neutron_third_party
+# - create_nova_conf_neutron
+# - start_neutron_service_and_check
+# - create_neutron_initial_network
+# - setup_neutron_debug
+# - start_neutron_agents
 #
 # ``unstack.sh`` calls the entry points in this order:
 #
-# stop_neutron
+# - stop_neutron
 
 # Functions in lib/neutron are classified into the following categories:
 #
@@ -891,6 +891,7 @@ function stop_neutron_third_party() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/nova

@@ -2,22 +2,23 @@
 # Functions to control the configuration and operation of the **Nova** service
 
 # Dependencies:
-# ``functions`` file
-# ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
-# ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
-# ``LIBVIRT_TYPE`` must be defined
-# ``INSTANCE_NAME_PREFIX``, ``VOLUME_NAME_PREFIX`` must be defined
-# ``KEYSTONE_TOKEN_FORMAT`` must be defined
+#
+# - ``functions`` file
+# - ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
+# - ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
+# - ``LIBVIRT_TYPE`` must be defined
+# - ``INSTANCE_NAME_PREFIX``, ``VOLUME_NAME_PREFIX`` must be defined
+# - ``KEYSTONE_TOKEN_FORMAT`` must be defined
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_nova
-# configure_nova
-# create_nova_conf
-# init_nova
-# start_nova
-# stop_nova
-# cleanup_nova
+# - install_nova
+# - configure_nova
+# - create_nova_conf
+# - init_nova
+# - start_nova
+# - stop_nova
+# - cleanup_nova
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -683,6 +684,7 @@ function stop_nova() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/nova_plugins/hypervisor-docker

@@ -2,11 +2,13 @@
 # Configure the Docker hypervisor
 
 # Enable with:
-# VIRT_DRIVER=docker
+#
+#   VIRT_DRIVER=docker
 
 # Dependencies:
-# ``functions`` file
-# ``nova`` and ``glance`` configurations
+#
+# - ``functions`` file
+# - ``nova`` and ``glance`` configurations
 
 # install_nova_hypervisor - install any external requirements
 # configure_nova_hypervisor - make configuration changes, including those to other services

lib/oslo

@@ -6,11 +6,12 @@
 # pre-released versions of oslo libraries.
 
 # Dependencies:
-# ``functions`` file
+#
+# - ``functions`` file
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_oslo
+# - install_oslo
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -52,6 +53,7 @@ function cleanup_oslo() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/rpc_backend

@@ -3,15 +3,16 @@
 # rpc backend settings
 
 # Dependencies:
-# ``functions`` file
-# ``RABBIT_{HOST|PASSWORD}`` must be defined when RabbitMQ is used
+#
+# - ``functions`` file
+# - ``RABBIT_{HOST|PASSWORD}`` must be defined when RabbitMQ is used
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# check_rpc_backend
-# install_rpc_backend
-# restart_rpc_backend
-# iniset_rpc_backend
+# - check_rpc_backend
+# - install_rpc_backend
+# - restart_rpc_backend
+# - iniset_rpc_backend
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -200,6 +201,7 @@ function qpid_is_supported() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/savanna-dashboard

@@ -1,15 +1,16 @@
 # lib/savanna-dashboard
 
 # Dependencies:
-# ``functions`` file
-# ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
-# ``SERVICE_HOST
+#
+# - ``functions`` file
+# - ``DEST``, ``DATA_DIR``, ``STACK_USER`` must be defined
+# - ``SERVICE_HOST``
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_savanna_dashboard
-# configure_savanna_dashboard
-# cleanup_savanna_dashboard
+# - install_savanna_dashboard
+# - configure_savanna_dashboard
+# - cleanup_savanna_dashboard
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)

lib/swift

@@ -2,22 +2,24 @@
 # Functions to control the configuration and operation of the **Swift** service
 
 # Dependencies:
-# ``functions`` file
-# ``apache`` file
-# ``DEST``, ``SCREEN_NAME``, `SWIFT_HASH` must be defined
-# ``STACK_USER`` must be defined
-# ``SWIFT_DATA_DIR`` or ``DATA_DIR`` must be defined
-# ``lib/keystone`` file
+#
+# - ``functions`` file
+# - ``apache`` file
+# - ``DEST``, ``SCREEN_NAME``, `SWIFT_HASH` must be defined
+# - ``STACK_USER`` must be defined
+# - ``SWIFT_DATA_DIR`` or ``DATA_DIR`` must be defined
+# - ``lib/keystone`` file
+#
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_swift
-# _config_swift_apache_wsgi
-# configure_swift
-# init_swift
-# start_swift
-# stop_swift
-# cleanup_swift
-# _cleanup_swift_apache_wsgi
+# - install_swift
+# - _config_swift_apache_wsgi
+# - configure_swift
+# - init_swift
+# - start_swift
+# - stop_swift
+# - cleanup_swift
+# - _cleanup_swift_apache_wsgi
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -617,6 +619,7 @@ function stop_swift() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/tempest

@@ -2,34 +2,38 @@
 # Install and configure Tempest
 
 # Dependencies:
-# ``functions`` file
-# ``lib/nova`` service is running
-# <list other global vars that are assumed to be defined>
-# - ``DEST``, ``FILES``
-# - ``ADMIN_PASSWORD``
-# - ``DEFAULT_IMAGE_NAME``
-# - ``S3_SERVICE_PORT``
-# - ``SERVICE_HOST``
-# - ``BASE_SQL_CONN`` ``lib/database`` declares
-# - ``PUBLIC_NETWORK_NAME``
-# - ``Q_USE_NAMESPACE``
-# - ``Q_ROUTER_NAME``
-# - ``VIRT_DRIVER``
-# - ``LIBVIRT_TYPE``
-# - ``KEYSTONE_SERVICE_PROTOCOL``, ``KEYSTONE_SERVICE_HOST`` from lib/keystone
+#
+# - ``functions`` file
+# - ``lib/nova`` service is running
+# - Global vars that are assumed to be defined:
+#   - ``DEST``, ``FILES``
+#   - ``ADMIN_PASSWORD``
+#   - ``DEFAULT_IMAGE_NAME``
+#   - ``S3_SERVICE_PORT``
+#   - ``SERVICE_HOST``
+#   - ``BASE_SQL_CONN`` ``lib/database`` declares
+#   - ``PUBLIC_NETWORK_NAME``
+#   - ``Q_USE_NAMESPACE``
+#   - ``Q_ROUTER_NAME``
+#   - ``VIRT_DRIVER``
+#   - ``LIBVIRT_TYPE``
+#   - ``KEYSTONE_SERVICE_PROTOCOL``, ``KEYSTONE_SERVICE_HOST`` from lib/keystone
+#
 # Optional Dependencies:
-# ALT_* (similar vars exists in keystone_data.sh)
-# ``LIVE_MIGRATION_AVAILABLE``
-# ``USE_BLOCK_MIGRATION_FOR_LIVE_MIGRATION``
-# ``DEFAULT_INSTANCE_TYPE``
-# ``DEFAULT_INSTANCE_USER``
-# ``CINDER_MULTI_LVM_BACKEND``
-# ``HEAT_CREATE_TEST_IMAGE``
+#
+# - ``ALT_*`` (similar vars exists in keystone_data.sh)
+# - ``LIVE_MIGRATION_AVAILABLE``
+# - ``USE_BLOCK_MIGRATION_FOR_LIVE_MIGRATION``
+# - ``DEFAULT_INSTANCE_TYPE``
+# - ``DEFAULT_INSTANCE_USER``
+# - ``CINDER_MULTI_LVM_BACKEND``
+# - ``HEAT_CREATE_TEST_IMAGE``
+#
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_tempest
-# configure_tempest
-# init_tempest
+# - install_tempest
+# - configure_tempest
+# - init_tempest
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -345,6 +349,7 @@ function init_tempest() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/template

@@ -3,18 +3,19 @@
 # <do not include this template file in ``stack.sh``!>
 
 # Dependencies:
-# ``functions`` file
-# ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
-# <list other global vars that are assumed to be defined>
+#
+# - ``functions`` file
+# - ``SERVICE_{TENANT_NAME|PASSWORD}`` must be defined
+# - <list other global vars that are assumed to be defined>
 
 # ``stack.sh`` calls the entry points in this order:
 #
-# install_XXXX
-# configure_XXXX
-# init_XXXX
-# start_XXXX
-# stop_XXXX
-# cleanup_XXXX
+# - install_XXXX
+# - configure_XXXX
+# - init_XXXX
+# - start_XXXX
+# - stop_XXXX
+# - cleanup_XXXX
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
@@ -79,6 +80,7 @@ function stop_XXXX() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/tls

@@ -1,24 +1,27 @@
 # lib/tls
 # Functions to control the configuration and operation of the TLS proxy service
 
-# Dependencies:
 # !! source _before_ any services that use ``SERVICE_HOST``
-# ``functions`` file
-# ``DEST``, ``DATA_DIR`` must be defined
-# ``HOST_IP``, ``SERVICE_HOST``
-# ``KEYSTONE_TOKEN_FORMAT`` must be defined
+#
+# Dependencies:
+#
+# - ``functions`` file
+# - ``DEST``, ``DATA_DIR`` must be defined
+# - ``HOST_IP``, ``SERVICE_HOST``
+# - ``KEYSTONE_TOKEN_FORMAT`` must be defined
 
 # Entry points:
-# configure_CA
-# init_CA
+#
+# - configure_CA
+# - init_CA
 
-# configure_proxy
-# start_tls_proxy
+# - configure_proxy
+# - start_tls_proxy
 
-# make_root_ca
-# make_int_ca
-# new_cert $INT_CA_DIR int-server "abc"
-# start_tls_proxy HOST_IP 5000 localhost 5000
+# - make_root_ca
+# - make_int_ca
+# - new_cert $INT_CA_DIR int-server "abc"
+# - start_tls_proxy HOST_IP 5000 localhost 5000
 
 
 # Defaults
@@ -321,6 +324,7 @@ function start_tls_proxy() {
 }
 
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End:

lib/trove

@@ -181,6 +181,7 @@ function stop_trove() {
 # Restore xtrace
 $XTRACE
 
-# Local variables:
-# mode: shell-script
-# End:
+# Tell emacs to use shell-script-mode
+## Local variables:
+## mode: shell-script
+## End: