WackoWiki Markup

También disponible en Deutsch, English, Русский.


Este artículo, bastante largo, trata de cómo apareció el "marcado Wacko" y por qué es como es ahora. Si no sabes lo que es el "Wacko markup" y, especialmente, lo que es un "wiki", deberías leer un par de artículos de documentación en el sitio del proyecto WackoWiki y, especialmente, un artículo sobre el concepto de wiki.



1. Sobre el marcado Wacko

En resumen, el marcado Wacko es una forma especial de formatear el texto, que permite con un mínimo de caracteres especiales y una mínima distorsión visual del "texto fuente" obtener un hermoso HTML después de la conversión del programa.


Las capacidades de marcado de Wacko son suficientes para el diseño completo de páginas, grandes y pequeñas. Además de los modificadores tradicionales de texto "cursiva", "negrita", "subrayado" y "tachado", también hay un marcado de listas (incluso multinivel), encabezados, tablas, imágenes, resaltado de citas y muchas otras cosas.


El marcado Wacko se utiliza en el motor wiki WackoWiki y en otros proyectos de diversos desarrolladores. Para incrustar un marcado Wacko en su proyecto, sólo tiene que descargar e incorporar los siguientes componentes a su proyecto:


  • Formateador Wacko, una clase PHP que convierte el marcado Wacko en HTML
  • Editor visual para wikis. Este es un complemento opcional, pero extremadamente conveniente, del formateador Wacko.

El texto fuente de este artículo está escrito en el formato de marcado Wacko y está disponible para su revisión.

2. Principios básicos

Aunque originalmente heredamos el marcado Wacko del proyecto WakkaWiki (anteriormente disponible en http://wakkawiki.de, pero ahora no disponible), se basó en principios claros que determinaron su éxito posterior.


Así, la formación de las reglas de marcado, aunque se hizo de forma "evolutiva", siguió guiándose por un pequeño conjunto de principios que ayudaron a que el marcado siguiera siendo cómodo y natural.


Estos principios se inventaron para alcanzar los siguientes objetivos


  • Reducir la probabilidad de "activación accidental" (es decir, cuando el texto ordinario se percibe como parte del marcado)
  • Lograr un marcado intuitivo y fácil de recordar;
  • Proteger el entorno del texto formateado de posibles erratas del autor.

2.1. La semántica debe pasar por la sintaxis

Cualquier marcado wiki se basa en el principio WYTIWYG, por lo que cada regla de marcado Wacko intenta reflejar el significado (semántica) con su propio diseño (sintaxis). Dado que todo el diseño se realiza con texto simple -símbolos que se pueden escribir desde el teclado- hemos tratado de encontrar combinaciones que reflejen el significado:


  • **negrita** — asteriscos para el texto en negrita, que se separa de la masa total;
  • //cursiva// — la cursiva está formada por líneas trenzadas;
  • --tachado--__subrayado__ respectivamente;
  • El aspecto de las listas es el mismo que el que utilizamos para escribir dichas listas en los campos de entrada de texto.

Aquí nos hemos alejado del clásico marcado wiki con "sólo 5 apóstrofes en cada lado".

2.2. Caracteres emparejados

Como habrá observado, todos los ejemplos anteriores de marcas de trabajo contienen caracteres emparejados. Gracias a este principio, el texto "simplemente insertado desde algún otro editor" no requiere ningún preprocesamiento especial: es poco probable que contenga los caracteres "emparejados" de esta manera.


Hay casos en los que se utilizan secuencias triples, cuádruples e incluso 5-6 consecutivas para resaltar los títulos a diferentes niveles. Cuantos más caracteres, más profundo es el nivel del título.

2.3. El marcado está en contacto con el texto interno

Es posible que usted sea una de esas personas que siempre escriben un guión como "dos menos" (así: --). De todos modos, es evidente que los autores se encuentran entre esas personas. Es más, hay muchos textos que contienen el doble menos tanto como guión como en otras calidades.


El principio de que el marcado debe estar "en contacto" con el texto interno evita esa transformación accidental del "texto plano" en texto marcado. Este principio no se ha introducido para todas las reglas de marcado, sino para aquellas en las que puede aparecer un único carácter emparejado en el "código fuente" (por ejemplo, para el tachado).


Es decir, --que es como funciona--, y si -- lo hacemos -- — el texto no será tachado.


Hay que tener en cuenta que esta regla, la anterior y la siguiente tienen como objetivo minimizar la "activación accidental" del procesamiento de marcas, es decir, librarse de las situaciones en las que algunos caracteres del texto se perciben como parte de las marcas.

2.4. Traducir cadena — completar algún fragmento de texto

A diferencia, por ejemplo, del marcado OpenWiki, el salto de línea en el "código fuente" del marcado Wacko se percibe literalmente como un salto de línea (dos saltos de línea iniciarán un nuevo párrafo). Por lo tanto, aceptamos que un salto de línea es la finalización de un texto terminado, como una frase o incluso un párrafo.


Algunas reglas de marcado de Wacko: reglas que cambian la configuración de la fuente del texto (negrita, cursiva, subrayado, etc.) y los encabezados – la mayoría de estas reglas sólo funcionan en un fragmento de texto limitado a los saltos de línea. El uso de este principio permite resolver tres problemas a la vez


  • reducir la probabilidad de "activación accidental";
  • simplificar la percepción del marcado (porque el "principio" y el "final" de la selección no están lejos el uno del otro)
  • reducir el papel del "estilo de letra" al formato de los pequeños fragmentos de texto, lo que tiene un efecto positivo en la percepción del resultado.

2.5. Las marcas "rotas" no deben romper el HTML alrededor del texto

Los principios anteriores nos permiten resolver una tarea muy importante: "proteger" el HTML alrededor del texto formateado de posibles errores de formato. Gracias a la regla "pegajosa", podemos determinar casi siempre qué parte del marcado es el "principio" y cuál es el "final" del marcado, así como insertar ambas etiquetas HTML (o no insertar ninguna) a la vez. En el caso de las reglas de un marcado Wacko que no tienen un "emparejamiento" tan fácil de conseguir, hay que hacer todos los esfuerzos posibles para lograr un resultado "ajustado". Y, como vemos, se ha conseguido.

2.6. Debe haber una forma de escribir exactamente lo que quiero escribir

Cualquier marca debe poder "escapar", es decir, hacer que se ignoren las reglas de marcado y que el fragmento de texto pase por el formato sin cambios. Este artículo es un ejemplo de cuándo es necesario ese "escape".

2.7. Cambio mínimo de la disposición del teclado

Por último, pero no menos importante, ningún autor anglófono podría tener un principio muy importante, pero para los usuarios de habla rusa este principio determina en gran medida la comodidad resultante.


La esencia del principio es seleccionar las reglas de marcado de tal manera que la mayoría de ellas (especialmente las reglas de uso frecuente) puedan ser tecleadas, permaneciendo en la disposición rusa. Al mismo tiempo, no hay que olvidar la misma accesibilidad para el público de habla inglesa.


Así, la sintaxis de referencia original [[WikiLink Descripción textual]] encontró su duplicado ((WikiLink Texto en el enlace)), que puede utilizarse tanto en la maquetación inglesa como en la rusa. Muchas reglas de marcado wiki tienen esta valiosa propiedad.

3. Reglas de marcado

Aplicando estos principios, hemos desarrollado y mejorado el conjunto original de reglas, estudiando cuidadosamente los diferentes motores wiki. Si me atreviera a presumir, diría que el marcado final de la wiki incorporó lo mejor de las diferentes reglas de marcado, manteniéndose delgado y simple. Sin embargo, ¡maldita sea! Como resultado de nuestro trabajo, nuestro marcado ha incorporado lo mejor de las diferentes reglas de marcado, permaneciendo delgado y simple.


En este capítulo se describe brevemente cómo hemos llegado a las reglas de marcado más importantes.

3.1. Marcado de una sola línea

Las reglas de marcado de una sola línea eran todas aquellas que utilizaban símbolos que se empleaban a menudo en el "texto plano" y que se referían a algún diseño "local" del texto:

  • negrita, cursiva, subrayado
  • texto pequeñomonoespaciado
  • los encabezados (que no tienen sentido cuando se dividen en líneas)
  • enlaces (cuyo texto también es mejor que siga siendo "corto")
  • gradoíndices (que sólo funcionan dentro de una palabra)

3.2. Marcaje multilínea

El resto de las reglas de marcado funcionan con grandes fragmentos de cadenas. Esto se debe principalmente a que su diseño se aplica a menudo a grandes fragmentos de texto.


Es, por ejemplo, un tachado
O una cita que capta todo el párrafo.

3.3. Anulación de marcas

La cancelación de marcas se implementa de dos maneras:

  • anulación en bloque con "caracteres emparejados" "";
  • anulación en bloque (introduciendo un carácter especial antes de la secuencia cancelada) con el símbolo ~ (tilde).

El primer método permite anular el marcado de un texto grande con relativa facilidad, y el segundo es conveniente cuando se quiere anular el marcado de sólo una o dos palabras o incluso de un "carácter emparejado". Además, el escape de tilde también nos permite mostrar comillas dobles, como en el ejemplo anterior.


Si abre !/source de este artículo, encontrará que la cancelación de marcas es muy común — de otra manera no habríamos podido dar ningún ejemplo de marcas en su forma no procesada.

3.4. Referencias e imágenes

Wacko markup, convierte automáticamente las URLs del texto en hipervínculos. Si está claro que la URL apunta a una "imagen" (por ejemplo, termina con .jpg.gif) — se inserta una imagen en el texto formateado utilizando la etiqueta <img>. Esto es conveniente porque permite insertar enlaces desde el portapapeles sin pensarlo mucho, obteniendo un resultado de bastante calidad.


Hay dos etiquetas que tienen varias variantes de uso para un enlace con una descripción:


  • ((URL Texto descripción))
  • [[URL Descripción de texto]] — igual, pero menos conveniente
  • ((Referencia Wiki Con Espacios == Descripción de Texto)) — permite insertar espacios en el "lado izquierdo" de un enlace wiki (también funciona en corchetes)

El concepto de enlace wiki permite insertar enlaces "internos" más fácilmente y el marcado de Wacko también lo tiene en cuenta. Todos los enlaces que no son "internos" se hacen inmediatamente como "externos", lo mismo ocurre con las direcciones de correo electrónico.


Las descripciones de las imágenes se colocan de forma muy similar a las descripciones de los enlaces:

  • ((imagen.jpg Descripción)) — es una forma de poner el título de una imagen
  • ((URL imagen_pequeña.jpg)) — es una forma de poner un enlace de una imagen

3.5. Estructuras de las listas

¿Cómo es más natural para una persona escribir listas, numeradas y no numeradas, así como anidadas?


**Probablemente algo así:**
  * elemento de la lista-1
  * elemento de la lista-2
  * sublista
    * elemento de la sublista-1
    * elemento de la sublista-2
  * continuación de la lista
  
  1. Lista numerada uno
  2. segundo elemento
    1. así como con la lista anidada
    6. La numeración puede ser confusa

¿Qué quieres obtener?


  • elemento de la lista-1
  • elemento de la lista-2
  • sublista
    • elemento de la sublista-1
    • elemento de la sublista-2
  • continuación de la lista

  1. lista numerada uno 
  2. segundo elemento
    1. así como con una lista anidada
    2. la numeración puede ser confusa

Así es como se organizan las reglas de marcado de las listas en un marcado Wacko. Este ejemplo ilustra bien por qué todas las viñetas de las listas se desplazan inicialmente un par de caracteres hacia la derecha: así se evita la confusión con el texto en negrita.


La sangría se selecciona igual a dos caracteres basándose en el principio de los "caracteres emparejados", que son casi inexistentes en los textos ordinarios. Algunos otros formatos de wiki utilizan de cinco a seis espacios: ¡imagínese cómo sería un tercer nivel de anidamiento en <textarea>!


El diseño original de c2.com utiliza un carácter de tabulación, lo que nos parece muy poco razonable: en la mayoría de las interfaces, el tabulador realiza funciones de navegación, y en algunos navegadores es imposible introducir un carácter de tabulación en el campo de entrada.


La numeración en las listas numeradas se realiza de forma automática, lo que permite eliminar fácilmente elementos, añadir otros nuevos y transferirlos a la jerarquía. Si necesita una lista numerada que empiece por el número tres, comience por 1.#3 Así.


  1. Así.

3.6. Marcaje de tablas

Las tablas son una de las partes más difíciles de cualquier marcado. La mejor solución es un conjunto de reglas cuyo marcado imita las líneas verticales de la cuadrícula de la tabla. Esto es más fácil que dibujar toda la cuadrícula con guiones, pluses y líneas verticales, y al mismo tiempo da una tabla que es totalmente legible en el "código fuente". Puede encontrar más información sobre el marcado de tablas en la sintaxis de marcado de Wacko. También hay ejemplos.


Por desgracia, el marcado de tablas es el fragmento más "vulnerable" de un marcado Wacko, que permite "romper" la estructura del entorno externo de una página en algunos casos. Es un pequeño precio que decidimos pagar por la claridad de la sintaxis y la rapidez de su análisis sintáctico.

4. Desarrollo del marcado

En primer lugar, no se han descrito todas las reglas de marcado, sólo las más importantes. Si le falta algo, consulte primero la documentación más completa. Si queda claro que las reglas existentes no son suficientes, hay que ampliar el marcado. Así es como aparecieron la mayoría de nuestras reglas de marcado.

4.1. ¿Cuándo hay que cambiar el marcado existente?

Nunca.


Esto es así si no hablamos de introducir nuevas reglas, sino de cambiar las existentes. Cambiar el comportamiento del marcado, que te parece útil, puede molestar significativamente a otras personas que están acostumbradas a trabajar con ese marcado. Imagina que en algunos sitios <b> funcionara como <a> y viceversa.


Por supuesto, si hay una regla dentro de tu proyecto particular que te perturba significativamente para hacerlo, entonces puedes pensar en reemplazarla. Cuando sustituya/elimine una regla, piense en cómo será aceptada por todos los que están acostumbrados al marcado estándar.

4.2. ¿Cuándo merece la pena introducir nuevas entidades de marcado?

Lo menos posible.


El marcado Wacko tiene el concepto de "resaltadores", que son entidades complementarias que pueden añadirse fácilmente sin ocupar el "espacio de marcado primario", es decir, los caracteres emparejados. El concepto de resaltador se describe a continuación.


Si simplemente introduce un nuevo "carácter emparejado" sin pensarlo bien, hará que sus usuarios se lo piensen. El hecho de que utilicen un marcado Wacko sin dudar sólo ha sido posible porque los desarrolladores han pensado mucho en las consecuencias de cada nueva regla.


Si quieres ampliar tu marcado, lo mejor es que te pongas en contacto con los autores de este formato: quizá ya tengan una idea o estarán encantados de aceptar la tuya. La acción coordinada siempre es más eficaz.

5. Transformaciones complejas y funciones de servicio

La idea del marcado Wacko, tomada de WakkaWiki y extendida por los autores, proporciona dos maneras de mejorar significativamente las capacidades de marcado e incrustar diferentes funcionalidades complejas en las páginas.


Estas son las dos formas que recomendamos utilizar en primer lugar a aquellos que quieran ampliar sus reglas de marcado. Entre otras cosas, el uso de estos métodos no requiere un análisis detallado de la clase inicial del formateador Wacko.

5.1. El concepto de resaltadores

Los resaltadores son un concepto que permite al desarrollador implementar una lógica compleja de conversión de un bloque de texto, y permite al usuario transferir fácilmente este bloque de texto al diseño.


En el cuerpo del marcado de Wacko, el uso del resaltador tiene el siguiente aspecto %%(html)<div class="test">testdiv</div>...%% — es decir, se utiliza el "carácter coincidente" %%%, indicando entre paréntesis qué función de resaltado debe pasar lo que está dentro del bloque del resaltador.


El desarrollador, escribe estas funciones que toman una variable de texto, hacen algunas transformaciones con ella y luego devuelven el resultado.


Por lo general, esta sintaxis se utiliza para varios "colores" de texto — para resaltar la sintaxis, el marcado de los registros de chat y correos electrónicos, la inserción de algunos bloques de texto al azar.


Este concepto es una forma de ampliar fácilmente el marcado, pero también es una forma de hacerlo;

  • sin utilizar "caracteres emparejados" adicionales;
  • sin conocer los detalles del trabajo del formateador.

5.2. Concepto de acciones

Las acciones son un concepto que permite al desarrollador implementar alguna funcionalidad compleja (tal vez incluso requiriendo un diálogo con el usuario), y al usuario proporcionar fácilmente el acceso a esta funcionalidad en el lugar adecuado de la página.


En el cuerpo del marcado de Wacko, el uso de la "acción" tiene el siguiente aspecto {{changes page="/Dev"}} — "carácter emparejado" {{ con la indicación del nombre de la "acción" y parámetros adicionales.


El desarrollador escribe estas funciones de la misma manera que escribe los "resaltadores".


Es con las "acciones" en WackoWiki se implementa una parte importante de la funcionalidad para trabajar con las páginas (construcción de un directorio, listas de cambios recientes / comentarios, búsqueda).


Este concepto es una forma de "incrustar" alguna funcionalidad compleja en una página, sin entrar en los detalles del trabajo del Formateador Wacko.

5.3. Interwiki – modificación del marcado de enlaces

También hay una forma de ampliar la sintaxis de marcado de enlaces añadiendo reglas adicionales como ((repositorio:dirección))((repositorio:dirección Texto de enlace)). En este caso la dirección se especifica como dos fragmentos "depósito" y "nombre en este depósito". Por ejemplo, para LiveJournal la dirección tendrá este aspecto: ((lj:mendokusee)), y para el enlace a la traducción de una palabra inglesa se puede escribir ((lingvo:fascinating)).


Este concepto (al igual que gran parte de nuestro marcado) se ha heredado de la wiki, y originalmente estaba pensado para dirigir las páginas a otros nodos de la wiki. Como hemos visto, también es muy útil para otros fines menos específicos.


Sin embargo, hay otras formas de implementar una modificación similar. Los siguientes formatos de marcado se utilizan en diferentes sitios:

  • [[ljuser romochka]] (fuente)
  • [[xpointUser280 Vladimir Palant]] (fuente)
  • [[php ereg_replace]] (fuente)

La variante interwiki (enlaces a través de dos puntos) nos parece más correcta al menos porque se utiliza en muchos sistemas y es un estándar de facto. Además, interwiki no causa un conflicto con la habitual [[Descripción de enlaces]].

6. Detalles técnicos

Este artículo no es un lugar en el que pueda entender los detalles de cómo funciona el Formateador Wacko, sin embargo, vale la pena mencionar algunos de los puntos principales.


En primer lugar, el formateador en sí se basa en "expresiones regulares (concretamente, Expresiones Regulares Compatibles con Perl) y funciona según el principio de "análisis recursivo". Esto significa que intenta dividir el texto en los fragmentos "más grandes" del marcado, y luego se usa a sí mismo para analizarlos. Esto, a su vez, significa que no puedes poner las mismas reglas de marcado: por ejemplo, así — **ejemplo de marcado anidado** no funcionará. Pero hay que estar de acuerdo en que esto no es necesario.


En segundo lugar, el formateador trabaja en varias pasadas para la mejor protección contra la "activación accidental". El primer paso es un conjunto abreviado de reglas que permite "escapar" de los fragmentos de texto, prohibiendo su marcado. En la misma pasada se asignan todos los "resaltadores", protegiendo así contra el solapamiento de los resaltadores por otro marcado. La segunda pasada del formateador procesa todas las reglas restantes.


En tercer lugar, el formateador permite llevar a cabo el almacenamiento en caché del resultado formateado. Como el marcado contiene la funcionalidad que exige la interacción con el usuario, y también los enlaces a las páginas (que pueden procesarse de forma diferente para los distintos usuarios) para almacenar en caché el "resultado semiacabado" en el que sólo estaban las reglas relativas a los enlaces y las "acciones". La última pasada del formateador, la más rápida de todas y que no necesita recursividad, se realiza al mostrar el contenido de una página basada en este "resultado semiacabado", y hace el marcado de los enlaces y la inserción de las "acciones".


Si le interesan los aspectos más profundos del formateo – bienvenido al formateo de código.

7. Advertencias

Este artículo se ha escrito para explicar cómo y por qué se inventaron las reglas del marcado Wacko, de dónde proceden los "caracteres emparejados" y por qué nos gustaría esperar que los nuevos proyectos que utilicen el formato de edición del marcado Wacko sigan los principios que lo sustentan.


Si tienes alguna pregunta, no dudes en plantearla en los comentarios o personalmente a los autores del artículo.


Con respeto, el equipo de WackoWiki y los autores del artículo:

8. Referencias

  1. El proyecto WackoWiki
  2. Formateador para las marcas descritas
  3. Editor visual para las marcas descritas
  4. WakkaWiki — raíces históricas WackoWiki
  5. OpenWiki — otras raíces históricas de la sintaxis de marcado Wacko...
  6. Descripción de los conceptos wiki
  7. Sintaxis de marcado Wacko
  8. Ejemplos de marcado clásico en c2.com
  9. WikiName — El concepto de enlaces wiki