WMarkDown/WMD/es/doc/modules/custom_parameters.w.md

[[post_data {
    "author" : "KyMAN",
    "since" : 20210515,
    "version" : 20210519
}]]
# Parámetros customizados

Los parámetros customizados son parámetros que se identifican mediante una encapsulación de doble
corchete, siguiendo la idea de encapsulación de parámetros preprogramados de MediaWiki. Dichos
parámetros dan nuevas funcionalidades al entorno del WMarkDown las cuales nombraremos a
continuación.

> **IMPORTANTE**: Aunque sintácticamente sean iguales, e incluso se consideren Parámetros
Customizados, las inclusiones y los elementos multimedia no  están integrados dentro del fichero de
Parámetros Customizados, considerados como otros módulos con la misma sintaxis. Es importante tener
esto en cuenta por el hecho de que han de estar ordenados según prioridad para evitar la solapación
en la configuración.

## post_data

El "post_data" es un parámetro que se usa para establecer una información previa de un fichero,
aunque también puede ser para un artículo o fragmento de un artículo, aunque por el resultado lo
aconsejamos únicamente para encabezar un fichero que en sí sea un artículo completo. Básicamente da
la información de los participantes del fichero como autores del mismo, la fecha de creación y la
última fecha de modificación, los cuales se identifican dentro de un JSON con las siguientes llaves
de diccionario:

- **author**: Autor/es y participantes del artículo o fichero.
- **since**: Fecha de creación.
- **version**: Última fecha de modificación.

> No se usan las fechas de los metadatos de los ficheros por el hecho de que dependen del OS y éstos
pueden ir condicionados a la creación por descarga al ser un recurso compartido con Git, entre otras
cosas.

Las fechas tendrán el formato "YYYYMMDD", donde "YYYY" es el año con cuatro dígitos; el "MM" es el
número del mes con 2 dígitos obligatorios; y "DD" que es el día del mes con dos dígitos
oblitagorios.

En caso de que no se halla especificado el "author", éste se pondrá como desconocido ("Unknown" o el
especificado en la configuración); por otro lado, si no se le especifica el "since" éste será
substituído por la fecha de compilación del HTML; y finalmente, si no se le especifica el "version",
éste será substituído por el "since".

> Como conclusión, podemos exponer que ningún parámetro es obligatorio.

Un ejemplo de éste podría ser el siguiente:

```md
[[post_data {
    "author" : "KyMAN",
    "since" : 20210511,
    "version" : 20210513
}]]
```

Este componente personalizado se suele poner al principio del documento, encima del título que
encabeza el mismo.

## html_data

El HTML data es un parámetro que consta de un diccionario JSON que contiene las variables que se le
especifiquen al HTML de compilación donde se integrará la información. Esto permite tener en cada
página HTML generada, su SEO META configurado de forma sencilla y customizada. Dichos parámetros
pueden variar según el HTML utilizado al gusto del desarrollador o usuario que gestione la
documentación o página o páginas Web.

> Este complemento no tendrá visualización alguna sobre el HTML final.

Un ejemplo de este componente podría ser el siguiente:

```md
[[html_data {
    "title" : "WMarkDown - Parámetros customizados",
    "url" : "https://wmarkdown.k3y.pw/doc/modules/custom_parameters.html",
    "author" : "Tarsier, KyMAN",
    "since" : 20210515,
    "version" : 20210515,
    "key_words" : "Whalers,MarkDown,MediaWiki,WMarkDown,módulo,parámetros,custom,personalizado,include,inclusión,import,importación",
    "description" : "ÇMódulo de parámetros customizados.",
    "project" : "WMarkDown",
    "logo" : "https://wmarkdown.k3y.pw/images/wmarkdown.png"
}]]
```

Dicho componente se suele poner al final del documento, aunque puede ser puesto en cualquier otra
parte del mismo.

> **IMPORTANTE**: Cualquier llave de parámetro sobreescribirá a los originales, por ejemplo, por
defecto los títulos se conforman con le nombre del proyecto y el texto de la primera cabecera dada
por el fichero. En el ejemplo expuesto, se subsituye el título por el dado específicamente en este
parámetro customizado.

## include

El parámetro customizado "include" permite incluír un fichero externo el cual se compilará y se
pondrá al nivel de cabeceras actual si no se le especifica previamente a partir del parámetro
customizado "header_level" (Ver en el siguiente punto). Pueden existir anidamientos de elementos
includos, por lo cual hay que prestar especial atención a aquellos anidamientos que puedan ser
recursivos infinitamente. Un ejemplo de inclusión puede ser el siguiente:

```md

Estamos a nivel 0 de cabecera, por tanto, a la siguiente inclusión no se le añadirá ningún nivel a
las cabeceras.

[[include PATH1]]

# Nivel 1

Estamos en el nivel 1 y a la siguiente inclusión se le añadirá un nivel más a cada cebecera que
contenga.

[[include PATH2]]

Ahora estamos en el nivel de la última cabecera que teníamos en el PATH2, y será el nivel que se le
sumará a cada cabecera de la siguiente inclusión.

[[include PATH3]]

# Nivel 1

Volvimos al nivel 1, por tanto, solo se le sumará un nivel a la siguiente inclusión.

[[include PATH4]]

```

## header_level

Este parámetro customizado permite cambiar el nivel de cabeceras con el que se está trabajando,
permitiendo, a partir de dicho punto, cambiar el nivel de las mismas según el valor que se le
establezca. Éste tiene dos formas de establecerse:

- A partir de un valor numérico entero sin signo, el cual establece al nivel al cual se irá
directamente, siendo 0 el más bajo.
- A partir de un valor numérico entero con signo más para añadir sobre el nivel actual, o menos para
reducir sobre el nivel actual.

### Inclusión heredada

La inclusión heredada es la que se explica en el apartado del parámetro customizado "include", donde
vemos en el ejemplo que los niveles de las cabeceras aumentan automáticamente según hereden del
nivel donde se encuentren. No hace falta especificar nivel de forma forzada mediante "header_level".

### Inclusión forzada

La inclusión forzada hace referencia a que se le da un valor numérico entero sin signo, que
representa el nivel íntegro al que se quiere mover todo, independientemente de la herencia, por
ejemplo:

```md

## Nivel 2

Estamos en el nivel 2 de herencia, y queremos incluir un fichero en el nivel 4 de forma forzada.
Para ello lo haremos de la siguiente forma:

[[header_level 4]]
[[include PATH1]]

Para volver al nivel 2 de nuevo simplemente hemos de establecer aquí lo siguiente:

[[header_level 2]]

```

Como podemos ver en el ejemplo, este parámetro customizado nos permite forzar la inclusión de un
fichero en un nivel concreto y luego volver a otro nivel, en el caso del ejemplo, al nivel 2 que era
de donde partía.

### Inclusión añadida

La inclusión añadida permite desplazar el nivel de las cabeceras X niveles a partir de encabezar el
nivel con el signo "+" para añadir o el signo "-" para disminuir. Por ejemplo:

```md

## Nivel 2

Nos encontramos en el nivel 2. Como este fichero puede ser includo y heredado de otros niveles y
queremos reducir 2 niveles para volver al nivel 0 de este fichero para la inclusión del siguiente
fichero podemos hacerlo así:

[[header_level -2]]
[[include PATH1]]

Sin embargo, si queremos recuperar la posición anterior no vamos a poder posiblemente pues si
ponemos +2, será que aumenta 2 posiciones a partir de la última cabecera del PATH1. Es muy
importante tenerlo encuenta.

```

## data_dictionary

El parámetro customizado "data_dictionary" nos permite crear un diccionario de conceptos contra
palabras o estructuras de texto que puedan aparecer en la documentación y con ello, generar una
definición de las mismas, ya sea como referencia donde se coloque el diccionario; o por el texto,
creando un pequeño elemento HTML que hace que cuando el usuario ponga el puntero encima de la
palabra o palabras en cuestión, despliegue una pequeña capa con una descripción y vinculación de las
fuentes o referencias, ya sea para contrastar como para adquirir más información.

Este elemento se tratará en HTML como un INPUT HIDDEN, el cual será interpretado a nivel cliente
sobre JavaScript y generará tanto el diccionario con su buscador, como le dará la función de mostrar
definición y fuentes a los elementos en la documentación en general.

Este parámetro customizado se mezclará con otros "data_dictionary" que puedan existir en la
documentación por lo que se desaconseja encarecidamente el uso de más de uno de estos elementos,
aunque no por ello esté prohibido su uso, permitiendo incluso actualizar los datos de diccionario
que ya halla.

Un ejemplo de funcionamiento podría ser el siguiente:

```md

## Diccionario

[[data_dictionary {
    "dictionary" : [{
        "pattern" : "/\\bky ?man\\b/i",
        "result" : "KyMAN",
        "description" : [
            "Programador. Trabaja los lenguajes Python, PHP, JavaScript, CSS (CSS y SCSS), SQL ",
            "(SQLite, MySQL (MariaDB) y SQL Server)"
        ],
        "links" : [
            "https://git.k3y.pw/KyMAN/",
            "https://git.a3do.net/KyMAN/",
            "https://www.youtube.com/channel/UCCAWOt-AxTyAiFWBgyb3X9Q"
        ]
    }, {
        "pattern" : "/\\bmark ?down\\b/i",
        "result" : "MarkDown",
        "description" : [
            "Simple lenguaje de marcas de texto para documentar. se suele usar en proyectos Git."
        ],
        "links" : [
            "https://es.wikipedia.org/wiki/Markdown",
            "https://markdown.es/"
        ]
    }, {
        "pattern" : "/\\bmedia ?wiki\\b/i",
        "result" : "MediaWiki",
        "description" : [
            "CMS PHP muy extendido para gestionar información y documentación con un pequeño ",
            "lenguaje de marcas de texto para su procesamiento. Como referencias tendríamos ",
            "Wikipedia, HiddenWiki, etc."
        ],
        "links" : [
            "https://www.mediawiki.org/",
            "https://es.wikipedia.org/wiki/MediaWiki"
        ]
    }, {
        "pattern" : ["/\\bwmarkdown\\b/i", "/\\bwmd\\b/i"],
        "result" : ["WMarkDown", "WMD"],
        "description" : [
            "Pequeño sistema para documentación de proyectos que mezcla los lenguajes de marcas ",
            "de texto MarkDown y MediaWiki con HTML y texto plano."
        ],
        "links" : [
            "https://wmarkdown.k3y.pw/",
            "https://git.k3y.pw/Whalers/WMarkDown"
        ]
    }]
}]]

```

Como podemos ver en el ejemplo, este parámetro es un diccionario JSON con una única entrada,
"dictionary", la cual contendrá un Array de diccionarios los cuales tienen los siguientes elementos:

- **pattern**: Patrón o patrones de búsqueda.
- **result**: Resultado o resultados contra el o los patrones.
- **description**: Descripción o definición.
- **links**: Referencias o fuentes mediante URL.

Los patrones y los resultados han de tener el mismo número de elementos, es decir, si se le dan 2
patrones de búsqueda ha de haber 2 resultados, pues el sistema entiende que cada patrón es para una
posible forma de llamar al elemento diferente. Los resultados permiten, en conjunto con el patrón,
corregir posibles errores de escritura de cualquier texto que se le dé a partir del patrón regular.

Con respecto a las imágenes que representan el o los links que puedan estar representadas por
defecto en las capas que aparecen para definir un texto cuando le puntero se le pone encima están
definidas en SCSS a partir del atributo "data-site" que contiene cada Link, usando la raíz de la
página para establecer una imagen icónica del sitio Web al que se le hace referencia.

> **IMPORTANTE**: Se desaconseja el uso de este parámetro por dos motivos: el primero es la
limitación de PHP cara la limitación del número de caracteres que tiene a la hora de procesar dicho
String en un patrón regular; y la segunda es que actualmente hay una alternativa a dicho sistema que
viene siendo en JS la cual implementaría el diccionario desde JavaScript, en el propio constructor
del objeto WMarkDown. La solución puesta solventa muchos problemas de esta versión, sin embargo,
quita posicionamiento SEO al ser contenido dinámico autogenerado en el cliente y no gestionado
mediante Tags, pero por renta cuenta mejor el uso de dicha solución.

## Multimedia

Es un Parámetro Customizado que nos permite incluir elementos Multimedia a partir de varios nombres
los cuales son: "image", "images", "audio", "audios", "video", "videos" y "embed". Por la
complejidad y el tamaño de los Scripts para gestionar dichos elementos, éstos pertenecen a otro
fichero como un módulo independiente, con su patrón de búsqueda, sin embargo, se considerarán
Parámetros Customizados. Para más información, ir a la sección Multimedia donde se hablará de todo
este Parámetro Customizado como si fuera un módulo independiente por la extensión que supone.

> Se planea también agregar un nuevo sistema llamado Slider con nombre "slider" que permite la
creación de un Slider de cualquiera de los elementos que pertenecen a la multimedia.

## wdictionaries

El WDictionaries es como el **data_dictionary** pero con la diferencia de que coge los diccionarios de forma remota a partir de la siguiente estructura:

```md

[[header_level 0]]
<!-- [[wdictionaries "CABECERA" URLs]] -->
[[wdictionaries "Diccionario de prueba" https://wdictionaries.k3y.pw/?es/common,digital]]

```

En este caso tenemos el nombre de cabecera que queramos ponerle al buscador de términos del
diccionario, donde en el HTML comentado llamamos _"CABECERA"_; a continuación tenemos los enlaces
separados entre sí por espacios, tabulaciones, saltos de línea y/o retornos de carro.

> **IMPORTANTE**: El WDictionaries es un proyecto externo al WMarkDown, aunque éste naciera
principalmente para el uso dentro del WMarkDown, éste tiene su Web donde se explica su
funcionamiento e implementación. Además, el WMarkDown a nivel de JS puede implementar dichos
diccionarios sin que se use un WMD, eliminando el fallo a la hora de representar más de un
diccionario dentro de estos ficheros.

A continuación ponemos un ejemplo de carga de más de un fichero, por ejemplo, de diversos ficheros
JSON para hacer uso de la caché OnLine y del navegador.

```md

[[header_level 0]]
[[wdictionaries "Diccionario de prueba"
    https://wdictionaries.k3y.pw/json/es/common.json
    https://wdictionaries.k3y.pw/json/es/digital.json
    https://wdictionaries.k3y.pw/json/es/users.json
]]

```

> **NOTA**: El texto de la cabecera puede ser una única palabra sin comillas o un conjunto de ellas
encapsuladas entre comillas.

> **NOTA**: Recomendamos encarecidamente el no utilizar dicho Componente Customizado y usar el
existente en el entorno cliente contra el propio constructor del WMarkDown en JS.

## wmonitor

El WMonitor es un pequeño subsistema del WMarkDown el cual permite establecer un punto de monitoreo
de visualizaciones, visitas, likes/dislikes y comentarios contra el cliente. Es importante destacar
que funcionará sobre el entorno cliente aunque éste se establezca en el entorno del WMD. Para
implementarlo requerimos de nombrar a este Componente Customizado y a continuación, poner un texto
indicativo al cual hace referencia. Dicho texto ha de ser único para cada WMonitor, pudiéndose dar
el caso de poder compartir dichos datos con otros puntos, pero se perdería la información real de
visualizaciones y likes/dislikes de ambos individualmente y pudiendon llevar a engaño visual de la
información. Un ejemplo de implementación sobre una cabecera podría ser el siguiente:

<table style="width:100%;">
    <thead>
        <tr>
            <th style="width:50%;">WMarkDown</th>
            <th style="width:50%;">Resultado</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>

```md
[[post_data {
    "author" : "KyMAN",
    "since" : 202106029,
    "version" : 202106029
}]]
# Prueba del WMonitor
[[wmonitor prueba_del_wmonitor]]

Texto que queramos ponerle al cuerpo de este artículo.

```

            </td>
            <td>

                [[post_data {
                    "author" : "KyMAN",
                    "since" : 202106029,
                    "version" : 202106029
                }]]
                <h1>Prueba del WMonitor</h1>
                [[wmonitor prueba_del_wmonitor]]

                Texto que queramos ponerle al cuerpo de este artículo.

            </td>
        </tr>
    </tbody>
</table>

> **NOTA**: El texto indicativo puede ser una palabra sin comillas o varias encapsuladas entre
comillas.

> **NOTA**: Habrá más información acerca de éste en la sección que hable sobre el entorno cliente.

El almacenamiento de los datos en el entorno servidor de este Componente Customizado viene siendo en
un archivo SQLite para que el administrador tenga control sobre los distintos ficheros de este tipo,
así como su globalización mediante el Driver PDO.

## ignore

Este Componente Customizado simplemente hace que WMarkDown ignore lo que tenga dentro, dejándolo sin
formatear ni nada. Es importante destacar que el doble cierre de corchete se considerará el cierre
del "ignore", y que en caso de necesitar ponerlo es importante hacer uso de HTML. Unos ejemplos de
ésto podrían ser los siguientes, donde el primero simplemente hace ignorar una palabra, el siguiente
un texto, y en el siguiente un JSON con doble cierre de corchete.

<table style="width:100%;">
    <thead>
        <tr>
            <th style="width:30%;">WMarkDown</th>
            <th style="width:30%;">Normal</th>
            <th style="width:30%;">Ignorado</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>

```md

# Testeando el *ignore*

Tengo 35 [[ignore años]].

Fichero: [[ignore vacíos.json]]

JSON: [[ignore '["jiji", "jaja", ["cosa.txt", "cosa.json"<span>]</span>]']]

```

            </td>
            <td>

                <h1>Testeando el *ignore*</h1>

                Tengo 25 años.

                Fichero: vacíos.json

                JSON: '["jiji", "jaja", ["cosa.txt", "cosa.json"]]'

            </td>
            <td>

                <h1>Testeando el *ignore*</h1>

                Tengo 35 [[ignore años]].

                Fichero: [[ignore vacíos.json]]

                JSON: [[ignore '["jiji", "jaja", ["cosa.txt", "cosa.json"<span>]</span>]']]

            </td>
        </tr>
    </tbody>
</table>

> **NOTA**: SPAN en HTML no es más que una etiqueta de línea, visualmente no se ve ni se percibe, y
gracias a ésta podremos escapar caracteres que puedan ser problemáticos en última instancia, como
éste que acabamos de ver.

## links_group

El _links\_group_ o "Grupo de Links" viene siendo pequeño componente que permite mostrar un conjunto
de Links sin mostrar sus URIs, sino una imagen representativa y a lo sumo, un pequeño texto o
palabra acorde a éste, iconificando los enlaces mediante imágenes, siguiendo la estructura del
módulo Multimedia, y automatizando ciertas cosas como la carga y selección de imágenes funcionales,
organizamiento de los mismos y los estilos básicos. Su orden se basa en el orden dado en el Array
JSON el cual define este Componente Customizado, e irántodos en la misma línea, centrados, y cuando
hay tantos que exceden la línea automáticamente crearán una segunda, tercera o tantas líneas como
requieran para mostrar todos los Links.

La estructura del JSON no es más que un Array de diccionarios, donde cada diccionario no es más que
un Link y el cual posee la siguiente estructura:

- **images** _(required)_: Array de URLs de imágenes alternativas, en el orden de prioridad.
- **link** _(required)_: URL a la que se quiere enviar.
- **text** _(required)_: Texto que acompaña a la imagen.
- **self** _(optional)_: Indica si se abre en la pestaña/ventana actual (true) o se abre una nueva
(false).

Con respecto al campo "images", se pueden poner tantas URLs como se quieran, incluyendo repetidas,
aunque la idea de repetidas en una mala idea porque pasará exactamente lo mismo en los casos
repetidos; y se cogerán partiendo de la primera imagen hasta la última, donde la primera imagen que
encuentre que no de error, será la que ponga. En caso de que todas las opciones den error o que no
se establezca imagen, la imagen quedará vacía.

Un ejemplo de funcionamiento puede ser el siguiente:

<table style="width:100%;">
    <thead>
        <tr>
            <th style="width:50%;">WMarkDown</th>
            <th style="width:50%;">Resultado</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>

```md

# Links de ejemplo

[[links_group [{
    "images" : ["https://wmarkdown.k3y.pw/images/wmarkdown.png"],
    "link" : "https://wmarkdown.k3y.pw/",
    "text" : "WMarkDown"
}, {
    "images" : ["https://git.k3y.pw/assets/logo-d36b5212042cebc89b96df4bf6ac24e43db316143e89926c0db839ff694d2de4.svg"],
    "link" : "https://git.k3y.pw/",
    "text" : "Git"
}, {
    "images" : ["https://gittutorials.k3y.pw/images/gittutorials.png"],
    "link" : "https://gittutorials.k3y.pw/",
    "text" : "GitTutorials"
}, {
    "images" : [],
    "link" : "https://wdictionaries.k3y.pw/",
    "text" : "WDictionaries"
}, {
    "images" : ["https://kyman.local/images/logo.png"],
    "link" : "https://kyman.k3y.pw/",
    "text" : "KyMAN Wlog"
}, {
    "images" : ["https://kanvas.k3y.pw/images/kanvas.png"],
    "link" : "https://kanvas.k3y.pw/",
    "text" : "Kanvas"
}] ]]

```

            </td>
            <td>

                <h1>Links de ejemplo</h1>

                [[links_group [{
                    "images" : ["https://wmarkdown.k3y.pw/images/wmarkdown.png"],
                    "link" : "https://wmarkdown.k3y.pw/",
                    "text" : "WMarkDown"
                }, {
                    "images" : ["https://git.k3y.pw/assets/logo-d36b5212042cebc89b96df4bf6ac24e43db316143e89926c0db839ff694d2de4.svg"],
                    "link" : "https://git.k3y.pw/",
                    "text" : "Git"
                }, {
                    "images" : ["https://gittutorials.k3y.pw/images/gittutorials.png"],
                    "link" : "https://gittutorials.k3y.pw/",
                    "text" : "GitTutorials"
                }, {
                    "images" : [],
                    "link" : "https://wdictionaries.k3y.pw/",
                    "text" : "WDictionaries"
                }, {
                    "images" : ["https://kyman.local/images/logo.png"],
                    "link" : "https://kyman.k3y.pw/",
                    "text" : "KyMAN Wlog"
                }, {
                    "images" : ["https://kanvas.k3y.pw/images/kanvas.png"],
                    "link" : "https://kanvas.k3y.pw/",
                    "text" : "Kanvas"
                }] ]]

            </td>
        </tr>
    </tbody>
</table>

## icon

Este Componente Customizado sirve para marcar algo como una nota, alerta, aviso, etc. Y suele ser
usado para los Quotes (Componente que se verá más adelante). Dicho Componente Customizado puede ser
nombrado como:

- icon
- i
- !

> [[! note NOTA]]: Las nomenclaturas "i" y "!" están hechas para agilizar y facilitar su uso.

La sintaxis de los iconos es la siguiente, donde podemos ver las siguientes partes:

```md
[[icon|i|! TIPO TEXTO?]]
```

- **TIPO**: Es el tipo de icono que se quiere mostrar. Dicho nombre lo podemos sacar del fichero de
iconos de CSS y nos valdría cualquiera de ellos, aunque oficialmente existen 5: *note* o notas;
 *alert* o alertas; *important* o cosas importantes; *warning* o avisos; y *danger* o peligro.
- **TEXTO**: Es un campo opcional que permite añadirle un texto que lo acompañe.

> [[! note NOTA]]: Es importante tener en cuenta que este Componente Customizado es un elemento de
línea que puede estar integrado dentro de un texto entre otros.

Los tipos de icono que hay son los siguientes:

<table style="width:100%;">
    <thead>
        <tr>
            <th style="width:19%;">Tipo</th>
            <th style="width:25%;">WMarkDown</th>
            <th style="width:28%;">Ejemplo</th>
            <th style="width:28%;">Resultado</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Nota</td>
            <td>

```md
[[! note NOTA]]
```
            </td>
            <td>

```md

> [[! note NOTA]]: Esto es una nota.

> [[! note]] Esto es una nota.

```

            </td>
            <td>

> [[! note NOTA]]: Esto es una nota.

> [[! note]] Esto es una nota.

            </td>
        </tr>
        <tr>
            <td>Alerta</td>
            <td>

```md
[[! alert ALERTA]]
```
            </td>
            <td>

```md

> [[! alert ALERTA]]: Esto es una alerta.

> [[! alert]] Esto es una alerta.

```

            </td>
            <td>

> [[! alert ALERTA]]: Esto es una alerta.

> [[! alert]] Esto es una alerta.

            </td>
        </tr>
        <tr>
            <td>Aviso</td>
            <td>

```md
[[! warn AVISO]]
[[! warning AVISO]]
```
            </td>
            <td>

```md

> [[! warn AVISO]]: Esto es un aviso.

> [[! warn]] Esto es un aviso.

```

            </td>
            <td>

> [[! warn AVISO]]: Esto es un aviso.

> [[! warn]] Esto es un aviso.

            </td>
        </tr>
        <tr>
            <td>Importante</td>
            <td>

```md
[[! important IMPORTANTE]]
```
            </td>
            <td>

```md

> [[! important IMPORTANTE]]: Esto es algo importante.

> [[! important]] Esto es algo importante.

```

            </td>
            <td>

> [[! important IMPORTANTE]]: Esto es algo importante.

> [[! important]] Esto es algo importante.

            </td>
        </tr>
        <tr>
            <td>¡Peligro!</td>
            <td>

```md
[[! danger PELIGRO]]
```
            </td>
            <td>

```md

> [[! danger PELIGRO]]: Esto es algo peligroso.

> [[! danger]] Esto es algo peligroso.

```

            </td>
            <td>

> [[! danger PELIGRO]]: Esto es algo peligroso.

> [[! danger]] Esto es algo peligroso.

            </td>
        </tr>
    </tbody>
</table>

## WDoc

El WDoc es un sistema basado en el XDoc para documentar código, pero con la diferencia que en este
caso es para documentar el código a partir de ficheros WMD para dejar el código lo más limpio
posible, además de agilizar la documentación del código dentro de los documentos WMD, manteniendo
una pequeña estructura simplificada de XDoc para una documentación rápida de variables y metodos que
nos podamos encontrar. El WDoc se basa en tres partes diferenciadas las cuales son:

- **Descripción**: Inicia con cualquier caracter que no sea "@" ni "#". Pequeño texto descriptivo
para definir por encima el método o variable que se quiera documentar.
- **Data o información**: Inicia con "@". Valores basados en una llave y un valor tanto para el XDoc
como para el propio WDoc, y suelen ser elementos comunes.
- **Atributos y retorno**: Inicia con "#". Parámetros de entrada del método y retorno del mismo.

Cada elemento conforma una única línea dentro del elemento o bloque WDoc y se distinguen a partir de
su inicio el cual se detalla en la lista anterior.

En el caso de la descripción, cualquier línea que empiece sin  ninguno de los caracteres
determinados será concatenada a la descripción separados por un simple espacio. Permite el uso de
HTML, lo mismo que en resto de atributos, aunque en los demás no se aconseja, y se hace uso de HTML
si se viere necesario pero en la medida de lo posible y por la descripción de este Componente
Customizado no se aconseja hacer un uso excesivo de ello.

El en el caso de Data o información, sirve para cumplimentar datos genéricos del XDoc o WDoc, siendo
algunos de ellos los siguientes:

- **name** *(required)*: Sería el nombre completo del elemento, es decir, si se encuentra en una
clase, subclase o espacio de nombres, ha de representar se entero, sin espacios.
- **language** *(required)*: Lenguaje de programación en el que esté trabajado sin espacios.
- **author** *(optional)*: Autor o autores del elemento a documentar, separados por comas y sin
espacios.
- **since** *(optional)*: Fecha en formato "YYYYMMDD" desde la primera aparición en código de dicho
elemento.
- **version** *(optional)*: Última fecha de modificación en formato "YYYYMMDD" de dicho elemento.
- **deprecated** *(optional)*: Determina si está obsoleto o no. Su valor ha de ser "true".

> [[! important IMPORTANTE]]: Los elementos de Data o información "required" u obligatorios deben de
existir siempre o pueden dar resultados no esperados por el redactor.

Finalmente, en el caso de los atributos se determinan a partir de 4 puntos los cuales se separan con
espacios, siendo el último el único capaz de contener dichos espacios. La separación entre ellos
pueden ser espacios o tabulaciones, y pueden ser tantos como se desee para mantener una legibilidad
a la hora de representar en código. Dichos elementos de los que consta son los siguientes:

- **nombre** *(required)*: Nombre del atributo.
- **tipados** *(required)*: Tipado o posibles tipados del atributo. En caso de poder ser cualquiera
se pondría la palabra "ANY" para representar "cualquiera" (Por defecto, el tipado "-" será "ANY").
- **modo** *(required)*: Determina si el atributo es obligatorio (Required) u opcional (Optional).
- **descripción** *(optional)*: Pequeña descripción del atributo.

> [[! note NOTA]]: Para representar el retorno, hemos de usar el nombre de atributo return, que
siguiendo con el modelo de un atributo continuaría con el tipado o tipados de variable de retorno,
un guión ("-") por el hecho de no ser ni opcional, ni requerido ni ninguna otra forma dependiente
del usuario, y con una pequeña descripción opcional que determine qué es lo que retorna.

Un ejemplo de dicho sistema puede ser el siguiente:

```md

Descripción WDoc del método **AnP.string_variables**.

[[wdoc
Procesa las variables de un String.
@name       AnP.string_variables
@lang       Python
#string     str             required    String a procesar.
#variables  dict,list,tuple optional    Variables para procesar el String.
#default    str             optional    Valor por defecto.
#return     str             -           String procesado.
]]

```

Su resultado vendría siendo el siguiente:

<blockquote class="quote">

Descripción WDoc del método **AnP.string_variables**.

[[wdoc
Procesa las variables de un String.
@name       AnP.string_variables
@lang       Python
#string     str             required    String a procesar.
#variables  dict,list,tuple optional    Variables para procesar el String.
#default    str             optional    Valor por defecto.
#return     str             -           String procesado.
]]

</blockquote>

También se cuenta con posibles sobrecargas, es decir, que un método pueda tener más de un tipo de
entrada con lo que éste actuará diferente en base a su entrada. Como éste se basa en los atributos y
retorno del mismo, se puede poner el parámetro "@overload" sin ningún valor ni nada, lo que indica
que a partir de ahí empieza una sobrecarga del método con sus propios parámetros de entrada y
retorno.

> [[! note NOTA]]: Un retorno vacío se especificará automáticamente con el tipado "void", por lo que
no haría falta ni definirlo.

> [[! note NOTA]]: Es importante determinar que en lenguajes como Python, en sus métodos objeto o
métodos de clase, el primer parámetro de entrada se entiende como un parámetro forzado del propio
lenguaje por el cual no se determinará en el WDoc, dando a entender que en estos casos se empezará
en el segundo parámetro de entrada por ser un parámetro dado al usuario, que será con los que pueda
interactuar.

## plain

El Componente Customizado "plain" nos permite establecer un fragmento de texto totalmente plano a
nivel de HTML, sin que éste se procese ni se etiquete. Es muy útil para mantener estructuras en los
títulos u otros elementos vinculados. Un ejemplo de funcionamiento puede ser el siguiente:

```md

# [[AnP.get_dictionary_path]]

Título del bloque "AnP.get\_dictionary\_path".

# AnP.get_dictionary_path

Título del bloque "AnP.get\_dictionary\_path".

```

> [[! note NOTA]]: Los textos que queden planos quedarán siendo parte de su padre y no
distinguiéndose del resto de los textos puesto que no estarán etiquetados.

[[html_data {
    "title" : "WMarkDown - Parámetros customizados",
    "url" : "https://wmarkdown.k3y.pw/es/doc/modules/custom_parameters.html",
    "author" : "Tarsier, KyMAN",
    "since" : 20210515,
    "version" : 20210519,
    "key_words" : "Whalers,MarkDown,MediaWiki,WMarkDown,módulo,parámetros,custom,personalizado,include,inclusión,import,importación,multimedia,xdoc,wdoc",
    "description" : "Módulo de parámetros customizados.",
    "project" : "WMarkDown",
    "logo" : "https://wmarkdown.k3y.pw/images/wmarkdown.png",
    "language" : "es"
}]]