dokuwiki (exportar a Mallard)

Esta es una sugerencia de MarcoVillegas: en vez de un editor adaptado, usar un wiki y añadir el output en formato Mallard.

Para dokuwiki la cosa se ve sencilla, en inc/parser/parser.php describen listas de tokens y si son únicos o de apertura y cierre, luego los parsers implementan métodos, ejemplo inc/parser/xhtml.php, y finalmente un renderer escupe el resultado

Habría que hacer un parser (fácil, parece) y un renderer, ojo que hay plugins q pueden hookearse al renderizado.

MoinMoin

(FIXME)

TinyMCE

TinyMCE también está interesante y parece tener un diseño más sencillo que CKEditor, aunque a primera vista no parezca. http://tinymce.moxiecode.com/ Hay que revisar el plugin de bbcode, que es lo más cercano a lo que queremos.

CKEditor

CKEditor está basado en plugins. Bajar el código de http://ckeditor.com/download y revisar:

_source/plugins/
_source/core/

Se deben adaptar los plugins:

_source/plugins/list/
_source/plugins/image/
_source/plugins/table/

Y crear un plugin para insertar:

notas/warnings/info/ideas (el bloque ancho)

Ver http://www.gnome.org/~shaunm/mallard/spec.html

Además, hay que editar _source/core/dtd.js para que entienda el DTD de mallard, según parece CKEditor está hardcodeado a XHTML. Revisar si _source/core/xml.js posibilita cargar documentos XML cualquiera, eso permitiría cargar documentos de Mallard sin mayor esfuerzo y concentrarnos en los plugins.

Descripción de Mallard

Mallard permite hacer documentacion para GNOME, existen documentacion por proyecto, y esta esta definida por archivos en xml con extension .page

Todo empieza por una pagina de indice, al estilo web, debe existir un archivo index.page

Reglas generales:

Todo documento en mallard debe empezar por esta seccion:

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">

o asi

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="groups">

donde el type cambia entre guide y topic, la pagina principal usa guide y las demas como topic, cuando se tratan de paginas que pertenecen a secciones e indican que son acciones o tareas se agregan tambien style="task" para especificar cierto estilo, en las paginas solamente de descripcion o introduccion no va. por ultimo contiene una id para identificar la pagina.

Como la etiqueta <page> necesita de </page> para terminar la descripcion (al igual que <html> </html) al final de toda la pagina debe ponerse una etiqueta </page> para definir el fin de la pagina.

Toda elemento debe cerrarse asi <elemento>contenido</elemento> a excepcion de <link /> que se cierra con '/' al final y <revision />

luego de <page>, debe haber un <info> </info>, en el cual se debe ubicar la informacion general del documento, asi por ejemplo:

<info>
  <desc>Flickr Uploader.</desc>
  <revision pkgversion="0.13" version="0.1" date="2009-11-13" status="incomplete"/>
  <credit type="author">
    <name>Germán Póo-Caamaño</name>
    <email>gpoo@gnome.org</email>
  </credit>
</info>

(pregunta para shaun, se debe poner <desc> </desc> en el index.page???)

Como se puede ver tiene una etiqueta <desc> </desc> en la cual se debe incluir la descripcion general del software a documentar. Esta descripcion no se mostrara al usar yelp.

Luego una etiqueta <revision /> donde se mostrara la version del software o paquete, (pkgversion) la version de la documentacion (version) la fecha (date) y el estado de la documentacion (status), en status se ha visto: incomplete, review, draft

Y en algunas paginas se ha visto:

<!--
      <e:review by="shaunm@gnome.org" date="2009-08-31" status="done"/>
      -->

Para definir quien lo reviso, y si esta se completo (done)

Luego una etiqueta <credit> con un atributo type='author' para definir el author de la documentacion

Luego un elemento <name> </name> con el nombre del autor y uno con <email> </email> para la direccion de correo electronico del autor. Se pueden tener varios autores cada uno con su propia etiqueta credit

Al final no se debe olvidar cerrar </credit> para terminar la parte de los creditos y </info> para terminar la descripcion general de la pagina.

en algunos documentos tambien antes de agregar </info> se puede poner

<!--
    <copyright>
      <year>2009</year>
      <name>GNOME Documentation Project</name>
    </copyright>
-->
    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />

Ahora esta es la parte que viene despues de <info> </info> y es la que se visualiza

<title>Postr</title>

Esta sirve para poner el titulo de la pagina, luego viene algo como esto

<p>Getting started with <app>Postr</app></p>

donde se pone la descripcion del software, se recomienda usar <app> </app> cada vez que se menciona la aplicacion, para que esta palabra tenga cierto estilo diferente y enfatizante.

Luego de esto se deben definir las secciones que tendra la documentacion con la etiqueta seccion asi:

<section id="getting-started" style="2column">
    <info>
      <title type="link">Getting Started</title>
    </info>
    <title>Getting Started</title>
</section>

(pregunta para shaun, es necesario el <info> o solamente el <title> despues del info.)

<title> es el titulo de la seccion que se va a describir en varios pasos si se desea, se debe poner tantas <section> </section> como sean necesarias.

en <section> estan los atributos id para identificarlo y esta style="2column" que seria el unico valor para ese atributo y define que se visualizaran en 2 columnas, si se pone un valor diferente a 2column se mostrara en una sola columna, si no se pone el atributo tambien mostrara en una sola columna. Lo que quiere decir que por ahora solo admite las 2 columnas, cualquier otro valor o si simplemente se omite, mostrara una sola columna.

Para paginas tipo 'topic' por ejemplo

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="introduction">

luego viene <info> </info> asi:

<info>
  <link type="guide" xref="index"/>
  <desc>Introduction to the <app>Postr</app> flickr uploader.</desc>
  <revision pkgversion="0.13" version="0.1" date="2009-11-13" status="incomplete"/>
  <credit type="author">
    <name>Germán Póo-Caamaño</name>
    <email>gpoo@gnome.org</email>
  </credit>
  <!--
    <copyright>
      <year>2009</year>
      <name>GNOME Documentation Project</name>
    </copyright>
  -->
  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
</info>

donde <link /> especifica hacia donde sera enlazado. Tiene el atributo guide y tambien seealso que puede ser usado asi

<info>
  <link type="guide" xref="index#getting-started"/>
  <desc>Log in on Flickr</desc>
  <revision pkgversion="0.13" version="0.1" date="2009-11-13" status="incomplete"/>
  <credit type="author">
    <name>Germán Póo-Caamaño</name>
    <email>gpoo@gnome.org</email>
  </credit>
  <!--
    <copyright>
      <year>2009</year>
      <name>GNOME Documentation Project</name>
    </copyright>
  -->
  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
</info>

Esto hara que esta pagina se referencie a getting-started (section creada en index) de index.page

<desc> </desc> descripcion del contenido de la pagina, esta descripcion aparecera como una pequena descripcion en la pagina index

todo lo demas como se describio arriba

luego de </info> viene el titulo

<title>Titulo de la pagina </title>

Luego parrafos para escribir el contenido con <p> </p> , <app> </app> para enfatizar el nombre de la aplicacion

para imagenes la forma es asi

  <figure>
    <title><app>Postr</app> window</title>
    <desc><app>Postr</app> main window</desc>
    <media type="image" src="figures/postr-main-window.png" mime="image/png" style="right">
      <p><app>Postr</app> main window.</p>
    </media>
  </figure>

donde el titulo y la descripcion tiene el mismo comportamiento anterior, tambien usa la etiqueta <gui> para refererirse a una ventana en especifico como con empathy asi:

<figure>
    <title><gui>Contact List</gui> window</title>
    <desc><app>Empathy</app> main window</desc>
    <media type="image" src="figures/empathy-main-window.png" mime="image/png" style="right">
      <p><app>Empathy</app> main window.</p>
    </media>
  </figure>

<media> </media> se usa para desplegar una ventana y dentro de ella una imagen con una descripcion dentro mediante un parrafo <p> </p>

type="image" para imagen src="ruta_de_la_imagen" para hacerlo estandar las imagenes deben estar en una carpeta con el nombre figures mime="image/png" para definir el tipo de archivo de la imagen por ahora en png style="right" por ahora es el unico estilo y es estandar

acabo de encontrar un bug en empathy docs quiero solucionarlo

se pueden usar <note style="warning"> </note> o <note style="tip"> </note> para notas de precaucion o tips