Inicio

Traducción al Español que hice de gendoc, programa que se puede obtener clonando este repositorio. Esta traducción está licenciada por el Autor del sitio bajo los mismos términos y condiciones de la web antes citada y por la Licencia FDL 1.3.

Documentación gendoc en Español.

gendoc es una pequeña herramienta que genera documentación en un archivo HTML estático y formateado. Es similar a Sphinx y ReadtheDocs, pero mucho mejor y mucho más interesante, ya que no tiene partes componentes del servidor y funciona sin JavaScript.

Sugerencia

Esta documentación es corta, mucho más corta que la de RtD. Esto no se debe a que me dé pereza escribirla, sino a que gendoc es realmente sencillo de utilizar. Ya se sabe, "¡Mantenlo estupidamente simple!"

Ventajas

  • Disponible como herramienta ANSI C y como script PHP (ambos sin dependencia).
  • Se parece y se siente como ReadtheDocs, pero también funciona sin conexión a Internet.
  • A diferencia de Sphinx, gendoc es fácil de usar, y genera un único archivo estático (que pasa la validación HTML5 del W3C, por cierto).
  • El documento gendoc está libre de dependencias y recursos externos, no requiere CSS de terceros ni webfonts.
  • No depende de jQuery ni de otras librerías de terceros y no tiene componentes de servidor.
  • Puede descargar un documento gendoc en su ordenador y utilizarlo como un archivo local, todo funcionará, ¡incluso la búsqueda!
  • Mucho más pequeño y más limpio CSS + HTML que lo que genera Sphinx, utilizando selectores en lugar de nombres de clase siempre que sea posible.
  • Mucho más fácil de tematizar que Sphinx, y la documentación generada tiene diseño responsivo listo para usar.
  • Tiene una herramienta de generación de APIs integrada, pero puede añadir plugins si no le gusta su formato de salida (que es bastante básico).

Desventajas

A diferencia de RtD, gendoc no proporciona alojamiento. Pero como los documentos son sólo archivos individuales y tenemos gitlab, github, etc. esto no es un problema real. (Tal vez permitirle tener una copia de su propia documentación y no llevársela a la nube no sea una desventaja en absoluto...)


  •  »
  •  1 Comenzando

1 Comenzando

Lo primero es descargar el código fuente o el script del repositorio. Ambos son archivos individuales, de unos 100 kilobytes cada uno. En serio, no hay dependencias (aparte de un intérprete de php para el script, por supuesto). Todo está incluido sin problemas.

1.1 Uso

Para la versión ANSI C: 

$ gcc gendoc.c -o gendoc
$ ./gendoc <salida.html> <archivo entrada> [archivo entrada...]
Y con la version PHP: 
$ php ./gendoc.php <output> <input file> [input file...]

1.1.1 Salida

El formato de salida es detectado por la extensión, y a falta de un plugin de escritura para esa extensión, por defecto es un único archivo HTML5 válido para el W4C, autocontenido y sin dependencias, que puede llevar a cualquier parte (como el que está leyendo ahora). La salida de la versión ANSI C y de la versión PHP debería ser idéntica bit a bit (excepto si tiene la extensión php-gd instalada, entonces la versión PHP encogerá de forma transparente las imágenes alineadas para ahorrar espacio de almacenamiento).

1.1.2 Archivos de Entrada

Puede utilizar un archivo de entrada o varios archivos. No importa, gendoc de cualquier manera generará un único archivo de salida. Usted tiene el control total de cómo organizar sus documentos de origen, no influye en la salida (no como Sphinx).

Los archivos de entrada también se incorporan a la salida, su formato se detecta por la extensión, y en ausencia de un plugin de lectura, se utiliza por defecto las etiquetas de gendoc.

Nota

La versión ANSI C sólo lee etiquetas gendoc y sólo genera en formato de salida HTML5, no soporta plugins de lectura/escritura de formatos de archivo. Sin embargo, tiene un filtro incorporado para convertir MarkDown en gendoc, basado en smu. El plugin de PHP utiliza una clase ParseDown extendida.


  •  »
  •  2 Creación de Documentos

2 Creación de Documentos

Se escriben archivos de texto simples, por defecto con etiquetas similares a las de HTML, pero MUCHO MÁS simples. También puede añadir plugins para soportar cualquier formato de entrada, como ReadFirst o MarkDown. Esta documentación, en adelante, habla del formato de etiquetas por defecto de gendoc.

Hay dos categorías para las etiquetas. Las etiquetas de la primera categoría especifican la metainformación y la estructura general de la documentación.

2.1 Especificación de la Metainformación

Estos están encerrados entre las etiquetas gendoc: <doc>...</doc>. Bastante simples, sólo especifican algunos datos variables y etiquetas traducidas para el documento, sobre todo para las cajas de alerta. El <doc> debe ser la primera etiqueta en el archivo de documentación de origen. Sus subetiquetas son las siguientes:

<title>...</title>
Especifica el título del documento, que se muestra en diferentes lugares, en la parte superior izquierda y también en la barra de la ventana, por ejemplo
<titleimg>(nombrearchivo) ...</titleimg>
Opcionalmente se puede especificar una imagen de título. El nombre del archivo es una ruta relativa al documento fuente, y el texto restante después del espacio se utilizará como atributo alt y se añadirá a la cadena del título como prefijo.
<url>...</url>
La URL a la que conduce el título importante en la parte superior izquierda.
<version>...</version>
La cadena que hace referencia al número de versión se muestra debajo del título en la parte superior izquierda.
<theme>...</theme>
Especifica el nombre del archivo CSS para la Personalización del tema el tema (y sólo el tema).
</lang>...</lang>
El idioma de la documentación en formato de dos letras ISO-639-1. Sólo informativo, no creo que a nadie le importe lo que hay en el atributo lang de la etiqueta HTML.
<rslt>...</rslt>
La cadena traducida de "Resultados de la búsqueda".
</home>...</home>
La cadena traducida de "Inicio" (información emergente referida a la navegación de rutas que van apareciendo).
<links>...</links>
El tooltip (información de herramienta) traducido para los enlaces de los títulos, "Enlace permanente al encabezado".
<info>...</info>
La cabecera traducida del tipo de información alerta, "Info" o "Importante" o por el estilo.
<note>...</note>
La cabecera traducida de las alertas de tipo "Nota".
<also>...</also>
La cabecera traducida de las alertas de tipo "Ver También".
<todo>...</todo>
La cabecera traducida de las alertas de tipo "Hacer".
<warn>...</warn>
La cabecera traducida de las alertas de tipo "Advertencia".
<args>...</args>
La cabecera traducida de la tabla "Argumentos" (utilizada por el generador de la API).
<rval>...</rval>
La cabecera traducida de la tabla "Valor de Retorno" (utilizada por el generador de la API).
<prev>...</prev>
La etiqueta traducida en el botón de (página) "Anterior" en la parte inferior.
<next>...</next>
La etiqueta traducida en el botón de (página) "Siguiente" en la parte inferior.
<copy>...</copy>
Por último, el contenido de la etiqueta de copyright en la parte inferior.

Uso el ejemplo que escribió su Autor: 

    <doc>
	<titleimg>logo.png gendoc</titleimg>
	<title>Documentación</title>
	<url>https://texto-plano.xyz/~tano/archivos-gendoc/07_gendoc.html</url>
	<version>1.0.0</version>
	<theme>theme.css</theme>
	<lang>es</lang>
	<rslt>Resultado de la Búsqueda</rslt>
	<home>Inicio</home>
	<link>Enlace permanente a este Encabezado</link>
	<info>Importante</info>
	<hint>Consejo</hint>
	<note>Nota</note>
	<also>Vea También</also>
	<todo>Hacer</todo>
	<args>Argumentos</args>
	<rval>Valor de Retorno</rval>
	<warn>Advertencia</warn>
	<prev>Anterior</prev>
	<next>Siguiente</next>
	<copy>2022 Tano (tano@texto-plano.xyz)</copy>
    </doc>

Nota

Ya sea que se de <titleimg> o <title>, el título real se concatena a partir del texto alt y la etiqueta <title>, por lo tanto será "documentación gendoc" en el ejemplo anterior.

2.2 Tabla de Contenidos

Las siguientes etiquetas influyen en el modo en que se genera el índice de contenidos (TOC) de la izquierda. Estas etiquetas son

<cap>...</cap>
que añade un título al TOC, y las
<h1>...</h1>,<h2>...</h2> hasta <h6>...</h6>
etiquetas de encabezado.

La etiqueta <h1> abre una nueva página. Otros subtítulos añaden secciones a esa página. Los enlaces y las urls se generan automáticamente a partir del texto del encabezamiento, pero por si acaso el nombre generado no se ajusta a sus necesidades, puede especificar el id de la etiqueta a mano con <h1 (id)>, <h2 (id)>i, <h3 (id)> etc.

Por ejemplo: 

		<h1>Encabezado Simple</h1>                    (Usará siempre "encabezado_simple" como etiqueta)
		<h1 mi_etiqueta_puntual>Otro Encabezado</h1>  (usará "mi_etiqueta_puntual")

2.2.1 La Página de Bienvenida

Puede encerrar la primera, y exactamente una etiqueta <h1> con sus subtítulos en un

<hello>...</hello>
Adjunta los títulos y secciones de bienvenida.

Estas rúbricas quedarán excluidas del índice de contenidos y, a cambio, se mostrarán como página de bienvenida. Además, el enlace "Inicio" con sus rutas de navegación llevará a esta página en lugar de a la primera entrada del índice de contenidos.

2.2.2 Incluír Documento Fuente

<include (nombrearchivo)>
Esta etiqueta incluye otro documento fuente como si se diera en la línea de comandos.

2.2.3 Consideraciones de Seguridad

Ninguna. Se asume que "Antonieta de las Nieves" necesita una documentación, así que escribe los archivos de entrada y ejecuta gendoc en su ordenador local, y con suerte Antonieta no quiere hackear a "de las Nieves" (¿tal vez si es esquizofrénica?). En resumen, sólo hay una parte en el proceso de generación.

Entonces "de las Nieves" solamente recibe el HTML estático generado, no tiene acceso a los archivos de entrada, no ejecuta gendoc ni se involucra en el proceso de generación de la documentación de ninguna manera. Todo lo que obtiene es el producto estático final.

Si "Antonieta" sube la documentación a un servidor, eso tampoco es un problema, porque gendoc no tiene absolutamente ningún componente de servidor. "de las Nieves" descargará la documentación en su ordenador (probablemente en la caché local de su navegador), y la búsqueda se ejecutará en su ordenador local. Si "de las Nieves" intenta piratear la búsqueda, sólo obtendrá malos resultados en su propio ordenador, pero no influirá en Cecil ni en otros lectores de documentos.


  •  »
  •  3 Formato

3 Formato

La segunda categoría es para las etiquetas que utiliza para dar formato al documento. gendoc le quita el peso de la web moderna de encima, lo libera de la locura de las hojas de estilo y de las etiquetas neutrales al contexto, puede utilizar etiquetas sencillas tal y como Sir Burners Lee pretendía originalmente.

En un documento fuente bien formado no deberían existir más etiquetas que las enumeradas aquí (olvídese de <span>, <div>, etc.). Pero para proporcionar compatibilidad con HTML, los generadores no imponen esto, todas las etiquetas que no son reconocidas por gendoc se copian literalmente en la documentación final (con una advertencia).

Advertencia

No se deje engañar por el parecido: las etiquetas gendoc no son etiquetas HTML, sólo lo parecen para acortar significativamente su curva de aprendizaje.

Advertencia

En cuanto escriba su primer atributo de la etiqueta, puede estar seguro de que lo está haciendo mal.

Todas las etiquetas tienen su correspondiente etiqueta de cierre, excepto <include>, <api>, <br>, <mb*> e <img*> (donde '*' puede ser l,r,w). Esto se valida y los errores se reportan para cada sección individualmente.

3.1 Estilo de Texto

<h1>...</h1>,<h2>...</h2> hasta <h6>...</h6>
Para dar al texto estilo de encabezado.
<b>...</b>
Hace que el texto esté en negrita.
<i>...</i>
Hace que el texto esté en cursiva (u oblicuo).
<u>...</u>
Hace que el texto esté subrayado.
<s>...</s>
Hace que el texto esté tachado.
<sup>...</sup>
Hace que el texto esté en superíndice.
<sub>...</sub>
Hacer que el text sea subíndice.
<tt>...
Hace que el texto use la fuente monospace .También desactiva la interpretación de las etiquetas que hay dentro. Todas las etiquetas que puede ver en esta página están impresas con <tt> (No es necesario saber qué son &lt; y &gt; ni qué demonios hacen).
<quote>...</quote>
Hace que el texto sea:
Cita, no creo que necesites esto en una documentación, pero por si acaso

3.2 Estructuración de Textos

<p>...</p>
Envuelve los párrafos en, bueno, párrafos. Este elemento no tiene ningún aspecto visual, sólo separa bloques de texto. Si tiene problemas de visualización, intente envolver el texto en un párrafo.
<br>
Línea de ruptura. Utilícela sólo si es realmente necesario. Esta etiqueta no tiene par de cierre.
<ol>...</ol>,<ul>...</ul>,<li>...</li>
Listas ordenadas: <ol>...</ol> y no ordenadas: <ul>...</ul>. Ambas son etiquetas <li>...</li> que encierran elementos de la lista. No quiera tener viñetas de listas elegantes, son extremadamente molestas para los lectores de documentación.
<dl>...</dl>, <dt>...</dt> y <dd>...</dd>
Bloques de datos, como este que está leyendo ahora. La lista está encerrada en la etiqueta <dd>...</dd> y puede contener múltiples tópicos y descripciones. El tema está en <dt>...</dt> y la descripción en <dd>...</dd>.
<grid>...</grid>, <gr>...</gr> y <gd>/<gD>...</gd>
Las filas de la cuadrícula <gr>...</gr> están encerradas en etiquetas <grid>...</grid>. Cada fila contiene una o más celdas de cuadrícula <gd>. Parece y funciona como una tabla invisible con celdas de igual tamaño. La etiqueta de apertura <gD> en mayúsculas hace que la celda sea ancha.
<table>...</table>, <tr>...</tr> y <th>/<tH>, <td>/<tD>, <tn>/<tN>
Las filas (<tr>...</tr>) de la tabla están encerradas en etiquetas <table>...</table>. Cada fila contiene una o más celdas. Aquí, <th>...</th> se formatea como cabecera, <tH>...</th> como wide-header (encabezado ancho, tiene el mismo aspecto que la cabecera, pero alarga el color a lo ancho). La etiqueta <td>...</td> es para los datos de la tabla y hace que la celda esté alineada a la izquierda, pero si necesita alineación a la derecha (como para los números decimales), use <tn>...</tn>. Si no tiene cabeceras, pero necesita celdas anchas, entonces puede usar las variantes de apertura en mayúsculas, como <tD> y <tN> para ajustar las celdas.
Cabecera 1 Cabecera 2 Cabecera 3
(1,2) Izquierda (2,2) Izquierda (3,2) Derecha
(1,1) Derecha (2,1) Izquierda (3,1) Izquierda

3.3 Texto Preformateado

<pre>...<pre/>
Al igual que <tt>, cambia el tipo de letra a monospace y desactiva el análisis de etiquetas, pero además proporciona un área opcionalmente desplazable alrededor del texto. <pre> es para cualquier texto o salida de programa o muestras de línea de comandos. 
Este es un ejemplo
   de texto preformateado con
  varias líneas y que es muy muy largo, tanto que no cabe en la pantalla y debe aparecer una barra de desplazamiento.
<hl>...</hl>, <hm>...</hm>
Resalta partes de los bloques <pre> (y <code>). Utilice <hl> para resaltar algo, o <hm> para resaltar líneas enteras y múltiples. 
Este es un ejemplo
   de texto preformateado que tiene
		un texto resaltado,
      e incluso
algunos resaltados
		de líneas
		    completocomo ejemplo

3.4 Código Fuente

<code>...</code>, <code (lang)>...</code>
Al igual que <pre>, proporciona barras de desplazamiento, etc., pero <code> debe contener el código fuente del programa que será resaltado sintácticamente. Por defecto utiliza un resaltador genérico, pero puede añadir reglas a lenguajes específicos con plugins y especificar el lenguaje como <código c>, <código php>, <código python> etc. Dentro del bloque de código, puede usar <hl>...</hl> y <hm>...</hm> para resaltar manualmente alguna parte del código ("Mundo" dentro de una cadena literal en este ejemplo): 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#include <stdlib.h> /* comentario 1 multilínea */ // comentario 2, línea única int main(int argc, char **argv) { volatile static int i, a = 0xff, b = -1ULL; wchar_t c = L'\e', *d = L"wide string"; float e = 1.0f, f = .5, g = -1e10; for(i = 0; i < 128; i++) a += b->c; printf("Hola Mundo!\n"); }
<api (lang) (nombrearchivo)>
Esta etiqueta genera una sencilla documentación de la API para un archivo fuente escrito en el lenguaje de programación especificado. El formato por defecto es bastante básico, pero admite cualquier lenguaje que acepte comentarios multilínea al estilo C (es decir, C, C++, PHP, JavaScript, Java, Go, Rust, etc.). Además, puede usar plugins para añadir un formato personalizado y para soportar cualquier lenguaje de programación o doctype estándar.

Para ver un ejemplo, consulte la sección API de esta documentación.

3.5 Enlaces

Hay dos tipos de enlaces en el documento:

<a>...</a>
Crea un enlace interno a uno de los encabezados, por ejemplo <a>Comenzando</a> se ve así: Comenzando. Los enlaces internos siempre se abren en la misma pestaña del documento.
<a url>...</a>
Enlace externo. Estos abren una nueva pestaña.

3.6 Entrada del Usuario

En la documentación de un software es muy común tener que explicar cómo se realiza la entrada de datos por parte del Usuario. gendoc lo ayuda mucho con eso.

<ui1>...</ui1>, <ui2>...</ui2> hasta <ui6>...</ui6>
Estos no hacen nada en particular, pero puede estilizarlos desde el tema para imitar los elementos de la interfaz de Usuario de su software. Por ejemplo: "poner la casilla de verificación y luego hacer clic en el botón Guardar".
<kbd>...</kbd>
Se usa para representar los botones del teclado, <kbd>Ctrl</kbd>-<kbd>C</kbd> se ve: Ctrl+C.
<mbl>, <mbr>, <mbw>
Representa los botones y la rueda del ratón. Estas etiquetas no tienen par de cierre, son como imágenes. La etiqueta <mbl> se ve como , el botón derecho <mbr> como: y la rueda <mbw> como . Originalmente quería utilizar los glifos UNICODE "cuadrante superior izquierdo" y "cuadrante superior derecho" con un fondo degradado y un borde redondo, pero algunas fuentes (*khm* FreeSans) tiene estos incorrectamente intercambiados, y se muestra de manera muy diferente con diferentes tipos de letra (no se sabe por qué, <kbd> es bastante consistente y también donde la rueda del ratón con U+2579). De todos modos esto se ve mejor, pero dependiendo de los navegadores podría ser unos pocos píxeles verticalmente fuera en conjunto con <kbd>, como Alt+

3.6 Imagenes

<imgt (nombrearchivo)>
Inserta una imagen gpl3-1.png en el documento como texto alineado. El nombre del archivo es una ruta relativa al documento fuente. Las etiquetas de la imagen no tienen un par de cierre.
<imgl (nombrearchivo)>
gpl3-2.png Inserta una imagen en el documento que se alinea a la izquierda y flota alrededor del texto. 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 commondo consequat.
<imgr (nombrearchivo)>
gpl3-2.png Inserta una imagen en el documento que se alinea a la derecha y flota alrededor del texto. 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 commondo consequat.
<imgc (nombrearchivo)>
Inserta una imagen en el documento que está centrada y no flota con el texto.
gpl3-2.png
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<imgw (nombrearchivo)>
Inserta una imagen ancha en el documento que está centrada y no flota con el texto. gpl3-2.pngLogo GPL3: la calidad de esta imagen es una poronga. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<fig>...</fig>
Establece el título de la imagen como: <imgw figure.png><fig>Figura: patatín patatán</fig>.

3.7 Cajas de Alerta

Para estas cajas, el texto de la cabecera puede definirse en la etiqueta <doc>.

<hint>...</hint>
Crea un cuadro de sugerencias, como éste:

Sugerencia

Esta es una pista.

<info>...</info>
Crea una caja informativa, como ésta:

Importante

Esta es una información importante.

<note>...</note>
Crea una caja de nota como esta:

Nota

Esta es una nota.

<also>...</also>
Crea un cuadro de "ver también", como éste:

Ver También

Una buena película. Has jugado demasiado con el ordenador.

<warn>...</warn>
Crea un cuadro de advertencia, como éste:

Advertencia

Esta es una advertencia.

<todo>...</todo>
Crea un cuadro de tareas, como éste:

Hacer

Probablemente no deberías usar esto, en su lugar termine su código.


  •  »
  •  4 MarkDown

4 MarkDown

Puede elegir utilizar MarkDown para su formato de origen. Para ello, use la extensión .md en sus archivos de entrada. La versión ANSI C tiene un parser incorporado, la versión PHP necesita un plugin. En ambos casos, puede mezclar MarkDown simple con etiquetas gendoc (no HTML), como <mbl>, <imgl> etc.

Nota

Use la etiqueta <doc> al igual que lo haría con el formato XML para especificar los metadatos.

4.1 Tabla de Contenidos (markdown)

Use el estándar MD, las líneas subrayadas con el signo igual (‘=’) harán los encabezados <h1>, el guión (‘-’) hará los encabezados <h2>. También puede utilizar el prefijo hashmark (‘#’ marca de hash), donde el número de hashmarks establece el nivel del encabezado (de uno a seis). 

Encabezado 1
=========

Encabezado 2
---------

# Encabezado 1
## Encabezado 2
### Encabezado 3
#### Encabezado 4
##### Encabezado 5
###### Encabezado 6

4.1 Estilo de Texto (markdown)

Estos no son realmente el estándar de MD.

** ... **
Hace que el texto esté en negrita.
* ... *
Hace que el texto esté en itálica (u oblicuo).
_ ... _
Hace que el texto esté subrayado.
~ ... ~
Hace que el texto esté tachado.
^^ ... ^^
Hace que el texto sea superíndice.
,, ... ,,
Hace que el texto sea subíndice.
` ... `
Hace que el texto utilice la fuente monospace.
> ...
Las líneas que comienzan con > se agrupan y se presentan como una cita.
Citas:
> esta es una cita
> esto también pertenece a la misma cita
> No creo que necesites esto en una documentación

4.2 Estructuración de Textos (markdown)

Líneas vacías
Las líneas vacías comienzan y terminan un párrafo.
Dos espacios al final de una línea
Romper línea. Utilícelo sólo si es realmente necesario.
Listas con * ..., - ..., + ..., 1. ...
Listas ordenadas y desordenadas. Se pueden anidar.
  • Lista no ordenada
  • Lista no ordenada
  • Lista no ordenada
  1. Lista Ordenada
  2. Lista Ordenada
  3. Lista Ordenada
  • Lista no ordenada
  • Lista no ordenada
  • Lista no ordenada
Tablas
De nuevo, casi estándar, parece: 
| Cabecera de Ejemplo 1 | Cabecera de Ejemplo 2 | Cabecera de Ejemplo 3 |
|-----------------------|-----------------------|----------------------:|
| Dato de ejemplo 1     | Dato de ejemplo 2     |   Dato de ejemplo 3   |
| Dato de ejemplo 4     | Dato de ejemplo 5     |   Dato de ejemplo 6   |
En la segunda línea, si hay dos puntos dobles (como |----:|), entonces esa columna estará alineada a la derecha (sin importar dónde se encuentren los :). Además de MD, si contiene un asterisco * a la izquierda (como |*----|), entonces hará una celda de datos ancha, si está a la derecha (como |----*|), entonces una celda numérica ancha (así que la ubicación importa).

4.3 Texto Preformateado (markdown)

``` ... ```
Al igual que ` ... `, también cambia el tipo de letra a monospace y desactiva el análisis de etiquetas, pero además proporciona un área opcionalmente desplazable alrededor del texto. Esto es para cualquier texto o salida de programa o muestras de línea de comandos.

4.4 Código Fuente (markdown)

```(lang) ... ```
Al igual que ```, proporciona barras de desplazamiento, etc., pero debe contener el código fuente del programa que será resaltado sintácticamente. Por defecto utiliza un resaltador genérico, pero puede añadir reglas para lenguajes específicos con plugins y especificar el lenguaje como ```c, ```php, ```python etc. Dentro del bloque de código, puedes usar <hl>...</hl> y <hm>...</hm> para resaltar manualmente alguna parte del código.

4.5 Enlaces (markdown)

Hay dos tipos de enlaces en el documento:

[text]
Crea un enlace interno a uno de los encabezados, por ejemplo [Comenzando] tiene este aspecto: Comenzando. Los enlaces internos siempre se abren en la misma pestaña del documento.
[text](url)
Enlace externo. Estos abren una nueva pestaña.

4.6 Imagenes (markdown)

![texto descriptivo](nombrearchivo)
Inserta una imagen ancha con un título de imagen en el documento que esta centrado y no flota con el texto. (Para un mayor control, puede utilizar las etiquetas <imgt>, <imgl>, etc.).

4.7 Cajas de Alerta (markdown)

Los párrafos estándar que comienzan con una de las siguientes cadenas se convierten en cuadros de alerta.

HINT
Convierte el párrafo en un cuadro de Sugerencias.
INFO
Convierte el párrafo en una caja Informativa.
NOTE
Conviérte el párrafo en una caja de Notas.
SEE ALSO:, ALSO
Conviérte el texto en una caja Ver También.
WARNING, WARN
Conviérte el párrafo en una caja de Advertencias.
TODO
Conviérte el párrafo en una caja de tareas, no lo use, más bien termine lo que tenga que terminar.

  •  »
  •  5 Personalización del Tema

5 Personalización del Tema

Ahora esta parte es realmente mucho más simple que con Sphinx y ReadtheDocs. A diferencia de aquellos, aquí la lógica y la apariencia están realmente separados. Sí, sé que RtD tiene dos referencias de hojas de estilo, pero ¡mira los archivos .css! El css principal tiene códigos de color, y el css del tema está lleno de ajustes de márgenes, paddings, desbordamientos, visualizaciones, etc. Esto no es suficiente.

Sugerencia

En gendoc toda la lógica de navegación se implementa en CSS. No se necesita JavaScript.

5.1 La Etiqueta del Tema

En primer lugar, se especifica el tema con la etiqueta <theme>...</theme> del <doc>. Ésta debe contener un nombre de archivo relativo al documento fuente.

5.2 El Tema CSS

Aunque el CSS es una hoja de estilo válida, sólo incluye unos pocos selectores DOM específicos con sólo atributos temáticos.

Selector DOMDescripción
hr,table,th,td Si lo desea, establezca el color del borde y el color de fondo de la cabecera de la tabla.
tr Establecer la alteración de los colores de fondo de las filas.
a Establezca el color y la decoración de los enlaces.
.content Cambie aquí el color y la familia de la fuente por defecto de toda la documentación.
.title Cambia el aspecto de la zona grande de la parte superior izquierda.
.title, .home,
h1>a,h2>a,h3>a,
h4>a,h5>a,h6>a 		Debe establecer el mismo color de fondo para estos para un tema de buen aspecto.
.search Cambiar los colores de la caja de entrada de la búsqueda.
.nav Cambiar el color de la fuente y el color de fondo de la barra de navegación.
.nav p El selector de subtítulos de la TOC. También establece el aspecto de la leyenda "Resultados de la búsqueda".
.nav label Entrada inactiva del nivel superior de la TOC
.nav current La entrada activa del nivel superior de la TOC
.nav a Resultado de la búsqueda Entrada TOC
.nav li>ul>li Color d fondo de los subniveles
.nav li>ul>li>a Color de primer plano de los subniveles
pre Fondo y borde de los bloques preformateados.
.info .hint,
.warn		 Cambia el color de fondo de los cuadros de alerta.
.info>p:firstchild Cambia el color de fondo de la cabecera de las cajas de alerta, .
.btn El estilo de los botones "Anterior" y "Siguiente" en la parte inferior.
.ui1, ui2, ui3,
.ui4, ui5, ui6		 Puede utilizar estas clases para imitar los elementos de entrada de la interfaz de Usuario de su software, como los botones, por ejemplo.
Eso es todo. Esta lista cubre todos los selectores importantes y modificables del CSS del tema. ¿No es demasiado, verdad?

Advertencia

NUNCA cambie la lógica de un tema CSS, como la configuración de los atributos "display", "position", etc. Sólo cambie el color de fondo, el color del borde, el color de la fuente, la familia de la fuente, el tamaño de la fuente, etc.

5.3 Resaltado la Sintaxis

Para ello, tiene que definir unas cuantas clases en el CSS de su tema. En realidad son pocas. Estas clases son genéricas para todos los lenguajes:

ClaseDescripción
.hl_h Parte resaltada manualmente.
.hl_c Resaltado de sintaxis de los comentarios.
hl_p Resaltado sintáctico de pseudoelemento (como las directivas del precompilador, podría ser lo mismo que los comentarios).
hl_o Resaltado de sintaxis de operador.
hl_n Resaltado de sintasix del número literal.
hl_s Resaltado de sintaxis de cadena literal.
hl_t Resaltado de sintaxis de tipo.
hl_k Resaltado de sintaxis de palabra clave.
hl_f Resaltado de sintaxis de función.
hl_v Resaltado de sintaxis de variable.

5.4 Tema de Ejemplo

hr,table,th,td{border-color:#e1e4e5;}
th{background:#d6d6d6;}
tr:nth-child(odd){background:#f3f6f6;}
a{text-decoration:none;color:#2980B9;}
.content{background:#fcfcfc;color:#404040;font-family:Helvetica,sans-serif;}
.title,.home,h1>a,h2>a,h3>a,h4>a,h5>a,h6>a{background:#2980B9;color:#fcfcfc;}
.version{color:rgba(255,255,255,0.3);}
.search{border:1px solid #2472a4;background:#fcfcfc;}
.nav{background:#343131;color:#d9d9d9;}
.nav p{color:#55a5d9;}
.nav label:hover,.nav a:hover{background:#4e4a4a;}
.nav .current{background:#fcfcfc;color:#404040;}
.nav li>ul>li{background:#e3e3e3;}
.nav li>ul>li>a{color:#404040;}
.nav li>ul>li>a:hover{background:#d6d6d6;}
.pre {border:1px solid #e1e4e5;background:#f8f8f8;}
.info{background:#e7f2fa;}
.info>p:first-child{background:#6ab0de;color:#fff;}
.hint{background:#dbfaf4;}
.hint>p:first-child{background:#1abc9c;color:#fff;}
.warn{background:#ffedcc;}
.warn>p:first-child{background:#f0b37e;color:#fff;}
.btn{background:#f3f6f6;}
.btn:hover{background:#e5ebeb;}
.ui1{font-family:Serif;font-size:12px;border-radius:3px;background:#cfcfcf;}
.hl_h{background-color:#ccffcc;}
.hl_c{color:#808080;font-style:italic;}
.hl_p{color:#1f7199;}
.hl_o{color:#404040;}
.hl_n{color:#0164eb;}
.hl_s{color:#986801;}
.hl_t{color:#60A050;}
.hl_k{color:#a626a4;}
.hl_f{color:#2a9292;}
.hl_v{color:#e95649;}

  •  »
  •  6 Extensiones (Plugins)

6 Extensiones (Plugins)

Los plugins se encuentran en el mismo directorio que el archivo gendoc.php, en el subdirectorio "plugins". La versión ANSI C también revisa el directorio "/usr/share/gendoc/plugins". Se nombran de forma coherente, con un prefijo que indica de qué tipo de plugin se trata.

Nota

La similitud entre los plugins de lectura y escritura de archivos no es una coincidencia: el mismo plugin de formato de archivo puede implementar las funcionalidades de lectura y escritura.

6.1 Plugins para Resaltar la Sintaxis

Nombrado como plugins/hl_(lang).json, por ejemplo plugins/hl_python.json.

Utilizado tanto por la versión ANSI C como por la versión PHP. El resaltador genérico funciona bastante bien con cualquier lenguaje de programación (en el peor de los casos, algunas palabras clave del lenguaje u operadores especiales se resaltan como una variable). Pero en caso de que necesite cosas específicas del lenguaje, puede añadir reglas con estos plugins. Estos archivos deben contener una cadena JSON compatible con RFC 8259 con un array de los siguientes campos:

ÍndiceDescripción
0 Una matriz de regexp (expresión regular) que coinciden con los comentarios
1 Un array (arreglos) de regexp (expresión regular) que coinciden con pseudo elementos (como las directivas del precompilador)
2 Una matriz de regexp (expresión regular) que coincide con operadores (como +, -, *, /, >=, =, <= etc.)
3 Una matriz de regexp (expresión regular) que coincida con números (normalmente [0-9]+, pero también podría coincidir con números de coma flotante)
4 Una matriz de cadenas que inician y terminan literales de cadena (normalmente ", ', ` pero podría ser L", b' etc.)
5 Una matriz de caracteres que siempre separan los tokens (normalmente {, }, ; etc.)
6 Una matriz de cadenas que coinciden con los tipos (son palabras clave, sólo que resaltadas de forma diferente, como true, false, nullptr, etc.)
7 Una matriz de cadenas que coinciden con palabras clave (como function for, forach, etc.)
Las cadenas se comparan sin distinción de mayúsculas y minúsculas y, por razones de compatibilidad y rendimiento, las expresiones regulares sólo pueden contener estas reglas (en particular, no se permiten paréntesis):

ÍndiceDescripción
$ Coincide con el final de la línea
.*? Coincide con cero o más apariciones de cualquier carácter hasta que el patrón que le sigue coincida (por ejemplo .*?abc coincide con cualquier cosa hasta que abc coincida)
. Coincide con cualquier caracter.
[(list)] Coincide con los caracteres de la lista. La lista puede contener intervalos (start)-(end), por lo que para que coincida con el guión, utilice \-.
[(list)]? Coincide con cero o una ocurrencia de los caracteres de la lista.
[(list)]+ Coincide con varias (al menos una o más) apariciones de los caracteres de la lista.
[(list)]* Coincide con la aparición múltiple (cero o más) de los caracteres de la lista.
[^(list)] Coincide con cualquier carácter que no esté en la lista.
[^(list)]? Coincide con cero o una ocurrencia de cualquier carácter que no esté en la lista.
[^(list)]+ Coincide con la aparición múltiple (al menos una o más) de cualquier carácter que no esté en la lista.
[^(list)]* Coincide con la aparición múltiple (cero o más) de cualquier carácter que no esté en la lista.
Tenga en cuenta que la barra oblicua (/) y la barra invertida (\) siempre deben escaparse. Por ejemplo:
plugins/hl_c.json
1
2
3
4
5
6
7
8
9
10
11
12
/* reglas de resaltado de sintaxis para el lenguaje C */ [ /* 0 comentario */ [ "\/\/.*?$", "\/\*.*?\*\/" ], /* 1 pseudo */ [ "#.*?$" ], /* 2 operadores */ [ "->", "[=\<\>\+\-\*\/%&\^\|!:\.][=]?" ], /* 3 números */ [ "[0-9][0-9bx]?[0-9\.a-f\+\-]*[UL]*" ], /* 4 cadenas */ [ "\"", "'", "L\"", "L'" ], /* 5 separadores */ [ "[", "]", "{", "}", ",", ";" ], /* 6 tipos */ [ "char", "short", "int", "long", "float", ... ], /* 7 palabras claves */ [ "if", "else", "switch", "case", "for", ... ] ]

6.2 Plugins de Documentación de la API

Nombrado como plugins/api_(lang).php, por ejemplo plugins/api_python.php.

Estos plugins deben implementar una única función con el nombre gendoc_api_(lang), que recibe el contenido del archivo fuente, lo analiza en busca de comentarios doctype y llama a varios métodos de gendoc:: para generar la salida.

plugins/api_c.php 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php /* generar documentación de la API para el lenguaje C */ function gendoc_api_c($str) { /* obtener todos los comentarios con cadenas doctype */ if(preg_match_all("/\/\*\*[^\*](.*?)\*\/[\n](.*?)$/ims", $s, $M, PREG_SET_ORDER)) { gendoc::data_list_open(); foreach($M as $m) { gendoc::data_topic_open(); gendoc::source_code($m[2], "c"); gendoc::data_topic_close(); gendoc::data_description_open(); /* generar una salida de buen aspecto del comentario aquí */ gendoc::data_description_close(); } gendoc::data_list_close(); } }

6.3 Plugins de Lectura de Archivos de Entrada

Nombrados como plugins/fmt_(extensión).php, por ejemplo plugins/fmt_rst.php.

Estos plugins (al igual que los plugins de escritura de archivos) deben implementar una clase con el nombre gendoc_(extension). Para un lector, se requiere un método estático, llamado gendoc_(extension)::parse, que recibe el contenido del documento fuente como cadena, lo analiza y llama a varios métodos de gendoc:: para generar la salida. Los plugins del lector de archivos son responsables de incrementar el contador de número de línea en gendoc::$l cada vez que analizan un carácter de nueva línea (necesario para informar correctamente de los errores).

Por ejemplo:

plugins/fmt_md.php 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php /* Plugin lector de formatos de archivo MarkDown */ class gendoc_md { public static parse($str) { /* hacer algo con el documento fuente en $str * y llamar a los métodos de gendoc para generar la salida */ gendoc::heading(1, "The Hundread Years Old Man Who Climbed Out on the Window and Disappeared"); gendoc::heading(2, "Chapter 1"); gendoc::paragraph_open(); gendoc::text("Lorem ipsum sic dolor amet"); gendoc::paragraph_close(); gendoc::heading(2, "Chapter 2"); /* ... */ /* mantener actualizado el contador de líneas actuales */ gendoc::$l++; } }

Alternativamente, si la generación de la salida a través de los métodos de llamada no es factible, un plugin de lector de entrada podría devolver una cadena con etiquetas gendoc.

plugins/fmt_ext.php 
1
2
3
4
5
6
7
8
9
10
11
12
13
<?php /* Un plugin lector de formatos de archivo que no utiliza los métodos de gendoc:: */ class gendoc_ext { public static parse($str) { /* hacer algo con el documento fuente en $str * y generar una cadena de salida con etiquetas gendoc */ return "<h1>The Hundread Years Old Man Who Climbed Out on the Window and Disappeared</h1>". "<h2>Chapter 1</h2>". "<p>Lorem ipsum sic dolor amet</p>". "<h2>Chapter 2</h2>"; } }

Advertencia

Esto devuelve etiquetas gendoc, y no etiquetas HTML.

6.4 Plugins de Escritura de Archivos de Salida

Nombrados como plugins/fmt_(extension).php, por ejemplo plugins/fmt_md.php.

Estos plugins (al igual que los plugins lectores de archivos) deben implementar una clase con el nombre gendoc_(extension). Para un escritor, deben implementarse todos los métodos que están marcados como "tiene que ser implementado por los plugins de escritor" en la lista de la API más abajo. Además, deben instanciar esa clase y devolver una instancia.

Por ejemplo:

plugins/fmt_pdf.php 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php /* Plugin de creación de archivos PDF */ class gendoc_pdf { /* ganchos (hooks) para generar la salida a esta instancia */ public function heading($level, $id, $name) { /* ... */ } public function paragraph_open() { /* ... */ } public function paragraph_close() { /* ... */ } public function source_code($str, $type = "", $tokens = []) { /* ... */ } /* ... más métodos ... */ /* output this instance to a file */ public function output($fn) { $f = fopen($fn, "wb+"); if(!$f) { gendoc::report_error("unable to write file"); die; } /* imprimir en formato */ fclose($f); } } /* ¡Esto es muy importante! */ return new gendoc_pdf;
Un poco sobre la implementación del gancho de código fuente: el plugin obtiene el código fuente como cadena en $str, pero no tiene que analizarlo por sí mismo, porque gendoc también pasa el código fuente de forma tokenizada (el tercer parámetro $tokens). Aquí cada elemento del array es otro array con los siguientes campos:
ÍndiceDescripción
0 El tipo del token ("" texto, "c" comentario, "o" operador, "n" número, "s" cadena, "k" palabra clave, "t" tipo, "v" variable, igual que en las clases CSS de resaltado).
1 Cadena, la parte de la fuente incluida en este token.

Tanto para el texto preformateado como para el código fuente, el plugin File Format Writer es responsable de manejar las etiquetas <hl> y <hm> (que se incluyen en la cadena de entrada $str, sin importar el formato).

Sugerencia

La concatenación de los segundos campos en la matriz de tokens debería dar como resultado la cadena de código fuente original.

6.5 API

Estos métodos son utilizados por los plugins. Salvo unos pocos, que sólo se implementan en la clase gendoc y que se enumeran al principio, los plugins de escritor tienen que implementar todos ellos (como funciones no estáticas). Los plugins de lectura sólo tienen que implementar el método estático parse, pero llaman a estos métodos para generar la salida. 

1
2
public static function safeid($str)
Convierte una cadena de caracteres en una cadena de caracteres con atributos de URL e id. A veces es una mierda que Internet haya sido diseñado por personas que sólo hablan inglés.
Argumentos
cadena de entrada
Valor de Retorno
cadena la cadena convertida 
1
public static function report_error($msg)
Informa de un error. método de la clase gendoc solamente.
Argumentos
cadena mensaje de error 
1
2
public static function api($c, $fn)
Genera la documentación de la API. Método exclusivo de la clase gendoc.
Argumentos
cadena lenguaje
cadena nombre de archivo 
1
2
public static function include($fn) {
Incluye otro documento fuente. Método exclusivo de la clase gendoc.
Argumentos
cadena nombre de archivo 
1
2
public static function doc($str)
Analiza la etiqueta <doc>. Método exclusivo de la clase gendoc.
Argumentos
cadena con sub-etiquetas <doc> 
1
2
public static function hello_open()
Inicio de la etiqueta <hello>. método de la clase gendoc solamente. 
1
2
public static function caption($name)
Añade un título a la TOC. Método exclusivo de la clase gendoc.
Argumentos
cadena nombre del título 
1
2
public static function heading($level, $name, $id = "", $alias = "")
Añade un título. Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadena "1" a "6"
cadena de encabezamiento nombre legible por el Usuario
cadena id de etiqueta de encabezado 
1
2
public static function paragraph_open()
Inicia un párrafo. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function paragraph_close()
Termina un párrafo. Debe ser implementado por los plugins de los escritores. 
1
2
public static function bold_open()
Inicia texto en negrita. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function bold_close()
Detiene el texto en negrita. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function italic_open()
Inicia texto en cursiva. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function italic_close()
Detiene el texto en cursiva. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function underline_open()
Inicia el texto subrayado. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function underline_close()
Detiene el texto subrayado. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function strike_open()
Inicia el texto tachado. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function strike_close()
Detiene el texto tachado. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function superscript_open()
Inicia texto en superíndice. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function superscript_close()
Detiene el texto en superíndice. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function subscript_open()
Inicia el texto de subíndice. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function subscript_close()
Detiene el texto de subíndice. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function quote_open()
Inicio del texto de la cita. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function quote_close()
Detiene el texto de la cita. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function line_break()
Añade salto de línea. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function ordered_list_open()
Inicio de lista ordenada. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function ordered_list_close()
Fin de la lista ordenada. Tiene que ser implementado por los complementos del escritor. 
1
2
public static function unordered_list_open()
Inicia una lista desordenada. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function unordered_list_close()
Finaliza la lista desordenada. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function list_item_open()
Elemento de la lista de inicio. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function list_item_close()
Fin de la lista. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function data_list_open()
Inicia la lista de datos. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function data_list_close()
Lista de datos finales. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function data_topic_open()
Inicio del tema de los datos. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function data_topic_close()
Tema de datos finales. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function data_description_open()
Descripción de los datos de inicio. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function data_description_close()
Descripción de los datos finales. Debe ser implementado por los plugins de los escritores. 
1
2
public static function grid_open()
Rejilla de inicio. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_row_open()
Inicio de la fila de la cuadrícula. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_cell_open()
Inicio de la celda de la cuadrícula. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_cell_wide_open()
Inicio de la celda de rejilla ancha. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_cell_close()
Fin de la celda de la rejilla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_row_close()
Fin de la fila de la cuadrícula. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_close()
Fin de la rejilla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_row_close()
Fin de la fila de la cuadrícula. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function grid_close()
Final de la rejilla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_open()
Tabla de inicio. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_row_open()
Inicio de la fila de la tabla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_header_open()
Inicio de la cabecera de la tabla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_header_wide_open()
Inicio de la cabecera de la tabla ancha. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_header_close()
Encabezado de la tabla final. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_cell_open()
Inicio de la celda de la tabla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_cell_wide_open()
Inicio de la celda de la tabla ancha. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_number_open()
Inicio de la celda de la tabla numérica. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_number_wide_open()
Inicio de la celda de tabla numérica ancha. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_cell_close()
Finalizar la celda de la tabla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_row_close()
Fin de la fila de la tabla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function table_close()
Final de la tabla. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function teletype($str)
Añade texto en teletipo (monospace). Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadena el texto 
1
2
public static function preformatted($str)
Añade texto preformateado (monospace multilínea). Tiene que ser implementado por los plugins de escritor.
Argumentos
cadena el texto 
1
2
public static function source_code($str, $type = "", $tokens = [])
Añade el código fuente. Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadena el código fuente como cadena
string el tipo de idioma (o cadena vacía)
código fuente con tokens de matriz (para resaltar la sintaxis) 
1
2
public static function prev_link()
Añade enlace a la página anterior. Podría ser implementado por los plugins de los escritores. 
1
2
public static function next_link($id, $name)
Añade enlace a la página siguiente. Podría ser implementado por los plugins de los escritores.
Argumentos
cadena id etiquetas de encabezamiento
cadena nombre encabezado legible por el Usuario 
1
2
public static function internal_link($name, $lnk = "")
Añade un enlace interno a cualquier título. Podría ser implementado por los plugins de los escritores.
Argumentos
cadena nombre encabezado legible por el Usuario
cadena a la que enlazar, podría ser una cadena de sustitución para las siguientes referencias 
1
2
public static function resolve_link($subst, $id)
Resuelve un enlace interno hacia adelante. Podría ser implementado por los plugins de los escritores.
Argumentos
cadena la cadena de sustitución que se utilizó como id
cadena el id real 
1
2
public static function external_link_open($url)
Inicia un enlace externo. Podría ser implementado por los plugins de los escritores.
Argumentos
URL's como cadena 
1
2
public static function external_link_close()
Termina un enlace externo. Podría ser implementado por los plugins de los escritores. 
1
2
public static function user_interface_open($type)
Inicia un elemento de la interfaz de Usuario. Debe ser implementado por los plugins de los escritores.
Argumentos
cadena de tipo "1" a "6" 
1
2
public static function user_interface_close()
Finaliza un elemento de la interfaz de Usuario. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function keyboard($key)
Añade una tecla del teclado. Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadena nombre de la clave 
1
2
public static function mouse_button($type)
Añade una imagen del botón del ratón. Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadena "l" (botón izquierdo), "r" (botón derecho) o "w" (rueda) 
1
2
public static function image($align, $fn, $a = [], $img = "")
Añade una imagen. Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadena de caracteres "t" (alineada como texto), "l" (izquierda), "r" (derecha), "c" (centrada) o "w" (ancha, centrada)
cadena nombre de archivo de la imagen
arreglo índice 0 ancho, 1 alto, 'mime' tipo mime
cadena datos de la imagen 
1
2
public static function figure($name)
Añade un título de imagen. Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadena descripción de la figura 
1
2
public static function alert_box_open($type)
Inicia un cuadro de alerta. Tiene que ser implementado por los plugins de los escritores.
Argumentos
cadenas ya sea "info", "hint", "note", "also", "todo" o "warn" 
1
2
public static function alert_box_close()
Termina una caja de alerta. Tiene que ser implementado por los plugins de los escritores. 
1
2
public static function text($str)
Añade cualquier texto arbitrario a la salida. Si una etiqueta está abierta, entonces a eso. Tiene que ser implementado por los plugins de escritor.
Argumentos
cadena el texto 
1
2
public static function parse($s)
Analiza un documento fuente. Debe ser implementado por los plugins lectores de formatos de archivo.
Argumentos
cadena contenido del documento fuente
gendoc::\$fn nombre del archivo fuente
Valor de Retorno
gendoc::\$l número de línea actual, debe ser incrementado por el plugin de lectura 
1
2
public static function output($fn)
Documentación de salida. Tiene que ser implementado por los plugins de los escritores.
Argumentos
nombre de cadena del archivo en el que se va a escribir

  •  »
  •  7 Consejos y Trucos

7 Consejos y Trucos

7.1 El Problema de No Refrescarse

Algunos navegadores se niegan a recargar la página si se introduce una URL con una etiqueta de anclaje (la que va después de '#'). Además de escribir la URL y pulsar ↵ Enter, también hay que pulsar F5 (refrescar la página). Esto no debería ser, pero podría ser problemático al enlazar la documentación desde otras fuentes, por lo que el documento generado también acepta las etiquetas como cadena de consulta de la URL (después de '?' en la URL). Todos los navegadores piensan que una URL con una cadena de consulta tiene que ser recargada. Estos tipos de enlaces se redirigen de forma transparente a una URL con una variante de anclaje (que entonces está bien, porque la recarga ya se ha producido).

7.2 No JavaScript

No es un problema. La barra de navegación de la izquierda con el TOC funcionará como se espera. También lo hará el "Inicio" en la parte superior, y los enlaces "Anterior" y "Siguiente" en la parte inferior. Sin embargo, los enlaces internos creados mediante la etiqueta <a> sólo funcionarán dentro de la misma página, y no cambiarán de página (debido al problema de no recargar con anclas explicado anteriormente, y la solución requiere JavaScript).


  •  »
  •  8 Licencia

8 Licencia

8.1 Generadores de gendoc

gpl3-1.pngTanto el código fuente en C ANSI como el script en PHP están disponibles bajo la licencia GPLv3+ o cualquier versión posterior de la misma. 

 Este programa es software libre; puede redistribuirlo y/o modificarlo
 bajo los términos de la Licencia Pública General GNU publicada
 por la Fundación para el Software Libre; ya sea la versión 3 de la Licencia,
 o (a su elección) cualquier versión posterior.

 Este programa se distribuye con la esperanza de que sea útil,
 pero SIN NINGUNA GARANTÍA; ni siquiera la garantía implícita de
 COMERCIALIZACIÓN o ADECUACIÓN A UN PROPÓSITO PARTICULAR.
 Consulte la Licencia Pública General de GNU para más detalles.

 Debería haber recibido una copia de la Licencia Pública General GNU
 junto con este programa; si no es así, escriba a la Free Software
 675 Mass Ave, Cambridge, MA 02139, USA.

8.2 Iconos Incrustados

CC-BY-4.0.pngEsos pocos iconos incrustados en la salida provienen de iconos públicos de FontAwesome y tienen licencia CC-BY-4.0. 

Usted es libre de:

 - Compartir - copiar y redistribuir el material en cualquier medio o formato

 - Adaptar - remezclar, transformar y construir sobre el material
     El licenciante no puede revocar estas libertades siempre y cuando usted siga
     los términos de la licencia.

Bajo los siguientes términos:

 - Atribución - Debe dar el crédito apropiado, proporcionar un enlace a
     la licencia, e indicar si se han realizado cambios. Puede hacerlo de
     de manera razonable, pero no de forma que sugiera que el
     que el licenciante lo respalda a usted o a su uso.

8.3 Hoja de Estilo Incrustada

CC-BY-4.0.pngMe gustaría decir que el CSS incrustado es de RtD, pero la verdad es que el estilo de RtD era un desastre y tuve que reescribir todo desde cero. Así que parece y se siente como la hoja de estilo original de RtD, pero es una reescritura completa desde cero, con licencia CC-BY.

8.4 Javascript Incrustado

CC-BY-4.0.pngEl código JavaScript mínimo que se introduce en los documentos (para proporcionar resultados de búsqueda) también tiene licencia CC-BY.