Updating CNV repo names for 2.3

Updating CNV repo names for 2.3

// Module included in the following assemblies:
//
// cnv_install/cnv-installing-virtctl.adoc

[id="cnv-enabling-cnv-repos_{context}"]
= Enabling container-native virtualization repositories

Red Hat offers {CNVProductName} repositories for both Red Hat Enterprise Linux 8
and Red Hat Enterprise Linux 7:

* Red Hat Enterprise Linux 8 repository: `cnv-2.3-for-rhel-8-x86_64-rpms`

* Red Hat Enterprise Linux 7 repository: `rhel-7-server-cnv-2.3-rpms`

The process for enabling the repository in `subscription-manager` is the same
in both platforms.

.Procedure

* Use `subscription manager` to enable the appropriate {CNVProductName} repository for
 your system:
+
----
# subscription-manager repos --enable <repository>
----

// Module included in the following assemblies:
//
// cnv_install/cnv-installing-virtctl.adoc

[id="cnv-enabling-cnv-repos_{context}"]
= Enabling container-native virtualization repositories

Red Hat offers {CNVProductName} repositories for both Red Hat Enterprise Linux 8
and Red Hat Enterprise Linux 7:

* Red Hat Enterprise Linux 8 repository: `cnv-2.2-for-rhel-8-x86_64-rpms`

* Red Hat Enterprise Linux 7 repository: `rhel-7-server-cnv-2.2-rpms`

The process for enabling the repository in `subscription-manager` is the same
in both platforms.

.Procedure

* Use `subscription manager` to enable the appropriate {CNVProductName} repository for
 your system:
+
----
# subscription-manager repos --enable <repository>
----


Fix typo in fluentd-server-inecure

Fix typo in fluentd-server-inecure

// Module included in the following assemblies:
//
// * logging/cluster-logging-external.adoc

[id="cluster-logging-collector-log-forward-fluentd_{context}"]
= Forwarding logs using the Fluentd forward protocol

You can use the Fluentd *forward* protocol to send a copy of your logs to an external log aggregator configured to accept the protocol instead of, or in addition to, the default Elasticsearch log store. You are responsible for configuring the external log aggregator to receive the logs from {product-title}.

To configure log forwarding using the *forward* protocol, create a `ClusterLogForwarder` Custom Resource (CR) with one or more outputs to the Fluentd servers and pipelines that use those outputs. The Fluentd output can use a TCP (insecure) or TLS (secure TCP) connection.

[NOTE]
====
Alternately, you can use a ConfigMap to forward logs using the *forward* protocols. However, this method is deprecated in {product-title} and will be removed in a future release.
====

.Procedure

. Create a `ClusterLogForwarder` CR YAML file similar to the following:
+
[source,yaml]
----
apiVersion: logging.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: instance <1>
  namespace: openshift-logging <2>
spec:
  outputs:
   - name: fluentd-server-secure <3>
     type: fluentdForward <4>
     url: 'tls://fluentdserver.security.example.com:24224' <5>
     secret: <6>
        name: fluentd-secret
   - name: fluentd-server-insecure
     type: fluentdForward
     url: 'tcp://fluentdserver.home.example.com:24224'
  pipelines:
   - name: forward-to-fluentd-secure <7>
     inputRefs:  <8>
     - application
     - audit
     outputRefs:
     - fluentd-server-secure <9>
     - default <10>
     labels:
       clusterId: C1234 <11>
   - name: forward-to-fluentd-insecure <12>
     inputRefs:
     - infrastructure
     outputRefs:
     - fluentd-server-insecure
     labels:
       clusterId: C1234
----
<1> The name of the `ClusterLogForwarder` CR must be `instance`.
<2> The namespace for the log forwarding CR must be `openshift-logging`.
<3> Specify a name for the output.
<4> Specify the `fluentdForward` type.
<5> Specify the URL and port of the external Fluentd instance as a valid absolute URL. You can use the `tcp` (insecure) or `tls` (secure TCP) protocol. If the cluster-wide proxy using the CIDR annotation is enabled, the output must be a server name or FQDN, not an IP address.
<6> If using a `tls` prefix, you must specify the name of the secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project and must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent.
<7> Optional. Specify a name for the pipeline.
<8> Specify which log types should be forwarded using that pipeline: `application,` `infrastructure`, or `audit`.
<9> Specify the output to use  with that pipeline for forwarding the logs.
<10> Optional. Specify the `default` output to forward logs to the internal Elasticsearch instance.
<11> Optional. One or more labels to add to the logs.
<12> Optional: Configure multiple outputs to forward logs to other external log aggregtors of any supported type:
** Optional. A name to describe the pipeline.
** The `inputRefs` is the log type to forward using that pipeline: `application,` `infrastructure`, or `audit`.
** The `outputRefs` is the name of the output to use.
** Optional: One or more labels to add to the logs.

. Create the CR object:
+
[source,terminal]
----
$ oc create -f <file-name>.yaml
----

The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd
pods to force them to redeploy.

[source,terminal]
----
$ oc delete pod --selector logging-infra=fluentd
----

// Module included in the following assemblies:
//
// * logging/cluster-logging-external.adoc

[id="cluster-logging-collector-log-forward-fluentd_{context}"]
= Forwarding logs using the Fluentd forward protocol

You can use the Fluentd *forward* protocol to send a copy of your logs to an external log aggregator configured to accept the protocol instead of, or in addition to, the default Elasticsearch log store. You are responsible for configuring the external log aggregator to receive the logs from {product-title}.

To configure log forwarding using the *forward* protocol, create a `ClusterLogForwarder` Custom Resource (CR) with one or more outputs to the Fluentd servers and pipelines that use those outputs. The Fluentd output can use a TCP (insecure) or TLS (secure TCP) connection.

[NOTE]
====
Alternately, you can use a ConfigMap to forward logs using the *forward* protocols. However, this method is deprecated in {product-title} and will be removed in a future release.
====

.Procedure

. Create a `ClusterLogForwarder` CR YAML file similar to the following:
+
[source,yaml]
----
apiVersion: logging.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: instance <1>
  namespace: openshift-logging <2>
spec:
  outputs:
   - name: fluentd-server-secure <3>
     type: fluentdForward <4>
     url: 'tls://fluentdserver.security.example.com:24224' <5>
     secret: <6>
        name: fluentd-secret
   - name: fluentd-server-inecure
     type: fluentdForward
     url: 'tcp://fluentdserver.home.example.com:24224'
  pipelines:
   - name: forward-to-fluentd-secure <7>
     inputRefs:  <8>
     - application
     - audit
     outputRefs:
     - fluentd-server-secure <9>
     - default <10>
     labels:
       clusterId: C1234 <11>
   - name: forward-to-fluentd-insecure <12>
     inputRefs:
     - infrastructure
     outputRefs:
     - fluentd-server-insecure
     labels:
       clusterId: C1234
----
<1> The name of the `ClusterLogForwarder` CR must be `instance`.
<2> The namespace for the log forwarding CR must be `openshift-logging`.
<3> Specify a name for the output.
<4> Specify the `fluentdForward` type.
<5> Specify the URL and port of the external Fluentd instance as a valid absolute URL. You can use the `tcp` (insecure) or `tls` (secure TCP) protocol. If the cluster-wide proxy using the CIDR annotation is enabled, the output must be a server name or FQDN, not an IP address.
<6> If using a `tls` prefix, you must specify the name of the secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project and must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent.
<7> Optional. Specify a name for the pipeline.
<8> Specify which log types should be forwarded using that pipeline: `application,` `infrastructure`, or `audit`.
<9> Specify the output to use  with that pipeline for forwarding the logs.
<10> Optional. Specify the `default` output to forward logs to the internal Elasticsearch instance.
<11> Optional. One or more labels to add to the logs.
<12> Optional: Configure multiple outputs to forward logs to other external log aggregtors of any supported type:
** Optional. A name to describe the pipeline.
** The `inputRefs` is the log type to forward using that pipeline: `application,` `infrastructure`, or `audit`.
** The `outputRefs` is the name of the output to use.
** Optional: One or more labels to add to the logs.

. Create the CR object:
+
[source,terminal]
----
$ oc create -f <file-name>.yaml
----

The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd
pods to force them to redeploy.

[source,terminal]
----
$ oc delete pod --selector logging-infra=fluentd
----


INFUND-7046 Correcting Asciidoc.

INFUND-7046 Correcting Asciidoc.

Former-commit-id: be125c06d4f44698136035be9da53efb388c217d

=== Get ApplicationAssessmentSummary by Application Id
==== Request
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/http-request.adoc[]
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/path-parameters.adoc[]

==== Response
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/http-response.adoc[]
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/response-fields.adoc[]

==== Curl Example
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/curl-request.adoc[]

=== Get created invite by id
==== Request
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/http-request.adoc[]
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/path-parameters.adoc[]

==== Response
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/http-response.adoc[]
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/response-fields.adoc[]

==== Curl Example
include::{snippets}/applicationassessmentsummary/get-application-assessment-summary/curl-request.adoc[]


Fixing two build errors

Fixing two build errors

// Module included in the following assemblies:
//
// * networking/configuring-hardware-offloading.adoc

:_content-type: PROCEDURE
[id="configuring-machine-config-pool_{context}"]
= Configuring a machine config pool for hardware offloading

To enable hardware offloading, you must first create a dedicated machine config pool and configure it to work with the SR-IOV Network Operator.

.Prerequisites

* You installed the OpenShift CLI (`oc`).
* You have access to the cluster as a user with the `cluster-admin` role.

.Procedure

. Create a machine config pool for machines you want to use hardware offloading on.

.. Create a file, such as `mcp-offloading.yaml`, with content like the following example:
+
[source,yaml]
----
apiVersion: machineconfiguration.openshift.io/v1
kind: MachineConfigPool
metadata:
  name: mcp-offloading <1>
spec:
  machineConfigSelector:
    matchExpressions:
      - {key: machineconfiguration.openshift.io/role, operator: In, values: [worker,mcp-offloading]} <1>
  nodeSelector:
    matchLabels:
      node-role.kubernetes.io/mcp-offloading: "" <2>
----
<1> The name of your machine config pool for hardware offloading.
<2> This node role label is used to add nodes to the machine config pool.

.. Apply the configuration for the machine config pool:
+
[source,terminal]
----
$ oc create -f mcp-offloading.yaml
----

. Add nodes to the machine config pool. Label each node with the node role label of your pool:
+
[source,terminal]
----
$ oc label node worker-2 node-role.kubernetes.io/mcp-offloading=""
----

. Optional: To verify that the new pool is created, run the following command:
+
[source,terminal]
----
$ oc get nodes
----
+
--
.Example output
[source,terminal]
----
NAME       STATUS   ROLES                   AGE   VERSION
master-0   Ready    master                  2d    v1.23.3+d99c04f
master-1   Ready    master                  2d    v1.23.3+d99c04f
master-2   Ready    master                  2d    v1.23.3+d99c04f
worker-0   Ready    worker                  2d    v1.23.3+d99c04f
worker-1   Ready    worker                  2d    v1.23.3+d99c04f
worker-2   Ready    mcp-offloading,worker   47h   v1.23.3+d99c04f
worker-3   Ready    mcp-offloading,worker   47h   v1.23.3+d99c04f
----
--

. Add this machine config pool to the `SriovNetworkPoolConfig` custom resource:

.. Create a file, such as `sriov-pool-config.yaml`, with content like the following example:
+
[source,yaml]
----
apiVersion: sriovnetwork.openshift.io/v1
kind: SriovNetworkPoolConfig
metadata:
  name: sriovnetworkpoolconfig-offload
  namespace: openshift-sriov-network-operator
spec:
  ovsHardwareOffloadConfig:
    name: mcp-offloading <1>
----
<1> The name of your machine config pool for hardware offloading.

.. Apply the configuration:
+
[source,terminal]
----
$ oc create -f <SriovNetworkPoolConfig_name>.yaml
----
+
[NOTE]
=====
When you apply the configuration specified in a `SriovNetworkPoolConfig` object, the SR-IOV Operator drains and restarts the nodes in the machine config pool.

It might take several minutes for a configuration changes to apply.
=====

// Module included in the following assemblies:
//
// * networking/configuring-hardware-offloading.adoc

:_content-type: PROCEDURE
[id="configuring-machine-config-pool_{context}"]
= Configuring a machine config pool for hardware offloading

To enable hardware offloading, you must first create a dedicated machine config pool and configure it to work with the SR-IOV Network Operator.

.Prerequisites

* You installed the OpenShift CLI (`oc`).
* You have access to the cluster as a user with the `cluster-admin` role.

.Procedure

. Create a machine config pool for machines you want to use hardware offloading on.

.. Create a file, such as `mcp-offloading.yaml`, with content like the following example:
+
[source,yaml]
----
apiVersion: machineconfiguration.openshift.io/v1
kind: MachineConfigPool
metadata:
  name: mcp-offloading <1>
spec:
  machineConfigSelector:
    matchExpressions:
      - {key: machineconfiguration.openshift.io/role, operator: In, values: [worker,mcp-offloading <1>]}
  nodeSelector:
    matchLabels:
      node-role.kubernetes.io/mcp-offloading <2>: ""
----
<1> The name of your machine config pool for hardware offloading.
<2> This node role label is used to add nodes to the machine config pool.

.. Apply the configuration for the machine config pool:
+
[source,terminal]
----
$ oc create -f mcp-offloading.yaml
----

. Add nodes to the machine config pool. Label each node with the node role label of your pool:
+
[source,terminal]
----
$ oc label node worker-2 node-role.kubernetes.io/mcp-offloading=""
----

. Optional: To verify that the new pool is created, run the following command:
+
[source,terminal]
----
$ oc get nodes
----
+
--
.Example output
[source,terminal]
----
NAME       STATUS   ROLES                   AGE   VERSION
master-0   Ready    master                  2d    v1.23.3+d99c04f
master-1   Ready    master                  2d    v1.23.3+d99c04f
master-2   Ready    master                  2d    v1.23.3+d99c04f
worker-0   Ready    worker                  2d    v1.23.3+d99c04f
worker-1   Ready    worker                  2d    v1.23.3+d99c04f
worker-2   Ready    mcp-offloading,worker   47h   v1.23.3+d99c04f
worker-3   Ready    mcp-offloading,worker   47h   v1.23.3+d99c04f
----
--

. Add this machine config pool to the `SriovNetworkPoolConfig` custom resource:

.. Create a file, such as `sriov-pool-config.yaml`, with content like the following example:
+
[source,yaml]
----
apiVersion: sriovnetwork.openshift.io/v1
kind: SriovNetworkPoolConfig
metadata:
  name: sriovnetworkpoolconfig-offload
  namespace: openshift-sriov-network-operator
spec:
  ovsHardwareOffloadConfig:
    name: mcp-offloading <1>
----
<1> The name of your machine config pool for hardware offloading.

.. Apply the configuration:
+
[source,terminal]
----
$ oc create -f <SriovNetworkPoolConfig_name>.yaml
----
+
[NOTE]
=====
When you apply the configuration specified in a `SriovNetworkPoolConfig` object, the SR-IOV Operator drains and restarts the nodes in the machine config pool.

It might take several minutes for a configuration changes to apply.
=====


Updates 04-1-tipos-de-documentos-primarios.adoc

Auto commit by GitBook Editor

[[tipos-de-documentos-primarios]]
=== Tipos de documentos primarios

Como hemos comentado en el capítulo Introducción, _Documentos Primarios_ es el término que utiliza ATLAS.ti para hacer referencia a nuestras fuentes de datos, las cuales pueden ser de muy diferente tipo, pues podemos trabajar con una gran variedad de formatos: texto, imagen, audio, vídeo e incluso geo-referencias (Google Earth).

[[texto]]
==== Texto

Probablemente los documentos de texto serán los que utilizaremos más habitualmente, ya se trate de transcripciones de entrevistas, observaciones, diarios de campo, documentos institucionales, etc. El programa permite la utilización de una gran diversidad de formatos de archivo, aunque nosotros nos ocuparemos únicamente de los más habituales.

[[texto-plano]]
===== Texto plano

El formato más básico de texto que podemos utilizar es el texto plano, es decir, archivos con extensión “.txt” que presentan la ventaja de ser el formato más estándar y compatible entre procesadores de texto pero que al mismo tiempo tiene el inconveniente de que no permite ningún tipo de edición de estilo como negritas, cursivas, etc.

[[texto-enriquecido]]
===== Texto enriquecido

Se trata en este caso de archivos que permiten, al contrario de los anteriores, formatear el texto de forma que incluya desde negritas y cursivas hasta colores o imágenes. Aunque como decíamos, los tipos de
formatos de archivo (o procesadores de texto) que podemos utilizar son numerosos, tenemos en esta ocasión tres categorías básicas.

En primer lugar, podemos utilizar archivos creados con diferentes procesadores de texto (Microsoft Word o Libre Office p.ej.). En este caso los formatos de archivo recomendados son los “.doc” y “.rtf”,
aunque recomendamos la utilización de este último puesto que este tipo de documentos (y también los .txt) permiten que realicemos cambios sobre los mismos desde el interior del programa (ver <<04-2-asignar-documentos-primarios#edicion-de-documentos, Edición de documentos>>).

También podemos utilizar archivos en Portable Document Format (“.pdf”), que aunque estrictamente no se trate de archivos de texto enriquecido, en la práctica tienen las mismas características, puesto que pueden incluir cualquiera de las características editables permitidas por un procesador de textos. Por supuesto se trata de un formato que no será editable desde ATLAS.ti, pero que tiene la gran ventaja de que la visualización del documento será siempre la misma (algo que puede no ocurrir con otros formatos), lo que resulta fundamental en determinados tipos de análisis.

Por último, dentro de esta categoría de formatos enriquecidos encontramos los archivos “.htm”, es decir, documentos que hemos podido obtener directamente desde páginas web. La ventaja evidente de este tipo de archivos es que nos permite trabajar de una forma fácil con datos extraídos directamente desde la web, sin necesidad de que tengamos que realizar sobre los mismos ningún proceso de transformación o edición. Sin embargo, hay que tener en cuenta que no siempre obtendremos unos resultados idénticos a lo que podamos ver en las páginas originales, puesto que no se conservarán ni imágenes ni enlaces ni estilos. Por lo tanto, aunque se trata de una opción interesante consideramos que sólo es práctica para páginas web con formatos simples.

[[multimedia]]
==== Multimedia

Además de documentos textuales, podemos incluir como fuentes prácticamente cualquier otro tipo de datos, como imágenes fijas footnote:[Las imágenes pueden ser tanto documentos independientes como
elementos incluidos en los archivos de tipo _.doc_, _.rtf_ y _.pdf_.], audio e incluso vídeo. Esta variedad de fuentes de datos nos permitirá probablemente una mayor flexibilidad y riqueza en nuestro análisis. Una posibilidad que se nos abre con esta diversidad de formatos es la de utilizar la transcripción de una entrevista junto a su registro sonoro o audiovisual, de forma que, en caso de requerirlo, dispondremos de una información mucho más rica y precisa a la hora de realizar el análisis
que si sólo disponemos de la transcripción.

Una de las funcionalidades más interesantes del programa es la sincronización entre documentos primarios textuales y audiovisuales. ATLAS.ti nos permite, por ejemplo, sincronizar una transcripción con su
correspondiente archivo sonoro de forma que desde un punto concreto de la transcripción, podríamos acceder inmediatamente al mismo punto o momento en el documento de audio o vídeo (ver <<04-3-sincronizacion-audio-texto.adoc, Sincronización
audio-texto>>).

[[geo-referencias]]
==== Geo-referencias

Desde la versión 6 del programa, ATLAS.ti permite, literalmente, incluir "el mundo" como documento de datos. Aunque esta afirmación puede parecer exagerada, en la práctica es factible, puesto que podemos incorporar como documentos primarios mapas de __Google Earth__, en los que podemos, de la misma forma que hacemos con una imagen, seleccionar "ubicaciones significativas" para convertirlas en citas.

[[tipos-de-documentos-primarios]]
=== Tipos de documentos primarios

Como hemos comentado en el capítulo Introducción, _Documentos Primarios_ es el término que utiliza ATLAS.ti para hacer referencia a nuestras fuentes de datos, las cuales pueden ser de muy diferente tipo, pues podemos trabajar con una gran variedad de formatos: texto, imagen, audio, vídeo e incluso geo-referencias (Google Earth).

[[texto]]
==== Texto

Probablemente los documentos de texto serán los que utilizaremos más habitualmente, ya se trate de transcripciones de entrevistas, observaciones, diarios de campo, documentos institucionales, etc. El
programa permite la utilización de una gran diversidad de formatos de archivo, aunque nosotros nos ocuparemos únicamente de los más habituales.

[[texto-plano]]
===== Texto plano

El formato más básico de texto que podemos utilizar es el texto plano, es decir, archivos con extensión “.txt” que presentan la ventaja de ser el formato más estándar y compatible entre procesadores de texto pero que al mismo tiempo tiene el inconveniente de que no permite ningún tipo de edición de estilo como negritas, cursivas, etc.

[[texto-enriquecido]]
===== Texto enriquecido

Se trata en este caso de archivos que permiten, al contrario de los anteriores, formatear el texto de forma que incluya desde negritas y cursivas hasta colores o imágenes. Aunque como decíamos, los tipos de
formatos de archivo (o procesadores de texto) que podemos utilizar son numerosos, tenemos en esta ocasión tres categorías básicas.

En primer lugar, podemos utilizar archivos creados con diferentes procesadores de texto (Microsoft Word o Libre Office p.ej.). En este caso los formatos de archivo recomendados son los “.doc” y “.rtf”,
aunque recomendamos la utilización de este último puesto que este tipo de documentos (y también los .txt) permiten que realicemos cambios sobre los mismos desde el interior del programa (ver Edición de documentos en pág. 54).

También podemos utilizar archivos en Portable Document Format (“.pdf”), que aunque estrictamente no se trate de archivos de texto enriquecido, en la práctica tienen las mismas características, puesto que pueden incluir cualquiera de las características editables permitidaspor un procesador de textos. Por supuesto se trata de un formato que no será editable desde ATLAS.ti, pero que tiene la gran ventaja de que la visualización del documento será siempre la misma (algo que puede no ocurrir con otros formatos), lo que resulta fundamental en determinados tipos de análisis.

Por último, dentro de esta categoría de formatos enriquecidos encontramos los archivos “.htm”, es decir, documentos que hemos podido obtener directamente desde páginas web. La ventaja evidente de este tipo
de archivos es que nos permite trabajar de una forma fácil con datos extraídos directamente desde la web, sin necesidad de que tengamos que realizar sobre los mismos ningún proceso de transformación o edición. Sin embargo, hay que tener en cuenta que no siempre obtendremos unos resultados idénticos a lo que podamos ver en las páginas originales, puesto que no se conservarán ni imágenes ni enlaces ni estilos CSS. Por lo tanto, aunque se trata de una opción interesante consideramos que sólo es práctica para páginas web con formatos simples.

[[multimedia]]
==== Multimedia

Además de documentos textuales, podemos incluir como fuentes prácticamente cualquier otro tipo de datos, como imágenes fijas footnote:[Las imágenes pueden ser tanto documentos independientes como
elementos incluidos en los archivos de tipo __.doc, __.rtf y *.pdf.], audio e incluso vídeo. Esta variedad de fuentes de datos nos permitirá probablemente una mayor flexibilidad y riqueza en nuestro análisis. Una posibilidad que se nos abre con esta diversidad de formatos es la de utilizar la transcripción de una entrevista junto a su registro sonoro o audiovisual, de forma que, en caso de requerirlo, dispondremos de una información mucho más rica y precisa a la hora de realizar el análisis
que si sólo disponemos de la transcripción.

Una de las funcionalidades más interesantes del programa es la sincronización entre documentos primarios textuales y audiovisuales. ATLAS.ti nos permite, por ejemplo, sincronizar una transcripción con su
correspondiente archivo sonoro de forma que desde un punto concreto de la transcripción, podríamos acceder inmediatamente al mismo punto o momento en el documento de audio o vídeo (ver Sincronización
audio-texto, pág. 58).

[[geo-referencias]]
==== Geo-referencias

Desde la versión 6 del programa, ATLAS.ti permite, literalmente, incluir 'el mundo' como documento de datos. Aunque esta afirmación puede parecer exagerada, en la práctica es factible, puesto que podemos incorporar como documentos primarios mapas de __Google Earth__, en los que podemos, de la misma forma que hacemos con una imagen, seleccionar 'ubicaciones significativas' para convertirlas en citas.


Parent

Parent

= WSDL in brief
:toc: preamble
:sectanchors:
//works around awesome_bot bug that used to be published at github.com/dkhamsing/awesome_bot/issues/182.
:emptyattribute:

This document gives a _rough_ and _incomplete_ overview of WSDL 1.1. (WSDL 2.0 being not much supported at the moment.)

NOTE: The reader supposedly has basic knowledge of link:HTTP.adoc[HTTP], XML and link:SOAP.adoc[SOAP].

NOTE: The parts marked BP are complements to the spec given by WS-I BP (all versions from 1.0 to 2.0) (see <<refs>>).

////
TODO Find out how to escape bracket in [Public domain]; C++.
Link image to https://commons.wikimedia.org/wiki/File:WSDL_11vs20.png
Return value?
soapAction may be left undefined?
portType ⇐ binding ⇐ port ⇐ soap:address
////

== Overview
The Web Services Description Language (WSDL) spec defines a WSDL document. A WSDL document is an XML document that describes a web service, abstractly and concretely.

Except when mentioned otherwise, the elements this document refers to are XML elements with WSDL namespace [small]#(`\http://schemas.xmlsoap.org/wsdl/`)#.

.WSDL 1.1 (derived from work by Cristcost [Public domain], via Wikimedia Commons)
image:WSDL_11.png[Under a WSDL 1.1 document: an abstract description (types, message, portType), and a concrete description (binding, service)., float="left"]

* An abstract description indicates the operations that the web service provides, and the types it uses.
** The types it uses are defined under `types` and `message` elements.
** The operations are grouped together in `portType` elements. Though obscurely named, a `portType` simply represents a set of operations that coherently fit together (think about interfaces in Java, or abstract classes in C++).
** A WSDL file may define several such `portType` elements.
* A concrete description indicates how those abstract operations must be invoked, by linking them to an underlying exchange protocol, using a _link-type_.
** This is done using two elements: `binding`, that makes operations concrete (and specify how to encode types, …), and `service`, that defines concrete endpoints. (Those two elements may appear several times in a document.)
** A `service` contains a list of `port` elements. A `port`, or “endpoint”, indicates where the web service is to be reached.
** The elements used inside the `binding` and `service` elements depend on the underlying exchange protocol adopted by the web service being described, thus, depend on the chosen link-type.
* WSDL defines three link-types to make abstract descriptions concrete: SOAP, HTTP GET/POST and MIME. [small]#(It also defines an extension mechanism permitting to define more such link-types.)# This document only describes the SOAP link-type.

See https://www.w3.org/TR/2001/NOTE-wsdl-20010315#_wsdl[Example 1] (W3C).

== Internal references
Many WSDL elements admit an optional `name` attribute. XML Elements which admit a name may be referred to using a Qualified Name (QName). For example, the element `<portType name="StockQuotePortType">` defined in a namespace recognized under the prefix `tns` can be referred to by the QName `tns:StockQuotePortType` (see https://www.w3.org/TR/2001/NOTE-wsdl-20010315#_soap-e[Example 3]).

== Types and messages
XML schema are typically used to define types. The types to be used can be defined under `types`, using the `xsd:schema` element (thus XSD import mechanisms may be used in the usual manner). [small]#(WSDL also allows for other type systems.)#

The types are used to define messages, using `message` elements.

* A message consists of `part` elements.
* Each `part` has a name, and indicates either an `element` QName or a `type` QName (that must be defined in a schema under the `types` element, see above).
* How the parts are used depends on the link-type (see below). Typically, each part is a parameter of some operation or used as return value.

== Operations
An operation has a name, (usually) an input message, possibly an output message, and possibly fault messages. When output and fault messages are defined, it is to be understood that either the output or a fault will be returned, not both. Each of the `input`, `output` and `fault` elements designate the corresponding message using a QName.

== SOAP link-type
The SOAP link-type is used to complement an abstract web service description (consisting in `types`, `message` and `portType` elements) in order to make it a description of a SOAP web service. The SOAP binding used is the HTTP one (see link:SOAP.adoc#HTTP_binding[SOAP in brief]). [small]#(WSDL tolerates other SOAP bindings as well.)# Such a link is done using one `binding` element per `portType` to be defined as a component of the SOAP web service, and one `service` element.

The `binding` element is used to specify how abstract messages sent to or from an abstract interface (defined as a `portType`) are to be serialized as SOAP messages.

* The `binding` indicates, as its `type`, the QName of the `portType` it relates to (for example, `<binding type="tns:StockQuotePortType">`).
* The `binding` indicates that the link-type is SOAP by including as a sub-element the element `soap:binding`, where the `soap` prefix corresponds to the WSDL namespace for WSDL SOAP link-type [small]#(\http://schemas.xmlsoap.org/wsdl/soap12/)#.
* The `soap:binding` sub-element has a `transport` attribute, whose value is typically `\http://schemas.xmlsoap.org/soap/http`, to indicate that the HTTP binding is chosen as a SOAP binding.
* The `soap:binding` sub-element has a `style` attribute, whose value may be `document` (default) or `rpc`. [small]#(The `style` may also be set per-operation instead of for a whole `portType`.)#
* The `binding` element has one `operation` sub-element per operation that is to be reachable by SOAP. That sub-element specifies linking information for the _abstract_ operation with the same name within the related `portType`. Each such `operation` element has a `<soap:operation soapAction="uri"/>` sub-element that specifies the SOAP action to use to target that operation. Each `operation` also has sub-elements for each of the input, output and faults defined in the corresponding abstract operation, with for each of those a sub-element `soap:body` that, for `rpc` style, specifies a namespace (BP). Unbound parts are discouraged and should be ignored (BP http://ws-i.org/Profiles/BasicProfile-2.0-2010-11-09.html#R2209[R2209]{emptyattribute}).

Here is how to interpret these informations (BP).

With `document` style, there can be at most one message part in a message [small]#(unless `soap:body` `part` attribute is used)#. That part must be defined using the `element` attribute. It appears directly under the SOAP Body element.

With `rpc` style, each part is a parameter or a return value. Parts must be defined using the `type` attribute. The SOAP Body element will contain an operation wrapper element containing, for each part, a part wrapper element followed by the content of the part: `<opName><part1>…</part1><part2>…</part2></opName>`. The operation wrapper element namespace is the value of the namespace attribute of the `soap:body` element and its local name is either the name of the operation, for a SOAP Request, or the name of the operation suffixed with “Response”. The `name` and `type` attributes of `part` elements define the local name and type of the corresponding part wrapper. Part wrappers have no namespace.

Document style is http://ws-i.org/Profiles/BasicProfile-2.0-2010-11-09.html#Consistency_of_style_Attribute[encouraged].

BP mandates unique operation signatures, so that an endpoint may identify which operation is invoked based on the input message. The operation signature is the fully qualified name of the child element of the SOAP body [small]#(assuming no wsa:Action SOAP header blocks are used)#.

The `service` element consists in a set of `port` elements. Each `port` refers to a given `binding` element using a QName.
A sub-element of `port` gives the SOAP HTTP address to use to call the SOAP web service: `soap:address location="uri"`.

[[refs]]
== Refs
* W3C https://www.w3.org/TR/2001/NOTE-wsdl-20010315[WSDL 1.1] note; https://www.w3.org/Submission/2006/SUBM-wsdl11soap12-20060405/[WSDL 1.1 to SOAP 1.2] link-type
* WSDL https://www.w3.org/TR/?title=wsdl[Specifications] on W3C
* Web Services Interoperability (http://www.ws-i.org/[WS-I]) Basic Profile (BP) clarifies and modifies WSDL and related specifications to promote interoperability.
//* BP 2.0 corrected http://ws-i.org/profiles/basic/1.1/wsdl-2004-08-24.xsd[WSDL schema] TODO check 2.0 or 1.1?

== Supplementary details
What this document calls a link-type, namely the type of relation between the abstract and the concrete web service descriptions, is usually referred to as a _binding_. This presents risks of confusion with the WSDL `binding` element. Here the word “binding” is only used to refer to the element.

The WSDL element `import` can be used to import WSDL documents into other WSDL documents. (The spec also allows to use the WSDL `import` element to import XSD schemas, but this is now discouraged, see http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement16498504[BP 1.0] and later versions. The XSD import mechanism should be preferred.)

In WSDL 2.0, `portType` is called `interface`, `port` is called `endpoint`.

Each of the operation message (input, …) in a SOAP link-type has a `soap:body` whose `use` must (http://ws-i.org/Profiles/BasicProfile-2.0-2010-11-09.html#R2706[BP 2.0], 1.1) be `literal` (or left to the default, `literal`, BP 1.2). (`encoded` is not used any more, see this https://docs.microsoft.com/en-us/previous-versions/dotnet/articles/ms995710(v=msdn.10)[opinion]).

BP 2.0 does not require the sender to set soapAction in the HTTP header nor as part of the Content-Type header. Thus, it may not be relied upon.

An operation can be classified as: One-way (input only); Request-response (with input, output, and possibly fault messages); or other two types (that this document is not concerned with).

= WSDL in brief
:toc: preamble
:sectanchors:
//works around awesome_bot bug that used to be published at github.com/dkhamsing/awesome_bot/issues/182.
:emptyattribute:

This document gives a _rough_ and _incomplete_ overview of WSDL 1.1. (WSDL 2.0 being not much supported at the moment.)

NOTE: The reader supposedly has basic knowledge of link:HTTP.adoc[HTTP], XML and link:SOAP.adoc[SOAP].

NOTE: The parts marked BP are complements to the spec given by WS-I BP (all versions from 1.0 to 2.0) (see <<refs>>).

////
TODO Find out how to escape bracket in [Public domain]; C++.
Link image to https://commons.wikimedia.org/wiki/File:WSDL_11vs20.png
Return value?
soapAction may be left undefined?
portType ⇐ binding ⇐ port ⇐ soap:address
////

== Overview
The Web Services Description Language (WSDL) spec defines a WSDL document. A WSDL document is an XML document that describes a web service, abstractly and concretely.

Except when mentioned otherwise, the elements this document refers to are XML elements with WSDL namespace [small]#(`\http://schemas.xmlsoap.org/wsdl/`)#.

.WSDL 1.1, derived from work by Cristcost [Public domain\], via Wikimedia Commons
image:WSDL_11.png[Under a WSDL 1.1 document: an abstract description (types, message, portType), and a concrete description (binding, service)., float="left"]

* An abstract description indicates the operations that the web service provides, and the types it uses.
** The types it uses are defined under `types` and `message` elements.
** The operations are grouped together in `portType` elements. Though obscurely named, a `portType` simply represents a set of operations that coherently fit together (think about interfaces in Java, or abstract classes in C++).
** A WSDL file may define several such `portType` elements.
* A concrete description indicates how those abstract operations must be invoked, by linking them to an underlying exchange protocol, using a _link-type_.
** This is done using two elements: `binding`, that makes operations concrete (and specify how to encode types, …), and `service`, that defines concrete endpoints. (Those two elements may appear several times in a document.)
** A `service` contains a list of `port` elements. A `port`, or “endpoint”, indicates where the web service is to be reached.
** The elements used inside the `binding` and `service` elements depend on the underlying exchange protocol adopted by the web service being described, thus, depend on the chosen link-type.
* WSDL defines three link-types to make abstract descriptions concrete: SOAP, HTTP GET/POST and MIME. [small]#(It also defines an extension mechanism permitting to define more such link-types.)# This document only describes the SOAP link-type.

See https://www.w3.org/TR/2001/NOTE-wsdl-20010315#_wsdl[Example 1] (W3C).

== Internal references
Many WSDL elements admit an optional `name` attribute. XML Elements which admit a name may be referred to using a Qualified Name (QName). For example, the element `<portType name="StockQuotePortType">` defined in a namespace recognized under the prefix `tns` can be referred to by the QName `tns:StockQuotePortType` (see https://www.w3.org/TR/2001/NOTE-wsdl-20010315#_soap-e[Example 3]).

== Types and messages
XML schema are typically used to define types. The types to be used can be defined under `types`, using the `xsd:schema` element (thus XSD import mechanisms may be used in the usual manner). [small]#(WSDL also allows for other type systems.)#

The types are used to define messages, using `message` elements.

* A message consists of `part` elements.
* Each `part` has a name, and indicates either an `element` QName or a `type` QName (that must be defined in a schema under the `types` element, see above).
* How the parts are used depends on the link-type (see below). Typically, each part is a parameter of some operation or used as return value.

== Operations
An operation has a name, (usually) an input message, possibly an output message, and possibly fault messages. When output and fault messages are defined, it is to be understood that either the output or a fault will be returned, not both. Each of the `input`, `output` and `fault` elements designate the corresponding message using a QName.

== SOAP link-type
The SOAP link-type is used to complement an abstract web service description (consisting in `types`, `message` and `portType` elements) in order to make it a description of a SOAP web service. The SOAP binding used is the HTTP one (see link:SOAP.adoc#HTTP_binding[SOAP in brief]). [small]#(WSDL tolerates other SOAP bindings as well.)# Such a link is done using one `binding` element per `portType` to be defined as a component of the SOAP web service, and one `service` element.

The `binding` element is used to specify how abstract messages sent to or from an abstract interface (defined as a `portType`) are to be serialized as SOAP messages.

* The `binding` indicates, as its `type`, the QName of the `portType` it relates to (for example, `<binding type="tns:StockQuotePortType">`).
* The `binding` indicates that the link-type is SOAP by including as a sub-element the element `soap:binding`, where the `soap` prefix corresponds to the WSDL namespace for WSDL SOAP link-type [small]#(\http://schemas.xmlsoap.org/wsdl/soap12/)#.
* The `soap:binding` sub-element has a `transport` attribute, whose value is typically `\http://schemas.xmlsoap.org/soap/http`, to indicate that the HTTP binding is chosen as a SOAP binding.
* The `soap:binding` sub-element has a `style` attribute, whose value may be `document` (default) or `rpc`. [small]#(The `style` may also be set per-operation instead of for a whole `portType`.)#
* The `binding` element has one `operation` sub-element per operation that is to be reachable by SOAP. That sub-element specifies linking information for the _abstract_ operation with the same name within the related `portType`. Each such `operation` element has a `<soap:operation soapAction="uri"/>` sub-element that specifies the SOAP action to use to target that operation. Each `operation` also has sub-elements for each of the input, output and faults defined in the corresponding abstract operation, with for each of those a sub-element `soap:body` that, for `rpc` style, specifies a namespace (BP). Unbound parts are discouraged and should be ignored (BP http://ws-i.org/Profiles/BasicProfile-2.0-2010-11-09.html#R2209[R2209]{emptyattribute}).

Here is how to interpret these informations (BP).

With `document` style, there can be at most one message part in a message [small]#(unless `soap:body` `part` attribute is used)#. That part must be defined using the `element` attribute. It appears directly under the SOAP Body element.

With `rpc` style, each part is a parameter or a return value. Parts must be defined using the `type` attribute. The SOAP Body element will contain an operation wrapper element containing, for each part, a part wrapper element followed by the content of the part: `<opName><part1>…</part1><part2>…</part2></opName>`. The operation wrapper element namespace is the value of the namespace attribute of the `soap:body` element and its local name is either the name of the operation, for a SOAP Request, or the name of the operation suffixed with “Response”. The `name` and `type` attributes of `part` elements define the local name and type of the corresponding part wrapper. Part wrappers have no namespace.

Document style is http://ws-i.org/Profiles/BasicProfile-2.0-2010-11-09.html#Consistency_of_style_Attribute[encouraged].

BP mandates unique operation signatures, so that an endpoint may identify which operation is invoked based on the input message. The operation signature is the fully qualified name of the child element of the SOAP body [small]#(assuming no wsa:Action SOAP header blocks are used)#.

The `service` element consists in a set of `port` elements. Each `port` refers to a given `binding` element using a QName.
A sub-element of `port` gives the SOAP HTTP address to use to call the SOAP web service: `soap:address location="uri"`.

[[refs]]
== Refs
* W3C https://www.w3.org/TR/2001/NOTE-wsdl-20010315[WSDL 1.1] note; https://www.w3.org/Submission/2006/SUBM-wsdl11soap12-20060405/[WSDL 1.1 to SOAP 1.2] link-type
* WSDL https://www.w3.org/TR/?title=wsdl[Specifications] on W3C
* Web Services Interoperability (http://www.ws-i.org/[WS-I]) Basic Profile (BP) clarifies and modifies WSDL and related specifications to promote interoperability.
//* BP 2.0 corrected http://ws-i.org/profiles/basic/1.1/wsdl-2004-08-24.xsd[WSDL schema] TODO check 2.0 or 1.1?

== Supplementary details
What this document calls a link-type, namely the type of relation between the abstract and the concrete web service descriptions, is usually referred to as a _binding_. This presents risks of confusion with the WSDL `binding` element. Here the word “binding” is only used to refer to the element.

The WSDL element `import` can be used to import WSDL documents into other WSDL documents. (The spec also allows to use the WSDL `import` element to import XSD schemas, but this is now discouraged, see http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement16498504[BP 1.0] and later versions. The XSD import mechanism should be preferred.)

In WSDL 2.0, `portType` is called `interface`, `port` is called `endpoint`.

Each of the operation message (input, …) in a SOAP link-type has a `soap:body` whose `use` must (http://ws-i.org/Profiles/BasicProfile-2.0-2010-11-09.html#R2706[BP 2.0], 1.1) be `literal` (or left to the default, `literal`, BP 1.2). (`encoded` is not used any more, see this https://docs.microsoft.com/en-us/previous-versions/dotnet/articles/ms995710(v=msdn.10)[opinion]).

BP 2.0 does not require the sender to set soapAction in the HTTP header nor as part of the Content-Type header. Thus, it may not be relied upon.

An operation can be classified as: One-way (input only); Request-response (with input, output, and possibly fault messages); or other two types (that this document is not concerned with).


minor rephrasing in chronicles example

minor rephrasing in chronicles example

= The Dangerous & _Thrilling_ Documentation Chronicles: Based on True Events
Kismet Caméléon; Lazarus het_Draeke
v1.0, 2014-01-01: The first incarnation of The Documentation Chronicles.
:description: This story chronicles the inexplicable hazards and vicious beasts a \
team must conquer and vanquish on their journey to discovering the true power of \
Open Source.
:doctype: book
// Settings:
:experimental:
:icons: font
:listing-caption: Listing
:sectnums:
:toc:
:toclevels: 3
ifdef::backend-pdf[]
:title-logo-image: image:sample-banner.svg[pdfwidth=4.25in,align=center]
:source-highlighter: rouge
//:rouge-style: github
//:source-highlighter: pygments
//:pygments-style: tango
endif::[]
// URIs:
:wolper-uri: http://en.wikipedia.org/wiki/Wolpertinger

[abstract]
{description}

== It's a City Under Siege

This journey begins one late Monday afternoon at http://www.devoxx.be[Devoxx].
Our team needs coffee, _desperately_, but none of us dare open the theater doors...

During the first workshop, a script-happy warlock inadvertently released a legion of Wolpertingers!
To leave now would mean *code dismemberment and certain death*.

Behold -> the horror!

.Wolpertinger, stuffed
[.left.thumb]
image::wolpertinger.jpg[Wolpertinger,pdfwidth=50%,link=http://en.wikipedia.org/wiki/Wolpertinger]

You may not be familiar with these {wolper-uri}[ravenous beasts].
Trust us, they'll eat your shorts and suck loops from your code.
In light of this danger, we've searched high and wide for the security crew's defensive operations manual.
We can't find it and the DefOps{empty}footnote:[a portmanteau of “defensive” and “operations”] werewolves haven't returned from their rendezvous at Bier Central.
They've either eaten each other or fallen victim to the Wolpertingers roaming the streets of Antwerp.
Quick, hit kbd:[Ctrl,Alt,Backspace] or select menu:File[Quit] and let's bail out of here!

WARNING: Working with werewolves leads to howling and trying to train aggressive regular expressions with Pavlovian reinforcement.

_Weak light from the hallway trickled across the theater, chased by a distant scream._

=== Rendezvous Point

Come on, _Bier Central_.
Did you have to ask?
If you beat me there, I'll take a http://www.sintbernardus.be/stbernardusabt12.php?l=en[St. Bernardus Abt 12].

[#ravages]
== The Ravages of Writing

Crystalline XML tags relentlessly bombarded the theater.

.XML tags
[source,xml]
----
<author id="1">
  <personname>
    <firstname>Lazarus</firstname>
    <surname>het Draeke</surname>
  </personname>
</author>
----

Despite the assault, we were still attempting to draft an example of a defensive operation.

.DefOps Plan
====
Click btn:[Download Zip] to download the defensive operation plan bundle.

OMG!
Somebody please save us now!
I want my mum...and an extra-large double macchiato, please.
====

Unfortunaly, Lazarus and I had both come to the conclusion that we weren't going to get out of this without corrupted hardrives if we didn't locate caffeine within the next few hours.

=== A Recipe for Potion That Will Ensure You Win the Hearts of Developers

This potion for a sample document contains the following ingredients, which are listed in a very random, chaotically nested order.

.Ingredients for Potion that Demystifies Documents
* all the headings
** syntax highlighted source code
*** non-syntax highlighted source code or just a listing block
* quote block
** verse block
*** table with some cell formatting
**** sequential paragraphs
***** admonition blocks, but use them sparingly
*** bullet list with nesting
** numbered list with nesting
** definition list
*** sidebar
* example block
** block image (no inline images)
*** inline formatting in a paragraph
**** two fresh Burdockian leaves
***** They must be harvested by the light of the teal moons.

Are you square?

[square]
* one
* two
* three

What is there to do?

* [x] Done
* [ ] Next
* Who's counting?

==== Searching for Burdockian

.Steps for finding and preparing Burdockian leaves
. Locate dusty botany
.. Sneeze
... Sneeze some more
. Find section on Burdockian
.. Review its characteristics
... Take a picture of the diagram of its leaves
.... Don't rip out the picture like a troglodyte
..... Don't do it, I'm watching you
. Put on your hiking boots
. Freeze your butt off on the side of a mountain at midnight

Let's skip a few steps and start counting from 10.

[start=10]
. arabic (10)
.. loweralpha (a)
... lowerroman (i)
... lowerroman (ii)
... lowerroman (iii)
... lowerroman (iv)
.... upperalpha (A)
. arabic (11)

It's time for a top 5 list, made using the `reversed` option on an ordered list!

[%reversed]
. Stone Imperial Russian Stout
. Pliny the Elder
. Chimay Grande Réserve (Blue)
. St. Bernardus Abt 12
. Westvleteren 12 (XII)

How about a list with some terms?

* Fruits

Apple::
The round fruit of a tree of the rose family, which typically has thin red or green skin and crisp flesh.
Yes, I said _flesh_.

Pear::
A yellowish- or brownish-green edible fruit that is typically narrow at the stalk and wider toward the base, with sweet, slightly gritty flesh.
More flesh.
Mmmmm.

* Vegetables

Carrot::
An orange-colored root eaten as a vegetable.
Beware, it's a favorite of the Wolpertinger.

===== Are You Still Here?

.Move, move, move!
[CAUTION]
====
The Wolpertingers can smell your procrastination.
It's not their fault you can't find your boots.
====

====== Sigh...

TIP: Your boots are in your closet.

== Dawn on the Plateau

Lazarus was hanging from the bottom limb of a Burdockian tree, licking the bark.

[quote,Mark Tobey]
On pavements and the bark of trees I have found whole worlds.

"`If there are whole worlds on that bark, he just swallowed them,`" Kizmet replied.

[verse,The documentation attorneys]
____
No bark was harmed in the making of this potion.
    We're not so sure about a couple ants though.

        Nor those worlds...

     Crap, I smell an injunction.
____

We'd retrieved the leaves, but we'd obviously lost our minds in the process.

[verse]
Roses are +++red+++.
Violets are +++blue+++__-ish__.

== Words Seasoned with Power

_To tame_ the wild wolpertingers we needed to build a *charm*.
But **u**ltimate victory could only be won if we divined the *_true name_* of the __war__lock.

"`What kind of charm?`" Lazarus asked. "`An odoriferous one or a mineral one?`"
Kizmet shrugged. "`The note from Olaf's desk says '`wormwood and licorice,`' but these could be normal groceries for werewolves.`"

"`Well the H~2~O written on the security whiteboard could be part of a shopping list, but I don't think the local bodega also sells e = mc^2^,`" Lazarus replied.

"`Wait!`" Indigo plucked a small vial from her desk's top drawer and held it toward us.
The vial's label read '```e = mc^2^ *_the scent of science_* _smells like a genius_```'.

=== Can I Get Some `Code`?

[%hardbreaks]
Sure.
Have a listing block.

----
This is an example of a listing block.
The content inside is rendered as
 text.
----

But I'm not giving you any highlighting shazam just yet.

.What is a listing block?
****
Like literal blocks, the content in listing blocks is displayed exactly as you entered it.
Listing block content is rendered as `<pre>` text.

The `listing` style is applied to an element, such as a paragraph, by setting the `listing` attribute on that element.
****

Let's get our highlighting on!

<<<

Install Prawn:

 $ gem install prawn

Then create your first PDF document in Ruby!

.Generates a basic PDF document using Prawn
```ruby
require 'prawn' # <1>

Prawn::Document.generate 'output.pdf' do # <3>
  text 'Hello, World!' # <2>
end
```
<1> Imports Prawn library
<2> Adds text “Hello, World!” to first page
<3> Writes PDF to [file]_output.pdf_ after executing all statements

How about some source code that styles code? So meta!

```css
code {
  padding: 2px 4px;
  font-size: 90%;
  color: #c7254e;
  white-space: nowrap !important;
  background-color: #f9f2f4;
  border-radius: 4px;
}
```

Where could we go without some Java?
Naturally, some autosizing is necessary.

[source%autofit,java]
----
package org.javaee7.cdi.events;

import javax.annotation.PostConstruct;
import javax.enterprise.context.SessionScoped;
import javax.enterprise.event.Observes;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import javax.ws.rs.*;

/**
 * This session-scoped bean receives greeting strings from the event bus
 * and provides access to the collection of these greetings via a REST API.
 *
 * @author The Duke
 * @since 1.0
 */
@SessionScoped
public class GreetingReceiver implements EventReceiver, Serializable {

    private List<String> greetings;

    @PostConstruct
    void init() {
        this.greetings = new ArrayList<String>();
    }

    void receive(@Observes String greet) {
        this.greetings.add(greet);
    }

    @GET
    @Produces("application/json")
    public List<String> listAll(@QueryParam("start") Integer start, @QueryParam("max") Integer max) {
        int numGreetings = this.greetings.size();

        if (numGreetings == 0 || max == 0) {
            return Collections.<String>emptyList();
        }

        if (start == null) {
            start = 0;
        }

        if (max == null) {
            max = numGreetings;
        }

        return this.greetings.subList(start, Math.min(max + start, numGreetings));
    }

}
----

We already showed you an XML example in <<ravages>>.

I'll trade you a little table for some of that bark.

[cols=3,frame=topbot,grid=rows]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3

^m|Prefix the `{vbar}` with `{caret}` to center content horizontally
.<|Prefix the `{vbar}` with a `.` and `<` to align the content to the top of the cell
>|Prefix the `{vbar}` with `>` to align the content to the right horizontally

3+^.^e|This content spans all three columns (`3{plus}`) and is centered both horizontally (`{caret}`) and vertically (`.{caret}`) within the cell.
|===

Wait.
What?
Where is this story going?

`<span>`:: an html tag that makes me crazy

align:: something I never get going in the right direction.
Also has to do with my poor verbal communication skills

float::
style::
don't make me laugh

Does anyone have the time?

Tg lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborumj.

== Keeping It Together

On this page we have nested "`keep together`" logic.
The combined block will be shifted to the next page if there isn't room available on this one.

[verse]
First,
we
need
to
waste
several
lines
using
a
verse
to
push
the
next
block
to
its
breaking
point.

[NOTE]
.What happens if there is both a field and a method with the same name?
====
Back to the previous example, suppose that we have both a field and a method with the same name, as in:

.Java class with a field and method that share the same name
[source,java]
----
public class Foo {
  public String bar;

  public String bar() {
    return bar;
  }
}
----

*Golo resolves methods first, fields last.*
Hence, the following Golo code will resolve the `bar()` method, not the `bar` field:

.Golo picks the method over the field with the same name
[source,golo]
----
let foo = Foo()

foo: bar("baz") # <1>

println(foo: bar()) # <2>
----
<1> Writes the field
<2> Calls the `bar()` method
====

<<<

Here's a preview of how each heading level is rendered.

[discrete]
= Heading 1 (Level 0)

filler content

[discrete]
== Heading 2 (Level 1)

filler content

[discrete]
=== Heading 3 (Level 2)

filler content

[discrete]
==== Heading 4 (Level 3)

filler content

[discrete]
===== Heading 5 (Level 4)

filler content

[discrete]
====== Heading 6 (Level 5)

filler content

---

--
Here's some content inside an open block.
--

[appendix]
== Credits

.Brought to you with icon:heart[] by OpenDevise
[%header%footer,cols="2,2s,3",grid=rows,frame=topbot,width=75%,caption=]
|===
|Name
|Title
|Alias

|Sarah White
|President
|http://twitter.com/carbonfray[@carbonfray]

|Dan Allen
|Vice President
|http://twitter.com/mojavelinux[@mojavelinux]

3+^.e|Powered by Open Source
|===

= The Dangerous & _Thrilling_ Documentation Chronicles: Based on True Events
Kismet Caméléon; Lazarus het_Draeke
v1.0, 2014-01-01: The first incarnation of The Documentation Chronicles.
:description: This story chronicles the inexplicable hazards and vicious beasts a \
team must conquer and vanquish on their journey to discovering open source's true \
power.
:doctype: book
// Settings:
:experimental:
:icons: font
:listing-caption: Listing
:sectnums:
:toc:
:toclevels: 3
ifdef::backend-pdf[]
:title-logo-image: image:sample-banner.svg[pdfwidth=4.25in,align=center]
:source-highlighter: rouge
//:rouge-style: github
//:source-highlighter: pygments
//:pygments-style: tango
endif::[]
// URIs:
:wolper-uri: http://en.wikipedia.org/wiki/Wolpertinger

[abstract]
{description}

== It's a City Under Siege

This journey begins one late Monday afternoon at http://www.devoxx.be[Devoxx].
Our team needs coffee, _desperately_, but none of us dare open the theater doors...

During the first workshop, a script-happy warlock inadvertently released a legion of Wolpertingers!
To leave now would mean *code dismemberment and certain death*.

Behold -> the horror!

.Wolpertinger, stuffed
[.left.thumb]
image::wolpertinger.jpg[Wolpertinger,pdfwidth=50%,link=http://en.wikipedia.org/wiki/Wolpertinger]

You may not be familiar with these {wolper-uri}[ravenous beasts].
Trust us, they'll eat your shorts and suck loops from your code.
In light of this danger, we've searched high and wide for the security crew's defensive operations manual.
We can't find it and the DefOps{empty}footnote:[a portmanteau of “defensive” and “operations”] werewolves haven't returned from their rendezvous at Bier Central.
They've either eaten each other or fallen victim to the Wolpertingers roaming the streets of Antwerp.
Quick, hit kbd:[Ctrl,Alt,Backspace] or select menu:File[Quit] and let's bail out of here!

WARNING: Working with werewolves leads to howling and trying to train aggressive regular expressions with Pavlovian reinforcement.

_Weak light from the hallway trickled across the theater, chased by a distant scream._

=== Rendezvous Point

Come on, _Bier Central_.
Did you have to ask?
If you beat me there, I'll take a http://www.sintbernardus.be/stbernardusabt12.php?l=en[St. Bernardus Abt 12].

[#ravages]
== The Ravages of Writing

Crystalline XML tags relentlessly bombarded the theater.

.XML tags
[source,xml]
----
<author id="1">
  <personname>
    <firstname>Lazarus</firstname>
    <surname>het Draeke</surname>
  </personname>
</author>
----

Despite the assault, we were still attempting to draft an example of a defensive operation.

.DefOps Plan
====
Click btn:[Download Zip] to download the defensive operation plan bundle.

OMG!
Somebody please save us now!
I want my mum...and an extra-large double macchiato, please.
====

Unfortunaly, Lazarus and I had both come to the conclusion that we weren't going to get out of this without corrupted hardrives if we didn't locate caffeine within the next few hours.

=== A Recipe for Potion That Will Ensure You Win the Hearts of Developers

This potion for a sample document contains the following ingredients, which are listed in a very random, chaotically nested order.

.Ingredients for Potion that Demystifies Documents
* all the headings
** syntax highlighted source code
*** non-syntax highlighted source code or just a listing block
* quote block
** verse block
*** table with some cell formatting
**** sequential paragraphs
***** admonition blocks, but use them sparingly
*** bullet list with nesting
** numbered list with nesting
** definition list
*** sidebar
* example block
** block image (no inline images)
*** inline formatting in a paragraph
**** two fresh Burdockian leaves
***** They must be harvested by the light of the teal moons.

Are you square?

[square]
* one
* two
* three

What is there to do?

* [x] Done
* [ ] Next
* Who's counting?

==== Searching for Burdockian

.Steps for finding and preparing Burdockian leaves
. Locate dusty botany
.. Sneeze
... Sneeze some more
. Find section on Burdockian
.. Review its characteristics
... Take a picture of the diagram of its leaves
.... Don't rip out the picture like a troglodyte
..... Don't do it, I'm watching you
. Put on your hiking boots
. Freeze your butt off on the side of a mountain at midnight

Let's skip a few steps and start counting from 10.

[start=10]
. arabic (10)
.. loweralpha (a)
... lowerroman (i)
... lowerroman (ii)
... lowerroman (iii)
... lowerroman (iv)
.... upperalpha (A)
. arabic (11)

It's time for a top 5 list, made using the `reversed` option on an ordered list!

[%reversed]
. Stone Imperial Russian Stout
. Pliny the Elder
. Chimay Grande Réserve (Blue)
. St. Bernardus Abt 12
. Westvleteren 12 (XII)

How about a list with some terms?

* Fruits

Apple::
The round fruit of a tree of the rose family, which typically has thin red or green skin and crisp flesh.
Yes, I said _flesh_.

Pear::
A yellowish- or brownish-green edible fruit that is typically narrow at the stalk and wider toward the base, with sweet, slightly gritty flesh.
More flesh.
Mmmmm.

* Vegetables

Carrot::
An orange-colored root eaten as a vegetable.
Beware, it's a favorite of the Wolpertinger.

===== Are You Still Here?

.Move, move, move!
[CAUTION]
====
The Wolpertingers can smell your procrastination.
It's not their fault you can't find your boots.
====

====== Sigh...

TIP: Your boots are in your closet.

== Dawn on the Plateau

Lazarus was hanging from the bottom limb of a Burdockian tree, licking the bark.

[quote,Mark Tobey]
On pavements and the bark of trees I have found whole worlds.

"`If there are whole worlds on that bark, he just swallowed them,`" Kizmet replied.

[verse,The documentation attorneys]
____
No bark was harmed in the making of this potion.
    We're not so sure about a couple ants though.

        Nor those worlds...

     Crap, I smell an injunction.
____

We'd retrieved the leaves, but we'd obviously lost our minds in the process.

[verse]
Roses are +++red+++.
Violets are +++blue+++__-ish__.

== Words Seasoned with Power

_To tame_ the wild wolpertingers we needed to build a *charm*.
But **u**ltimate victory could only be won if we divined the *_true name_* of the __war__lock.

"`What kind of charm?`" Lazarus asked. "`An odoriferous one or a mineral one?`"
Kizmet shrugged. "`The note from Olaf's desk says '`wormwood and licorice,`' but these could be normal groceries for werewolves.`"

"`Well the H~2~O written on the security whiteboard could be part of a shopping list, but I don't think the local bodega also sells e = mc^2^,`" Lazarus replied.

"`Wait!`" Indigo plucked a small vial from her desk's top drawer and held it toward us.
The vial's label read '```e = mc^2^ *_the scent of science_* _smells like a genius_```'.

=== Can I Get Some `Code`?

[%hardbreaks]
Sure.
Have a listing block.

----
This is an example of a listing block.
The content inside is rendered as
 text.
----

But I'm not giving you any highlighting shazam just yet.

.What is a listing block?
****
Like literal blocks, the content in listing blocks is displayed exactly as you entered it.
Listing block content is rendered as `<pre>` text.

The `listing` style is applied to an element, such as a paragraph, by setting the `listing` attribute on that element.
****

Let's get our highlighting on!

<<<

Install Prawn:

 $ gem install prawn

Then create your first PDF document in Ruby!

.Generates a basic PDF document using Prawn
```ruby
require 'prawn' # <1>

Prawn::Document.generate 'output.pdf' do # <3>
  text 'Hello, World!' # <2>
end
```
<1> Imports Prawn library
<2> Adds text “Hello, World!” to first page
<3> Writes PDF to [file]_output.pdf_ after executing all statements

How about some source code that styles code? So meta!

```css
code {
  padding: 2px 4px;
  font-size: 90%;
  color: #c7254e;
  white-space: nowrap !important;
  background-color: #f9f2f4;
  border-radius: 4px;
}
```

Where could we go without some Java?
Naturally, some autosizing is necessary.

[source%autofit,java]
----
package org.javaee7.cdi.events;

import javax.annotation.PostConstruct;
import javax.enterprise.context.SessionScoped;
import javax.enterprise.event.Observes;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import javax.ws.rs.*;

/**
 * This session-scoped bean receives greeting strings from the event bus
 * and provides access to the collection of these greetings via a REST API.
 *
 * @author The Duke
 * @since 1.0
 */
@SessionScoped
public class GreetingReceiver implements EventReceiver, Serializable {

    private List<String> greetings;

    @PostConstruct
    void init() {
        this.greetings = new ArrayList<String>();
    }

    void receive(@Observes String greet) {
        this.greetings.add(greet);
    }

    @GET
    @Produces("application/json")
    public List<String> listAll(@QueryParam("start") Integer start, @QueryParam("max") Integer max) {
        int numGreetings = this.greetings.size();

        if (numGreetings == 0 || max == 0) {
            return Collections.<String>emptyList();
        }

        if (start == null) {
            start = 0;
        }

        if (max == null) {
            max = numGreetings;
        }

        return this.greetings.subList(start, Math.min(max + start, numGreetings));
    }

}
----

We already showed you an XML example in <<ravages>>.

I'll trade you a little table for some of that bark.

[cols=3,frame=topbot,grid=rows]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3

^m|Prefix the `{vbar}` with `{caret}` to center content horizontally
.<|Prefix the `{vbar}` with a `.` and `<` to align the content to the top of the cell
>|Prefix the `{vbar}` with `>` to align the content to the right horizontally

3+^.^e|This content spans all three columns (`3{plus}`) and is centered both horizontally (`{caret}`) and vertically (`.{caret}`) within the cell.
|===

Wait.
What?
Where is this story going?

`<span>`:: an html tag that makes me crazy

align:: something I never get going in the right direction.
Also has to do with my poor verbal communication skills

float::
style::
don't make me laugh

Does anyone have the time?

Tg lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborumj.

== Keeping It Together

On this page we have nested "`keep together`" logic.
The combined block will be shifted to the next page if there isn't room available on this one.

[verse]
First,
we
need
to
waste
several
lines
using
a
verse
to
push
the
next
block
to
its
breaking
point.

[NOTE]
.What happens if there is both a field and a method with the same name?
====
Back to the previous example, suppose that we have both a field and a method with the same name, as in:

.Java class with a field and method that share the same name
[source,java]
----
public class Foo {
  public String bar;

  public String bar() {
    return bar;
  }
}
----

*Golo resolves methods first, fields last.*
Hence, the following Golo code will resolve the `bar()` method, not the `bar` field:

.Golo picks the method over the field with the same name
[source,golo]
----
let foo = Foo()

foo: bar("baz") # <1>

println(foo: bar()) # <2>
----
<1> Writes the field
<2> Calls the `bar()` method
====

<<<

Here's a preview of how each heading level is rendered.

[discrete]
= Heading 1 (Level 0)

filler content

[discrete]
== Heading 2 (Level 1)

filler content

[discrete]
=== Heading 3 (Level 2)

filler content

[discrete]
==== Heading 4 (Level 3)

filler content

[discrete]
===== Heading 5 (Level 4)

filler content

[discrete]
====== Heading 6 (Level 5)

filler content

---

--
Here's some content inside an open block.
--

[appendix]
== Credits

.Brought to you with icon:heart[] by OpenDevise
[%header%footer,cols="2,2s,3",grid=rows,frame=topbot,width=75%,caption=]
|===
|Name
|Title
|Alias

|Sarah White
|President
|http://twitter.com/carbonfray[@carbonfray]

|Dan Allen
|Vice President
|http://twitter.com/mojavelinux[@mojavelinux]

3+^.e|Powered by Open Source
|===


Fix type on Clojutre start date

Fix type on Clojutre start date

= clojuTRE
clojuTRE
2017-09-02
:jbake-type: event
:jbake-edition: 2017
:jbake-link: http://clojutre.org/2017/
:jbake-location: Tampere, Finland
:jbake-start: 2017-09-02
:jbake-end: 2017-09-02

clojuTRE is a Clojure conference organized by http://www.metosin.fi/[Metosin]. The event has single track, late start, short talks (20 minutes and 5 minutes Q&A) and a funky after party for networking, discussions and draft beer. We welcome both newbies and seasoned Clojurists.

= clojuTRE
clojuTRE
2017-09-02
:jbake-type: event
:jbake-edition: 2017
:jbake-link: http://clojutre.org/2017/
:jbake-location: Tampere, Finland
:jbake-start: 2017-09-92
:jbake-end: 2017-09-02

clojuTRE is a free Clojure conference organized by http://www.metosin.fi/[Metosin]. The event has single track, late start, short talks (20 minutes and 5 minutes Q&A) and a funky after party for networking, discussions and draft beer. We welcome both newbies and seasoned Clojurists.


updated snippets

updated snippets

# Your snippets
#
# Atom snippets allow you to enter a simple prefix in the editor and hit tab to
# expand the prefix into a larger code block with templated values.
#
# You can create a new snippet in this file by typing "snip" and then hitting
# tab.
#
# An example CoffeeScript snippet to expand log to console.log:
#
# '.source.coffee':
#   'Console log':
#     'prefix': 'log'
#     'body': 'console.log $1'
#
# Each scope (e.g. '.source.coffee' above) can only be declared once.
#
# This file uses CoffeeScript Object Notation (CSON).
# If you are unfamiliar with CSON, you can read more about it in the
# Atom Flight Manual:
# http://flight-manual.atom.io/using-atom/sections/basic-customization/#_cson
'.source.asciidoc':
  'Cross Reference Inter-Doc':
    'prefix': 'xrefI'
    'body': '<<${1:path/to/wiki/page}#,${2:custom label text}>>'
  'Cross Reference Module':
    'prefix': 'xrefM'
    'body': 'xref:${1:target-page-filename}.adoc[${2:link text}]'
  'Cross Reference ROOT':
    'prefix': 'xrefR'
    'body': 'xref:ROOT:${1:target-page-filename}.adoc[${2:link text}]'
  'Admonition Block':
    'prefix': 'admonB'
    'body': """
    [${1:NOTE}${2:TIP}${3:IMPORTANT}${4:CAUTION}${5:WARNING}]
    ====
    $6
    ====
    $7
    """
  'Admonition Block with Title':
    'prefix': 'admonBwT'
    'body': """
    [${1:NOTE}${2:TIP}${3:IMPORTANT}${4:CAUTION}${5:WARNING}]
    .${6:Optional Title}
    ====
    $7
    ====
    $8
    """
  'Admonition Paragraph':
    'prefix': 'admonP'
    'body': """
    ${1:NOTE}${2:TIP}${3:IMPORTANT}${4:CAUTION}${5:WARNING}: $6
    """
  'Admonition Paragraph with Title':
    'prefix': 'admonPwT'
    'body': """
    .${1:Optional Title}
    ${2:NOTE}${3:TIP}${4:IMPORTANT}${5:CAUTION}${6:WARNING}: $7
    """

= Atom Snippets Page
:author: mitm
:revnumber: 2
:revdate: 2017-09-08T23:24:11.262Z
:relfileprefix: ../
:imagesdir: ..
:experimental:
ifdef::env-github,env-browser[:outfilesuffix: .adoc]

Edit this file to add snippets to the snippets.cson file for the
link:https://atom.io/[Atom editor]. To use these snippets just copy and paste
the text below into your snippets.cson file.

[source]
----
# Your snippets
#
# Atom snippets allow you to enter a simple prefix in the editor and hit tab to
# expand the prefix into a larger code block with templated values.
#
# You can create a new snippet in this file by typing "snip" and then hitting
# tab.
#
# An example CoffeeScript snippet to expand log to console.log:
#
# '.source.coffee':
#   'Console log':
#     'prefix': 'log'
#     'body': 'console.log $1'
#
# Each scope (e.g. '.source.coffee' above) can only be declared once.
#
# This file uses CoffeeScript Object Notation (CSON).
# If you are unfamiliar with CSON, you can read more about it in the
# Atom Flight Manual:
# http://flight-manual.atom.io/using-atom/sections/basic-customization/#_cson
'.source.asciidoc':
  'Inter-Doc Cross Reference':
    'prefix': 'xref'
    'body': '<<${1:path/to/wiki/page}#,${2:custom label text}>>'
  'Admonition Block':
    'prefix': 'admonB'
    'body': """
    [${1:NOTE}${2:TIP}${3:IMPORTANT}${4:CAUTION}${5:WARNING}]
    ====
    $6
    ====
    $7
    """
  'Admonition Block with Title':
    'prefix': 'admonBwT'
    'body': """
    [${1:NOTE}${2:TIP}${3:IMPORTANT}${4:CAUTION}${5:WARNING}]
    .${6:Optional Title}
    ====
    $7
    ====
    $8
    """
  'Admonition Paragraph':
    'prefix': 'admonP'
    'body': """
    ${1:NOTE}${2:TIP}${3:IMPORTANT}${4:CAUTION}${5:WARNING}: $6
    """
  'Admonition Paragraph with Title':
    'prefix': 'admonPwT'
    'body': """
    .${1:Optional Title}
    ${2:NOTE}${3:TIP}${4:IMPORTANT}${5:CAUTION}${6:WARNING}: $7
    """
----

== Snippets Explained

[cols="10, 45,45"*,options="header"]
|===

| Prefix
| Inserted Syntax
| Description

| xref
|`+<<path/to/wiki/page#,custom label text>>+`
| Inserts an `Inter-Document Cross Reference`.

| admonB
| [NOTETIPIMPORTANTCAUTIONWARNING] +
 ==== +
 ====
| Inserts an `Admonition Block` with the #NOTE# style highlighted. Use the kbd:[Tab] key to cycle to the next style
and kbd:[Backspace] off any unwanted style as you go. The final kbd:[Tab] will take you into the block.

| admonBwT
| [NOTETIPIMPORTANTCAUTIONWARNING] +
.Optional Title +
 ==== +
 ====
| Inserts an `Admonition Block` with title.

| admonP
| NOTETIPIMPORTANTCAUTIONWARNING:
| Inserts an `Admonition Paragraph` with the #NOTE# style highlighted. Use the kbd:[Tab] key to cycle to the next style
and kbd:[Backspace] off any unwanted style as you go. The final kbd:[Tab] will take you to the beginning of the paragraph.

| admonPwT
| .Optional Title +
NOTETIPIMPORTANTCAUTIONWARNING:
| Inserts an `Admonition Paragraph` with title.

|===


Add info on how to disable cleaner service (#64655) (#66704)

Co-authored-by: James Rodewig <d5d520df3f4564540f208acb32a86e5e141e7431@users.noreply.github.com>

Co-authored-by: Julien Guay <d252e019ad03df882bfd6f98f9fb6735823befe5@yahoo.fr>

[role="xpack"]
[testenv="basic"]
[[local-exporter]]
=== Local exporters

[IMPORTANT]
=========================
{metricbeat} is the recommended method for collecting and shipping monitoring
data to a monitoring cluster.

If you have previously configured legacy collection methods, you should migrate
to using {metricbeat} collection methods. Use either {metricbeat} collection or
legacy collection methods; do not use both.

Learn more about <<configuring-metricbeat>>.
=========================

The `local` exporter is the default exporter in {monitoring}. It routes data
back into the same (local) cluster. In other words, it uses the production
cluster as the monitoring cluster. For example:

[source,yaml]
---------------------------------------------------
xpack.monitoring.exporters.my_local_exporter: <1>
  type: local
---------------------------------------------------
<1> The exporter name uniquely defines the exporter, but it is otherwise unused.

This exporter exists to provide a convenient option when hardware is simply not
available. It is also a way for developers to get an idea of what their actions
do for pre-production clusters when they do not have the time or resources to
provide a separate monitoring cluster. However, this exporter has disadvantages
that impact the local cluster:

* All indexing impacts the local cluster and the nodes that hold the monitoring
indices' shards.
* Most collectors run on the elected master node. Therefore most indexing occurs
with the elected master node as the coordinating node, which is a bad practice.
* Any usage of {monitoring} for {kib} uses the local cluster's resources for
searches and aggregations, which means that they might not be available for
non-monitoring tasks.
* If the local cluster goes down, the monitoring cluster has inherently gone
down with it (and vice versa), which generally defeats the purpose of monitoring.

For the `local` exporter, all setup occurs only on the elected master node. This
means that if you do not see any monitoring templates or ingest pipelines, the
elected master node is having issues or it is not configured in the same way.
Unlike the `http` exporter, the `local` exporter has the advantage of accessing
the monitoring cluster's up-to-date cluster state. It can therefore always check
that the templates and ingest pipelines exist without a performance penalty. If
the elected master node encounters errors while trying to create the monitoring
resources, it logs errors, ignores that collection, and tries again after the
next collection.

The elected master node is the only node to set up resources for the `local`
exporter. Therefore all other nodes wait for the resources to be set up before
indexing any monitoring data from their own collectors. Each of these nodes logs
a message indicating that they are waiting for the resources to be set up.

One benefit of the `local` exporter is that it lives within the cluster and
therefore no extra configuration is required when the cluster is secured with
{stack} {security-features}. All operations, including indexing operations, that
occur from a `local` exporter make use of the internal transport mechanisms
within {es}. This behavior enables the exporter to be used without providing any
user credentials when {security-features} are enabled.

For more information about the configuration options for the `local` exporter,
see <<local-exporter-settings>>.

[[local-exporter-cleaner]]
==== Cleaner service

One feature of the `local` exporter, which is not present in the `http` exporter,
is a cleaner service. The cleaner service runs once per day at 01:00 AM UTC on
the elected master node.

The role of the cleaner service is to clean, or curate, the monitoring indices
that are older than a configurable amount of time (the default is `7d`). This
cleaner exists as part of the `local` exporter as a safety mechanism. The `http`
exporter does not make use of it because it could enable a single misconfigured
node to prematurely curate data from other production clusters that share the
same monitoring cluster.

In a dedicated monitoring cluster, you can use the cleaner service without
having to monitor the monitoring cluster itself. For example:

[source,yaml]
---------------------------------------------------
xpack.monitoring.collection.enabled: false <1>
xpack.monitoring.history.duration: 3d <2>
---------------------------------------------------

<1> Disables the collection of data on the monitoring cluster.
<2> Lowers the default history duration from `7d` to `3d`. The minimum value is
`1d`. This setting can be modified only when using a Gold or higher level
license. For the Basic license level, it uses the default of 7 days.

To disable the cleaner service, add a disabled local exporter:

[source,yaml]
----
xpack.monitoring.exporters.my_local.type: local <1>
xpack.monitoring.exporters.my_local.enabled: false <2>
----

<1> Adds a local exporter named `my_local`
<2> Disables the local exporter. This also disables the cleaner service.

[role="xpack"]
[testenv="basic"]
[[local-exporter]]
=== Local exporters

[IMPORTANT]
=========================
{metricbeat} is the recommended method for collecting and shipping monitoring
data to a monitoring cluster.

If you have previously configured legacy collection methods, you should migrate
to using {metricbeat} collection methods. Use either {metricbeat} collection or
legacy collection methods; do not use both.

Learn more about <<configuring-metricbeat>>.
=========================

The `local` exporter is the default exporter in {monitoring}. It routes data
back into the same (local) cluster. In other words, it uses the production
cluster as the monitoring cluster. For example:

[source,yaml]
---------------------------------------------------
xpack.monitoring.exporters.my_local_exporter: <1>
  type: local
---------------------------------------------------
<1> The exporter name uniquely defines the exporter, but it is otherwise unused.

This exporter exists to provide a convenient option when hardware is simply not
available. It is also a way for developers to get an idea of what their actions
do for pre-production clusters when they do not have the time or resources to
provide a separate monitoring cluster. However, this exporter has disadvantages
that impact the local cluster:

* All indexing impacts the local cluster and the nodes that hold the monitoring
indices' shards.
* Most collectors run on the elected master node. Therefore most indexing occurs
with the elected master node as the coordinating node, which is a bad practice.
* Any usage of {monitoring} for {kib} uses the local cluster's resources for
searches and aggregations, which means that they might not be available for
non-monitoring tasks.
* If the local cluster goes down, the monitoring cluster has inherently gone
down with it (and vice versa), which generally defeats the purpose of monitoring.

For the `local` exporter, all setup occurs only on the elected master node. This
means that if you do not see any monitoring templates or ingest pipelines, the
elected master node is having issues or it is not configured in the same way.
Unlike the `http` exporter, the `local` exporter has the advantage of accessing
the monitoring cluster's up-to-date cluster state. It can therefore always check
that the templates and ingest pipelines exist without a performance penalty. If
the elected master node encounters errors while trying to create the monitoring
resources, it logs errors, ignores that collection, and tries again after the
next collection.

The elected master node is the only node to set up resources for the `local`
exporter. Therefore all other nodes wait for the resources to be set up before
indexing any monitoring data from their own collectors. Each of these nodes logs
a message indicating that they are waiting for the resources to be set up.

One benefit of the `local` exporter is that it lives within the cluster and
therefore no extra configuration is required when the cluster is secured with
{stack} {security-features}. All operations, including indexing operations, that
occur from a `local` exporter make use of the internal transport mechanisms
within {es}. This behavior enables the exporter to be used without providing any
user credentials when {security-features} are enabled.

For more information about the configuration options for the `local` exporter,
see <<local-exporter-settings>>.

[[local-exporter-cleaner]]
==== Cleaner service

One feature of the `local` exporter, which is not present in the `http` exporter,
is a cleaner service. The cleaner service runs once per day at 01:00 AM UTC on
the elected master node.

The role of the cleaner service is to clean, or curate, the monitoring indices
that are older than a configurable amount of time (the default is `7d`). This
cleaner exists as part of the `local` exporter as a safety mechanism. The `http`
exporter does not make use of it because it could enable a single misconfigured
node to prematurely curate data from other production clusters that share the
same monitoring cluster.

In a dedicated monitoring cluster, the cleaning service can be used without
having to also monitor the monitoring cluster. For example:

[source,yaml]
---------------------------------------------------
xpack.monitoring.collection.enabled: false <1>
xpack.monitoring.history.duration: 3d <2>
---------------------------------------------------
<1> Disable the collection of data on the monitoring cluster.
<2> Lower the default history duration from `7d` to `3d`. The minimum value is
`1d`. This setting can be modified only when using a Gold or higher level
license. For the Basic license level, it uses the default of 7 days.


DOCS Correct audit emit_node_id default value as false (#56995)

Since version 7, the `xpack.security.audit.logfile.emit_node_id` setting defaults
to `false`, yet the docs say otherwise. This commit fixes that.

[role="xpack"]
[[auditing-settings]]
=== Auditing security settings
++++
<titleabbrev>Auditing settings</titleabbrev>
++++

You configure security auditing settings in the `elasticsearch.yml` configuration file
on each node in the cluster. For more information, see <<enable-audit-logging>>.

[[general-audit-settings]]
==== General Auditing Settings

`xpack.security.audit.enabled`::
Set to `true` to enable auditing on the node. The default value is `false`.
This puts the auditing events in a dedicated file named `<clustername>_audit.json`
on each node.

[[event-audit-settings]]
==== Audited Event Settings

The events and some other information about what gets logged can be controlled
by using the following settings:

`xpack.security.audit.logfile.events.include`::
Specifies which events to include in the auditing output. The default value is:
`access_denied, access_granted, anonymous_access_denied, authentication_failed,
connection_denied, tampered_request, run_as_denied, run_as_granted`.

`xpack.security.audit.logfile.events.exclude`::
Excludes the specified events from the output. By default, no events are
excluded.

`xpack.security.audit.logfile.events.emit_request_body`::
Specifies whether to include the request body from REST requests on certain
event types such as `authentication_failed`. The default value is `false`.
+
--
IMPORTANT: No filtering is performed when auditing, so sensitive data may be
audited in plain text when including the request body in audit events.
--

[[node-audit-settings]]
==== Local Node Info Settings

`xpack.security.audit.logfile.emit_node_name`::
Specifies whether to include the <<node.name,node name>> as a field in
each audit event. The default value is `false`.

`xpack.security.audit.logfile.emit_node_host_address`::
Specifies whether to include the node's IP address as a field in each audit event.
The default value is `false`.

`xpack.security.audit.logfile.emit_node_host_name`::
Specifies whether to include the node's host name as a field in each audit event.
The default value is `false`.

`xpack.security.audit.logfile.emit_node_id`::
Specifies whether to include the node id as a field in each audit event.
This is available for the new format only. That is to say, this information
does not exist in the `<clustername>_access.log` file.
Unlike <<node.name,node name>>, whose value might change if the administrator
changes the setting in the config file, the node id will persist across cluster
restarts and the administrator cannot change it.
The default value is `true`.

[[audit-event-ignore-policies]]
==== Audit Logfile Event Ignore Policies

These settings affect the <<audit-log-ignore-policy,ignore policies>>
that enable fine-grained control over which audit events are printed to the log file.
All of the settings with the same policy name combine to form a single policy.
If an event matches all of the conditions for a specific policy, it is ignored
and not printed.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.users`::
A list of user names or wildcards. The specified policy will
not print audit events for users matching these values.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.realms`::
A list of authentication realm names or wildcards. The specified policy will
not print audit events for users in these realms.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.roles`::
A list of role names or wildcards. The specified policy will
not print audit events for users that have these roles. If the user has several
roles, some of which are *not* covered by the policy, the policy will
*not* cover this event.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.indices`::
A list of index names or wildcards. The specified policy will
not print audit events when all the indices in the event match
these values. If the event concerns several indices, some of which are
*not* covered by the policy, the policy will *not* cover this event.

[role="xpack"]
[[auditing-settings]]
=== Auditing security settings
++++
<titleabbrev>Auditing settings</titleabbrev>
++++

You configure security auditing settings in the `elasticsearch.yml` configuration file
on each node in the cluster. For more information, see <<enable-audit-logging>>.

[[general-audit-settings]]
==== General Auditing Settings

`xpack.security.audit.enabled`::
Set to `true` to enable auditing on the node. The default value is `false`.
This puts the auditing events in a dedicated file named `<clustername>_audit.json`
on each node.

[[event-audit-settings]]
==== Audited Event Settings

The events and some other information about what gets logged can be controlled
by using the following settings:

`xpack.security.audit.logfile.events.include`::
Specifies which events to include in the auditing output. The default value is:
`access_denied, access_granted, anonymous_access_denied, authentication_failed,
connection_denied, tampered_request, run_as_denied, run_as_granted`.

`xpack.security.audit.logfile.events.exclude`::
Excludes the specified events from the output. By default, no events are
excluded.

`xpack.security.audit.logfile.events.emit_request_body`::
Specifies whether to include the request body from REST requests on certain
event types such as `authentication_failed`. The default value is `false`.
+
--
IMPORTANT: No filtering is performed when auditing, so sensitive data may be
audited in plain text when including the request body in audit events.
--

[[node-audit-settings]]
==== Local Node Info Settings

`xpack.security.audit.logfile.emit_node_name`::
Specifies whether to include the <<node.name,node name>> as a field in
each audit event.
The default value is `true`.

`xpack.security.audit.logfile.emit_node_host_address`::
Specifies whether to include the node's IP address as a field in each audit event.
The default value is `false`.

`xpack.security.audit.logfile.emit_node_host_name`::
Specifies whether to include the node's host name as a field in each audit event.
The default value is `false`.

`xpack.security.audit.logfile.emit_node_id`::
Specifies whether to include the node id as a field in each audit event.
This is available for the new format only. That is to say, this information
does not exist in the `<clustername>_access.log` file.
Unlike <<node.name,node name>>, whose value might change if the administrator
changes the setting in the config file, the node id will persist across cluster
restarts and the administrator cannot change it.
The default value is `true`.

[[audit-event-ignore-policies]]
==== Audit Logfile Event Ignore Policies

These settings affect the <<audit-log-ignore-policy,ignore policies>>
that enable fine-grained control over which audit events are printed to the log file.
All of the settings with the same policy name combine to form a single policy.
If an event matches all of the conditions for a specific policy, it is ignored
and not printed.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.users`::
A list of user names or wildcards. The specified policy will
not print audit events for users matching these values.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.realms`::
A list of authentication realm names or wildcards. The specified policy will
not print audit events for users in these realms.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.roles`::
A list of role names or wildcards. The specified policy will
not print audit events for users that have these roles. If the user has several
roles, some of which are *not* covered by the policy, the policy will
*not* cover this event.

`xpack.security.audit.logfile.events.ignore_filters.<policy_name>.indices`::
A list of index names or wildcards. The specified policy will
not print audit events when all the indices in the event match
these values. If the event concerns several indices, some of which are
*not* covered by the policy, the policy will *not* cover this event.