- Ayuda al contexto
- Estructura
- Preguntas Frecuentes

Ayuda al contexto
%HRTABLE%

- Los formularios de STTA ofrecen "enlaces" de ayuda específica sobre los items de entradad de datos. En la parte superior Izquierda de la ventana el texto <exec $text{help}> ofrece información genérica del formulario o cgi.
- Una vez abiertas las ventans de ayuda STTA se puede "navegar" por los enlaces y referencias cruzadas que ofrecen las mismas.
- La dimensión de las ventanas de ayuda puede configurarse en <exec &hlink('Interface','config_inface')>, valores $infoCfg{help_height} (<exec $config{help_height}>) y $infoCfg{help_width} (<exec $config{help_width}>). El aspecto o "look & feel" de la ayuda está sujeto a los mismos detalles y configuración que la interface de STTA

Estructura
%HRTABLE%

- STTA usa una biblioteca propia para gestionar la infraestructra de la Ayuda del módulo que evalua etiquetas y texto para devolver texto HTML:
  - Los ficheros html del "directorio base (help)" no contienen "cadenas de texto localizadas", usan variables de texto o valores del entorno en base a al idioma configurado en Webmin.
  - En algunos casos se "incluyen" otros ficheros para confeccionar la página, se incluyen secciones completas o se generarn valores de atributos de configuración del entorno.
  - El valor de LANG (que figura entre % ) es sustituido por el del idioma Webmin(ej: es, en, etc)
  - Todo el "texto localizado" en el idioma correspondiente, está en el subdirectorio LANG del "directorio base (help)" del módulo.
- El directorio dentro del módulo que contiene la ayuda es "help" que contiene:
  - Ficheros html con la arquitectura básica del tema correspondiente:
    - Carga de cabecera de página, etiqueta HTML "head".
    - Bloques de cabecera de la página de página, etiqueta HTML "headimg" y "headertitle".
    - "Include" de fichero LANG/head del tema. Texto de encabezado del tema.
    - "Include" de fichero LANG/msg del tema. Recuadro con información general en modo resumen y detalles relevantes.
    - "Include" de fichero LANG/body del tema. Texto con descripción y análisis detallado del tema.
    - Carga de referecias cruzadas (caja <exec $text{see_also}>), etiqueta HTML "footlinks".
    - Carga de pies y bloques de pie de la página, etiqueta HTML "foot".
  - Directorios LANG del idioma correspondiente para ser "incluídos" por la arquitectura base de las páginas, con la estructura siguiente:
    - Ficheros html de tipo general de la ayuda.
    - LANG/head/tema. Texto de encabezado del tema.
    - LANG/msg/tema. Recuadro con información general en modo resumen y detalles relevantes.
    - LANG/body/tema. Texto con descripción y análisis detallado del tema.
    - LANG/config/parámetro. Texto con detalles de la configuración del parámetro de la sección. Estos ficheros son cargados directamente del directorio LANG con una cabecera y pie por defecto. (cfg_head y cfg_foot).

Preguntas Frecuentes
%HRTABLE%

- ¿ Se puede desactivar la ayuda ?
  Sí, cambiando el valor de la variable <exec &hlink('$infoCfg{help_active}','config/help_active')> (help_active) en <exec &hlink('main','config_main')>
- ¿ Cómo se establece el enlace al Libro STTA ?
  El enlace por defecto está establecido sobre la Web de publicación de la versión oficial del <exec $text{book_stta_pdf}>, si la plataforma no tiene acceso a Internet, basta con descargar el archivo del "bookstta.pdf" y colocarlo en directoryo help/LANG (ej: help/es para Español), entonces, el enlace se establecerá contra este path. Habrá que actualizar el fichero pdf del libro cuando cambie en la Web de publicación.
- ¿ Cómo se puede generar una estrucura de ayuda para otro idioma ?
  Usando el script mklanghelp.sh desde el directorio del módulo de STTA (ver <exec &hlink('scripts','inface_scripts#stta')>).
- ¿ Sobre qué ficheros hay que modificar el texto o traducir a otro idioma ?
  Sobre los ficheros del directorio help/LANG (ej: help/es para Español) y los ficheros LANG correspondientes al idioma del directorio "lang" del módulo, en especial el genérico y el del directorio "lang/help". No se deben traducir la variables de entorno y valores de carga de cadenas de texto.
- ¿ Se pueden usar variables del entorno y valores de cadenas de texto ?
  Sí, usando las siguietes expresiones entre < >, donde las palabras text, config e infoCfg van precedidas del signo $ :
  - "exec text{nombre-de-la-variable}" es sustituído por el valor de la cadena de texto correspondiente.
  - "exec config{nombre-de-la-variable}" es sustituído por el valor de la variable correspondiente.
  - "infoCfg{nombre-del-parámetro}" (no hay que incluirlo entre <>) es sustituído por el valor de la cadena de texto del formulario de configuración correspondiente (ficheros "config.info.LANG).
- ¿ Cómo se puden usar los iconos de alerta en las páginas ?
  Escribiendo los siguientes textos entre signos % :
  - "W" muestra un %W%
  - "I" muestra un %I%
  - "H" muestra un %H%
  - "N" muestra un %N%
  - "S" muestra un %S%
  - "U" muestra un %U%
  - "P" muestra un %P%
  - "OK" muestra un %OK%
  - "INFO" muestra un %INFO%
  - "AR" muestra un %AR%
- ¿ Cómo se forma la URL de las páginas de ayuda ?
  URL base: http(s)://webmin-host:port/stta/help.cgi/stta/
  Hay que añadir:
  - El nombre del fichero html de ayuda ubicado en el directorio <exec $root_directory>/stta/help sin la extensión (.html).
    Ejemplo: página índice <exec &hlink('/stta/help.cgi/stta/toc','toc')>
  - Si se trata de una sección de la <exec &hlink($text{sttaconfig},'sttaconfig')> usar "config_[sección]", la sección es el nombre del fichero ubicado en el directorio de configuración de STTA (<exec $config_directory>/stta/dataconf).
  - Si se trata de un parámetro de la ayuda, usar config/[parámetro], el parámetro es el nombre del fichero html ubicado en el "directorio de la ayuda"/LANG/config.
    Ejemplo: página parámetro has_ldapcache <exec &hlink('/stta/help.cgi/stta/config/is_ldapcache','/config/is_ldapcache')>
  - En todos los casos puede añadirse al final un valor como nombre de la ventana ?nombre-ventana de modo que los enlaces de la página sean abiertos sobre la misma.
  - %W% No todos los ficheros ".html" pueden cargarse, el gestor de ayuda requiere incluir secciones y valores específicos (cabecera, pie página, etc) para generar un formato "HTML" correcto para los navegadores. Todos los ficheros bajo los directorios LANG son usados como "includes" de las páginas base en <exec $root_directory>/stta/help/.
- ¿ Se puede disponer de una página a modo de MANUAL de STTA ?
  Usar la URL: http(s)://webmin-host:port/stta/help.cgi/stta/tocbook
  O los enlaces a <exec &hlink($text{book_stta},'tocbook')>