Blur are set to return in 2010 with a reunion documentary, No Distance Left to Run, directed by Dylan Southern and Will Lovelace.

The documentary is a picture of reconciling friendship and Englishness, following the band’s path from the beginning to their headline appearance at Glastonbury 2009.

No Distance Left to Run features rehearsal and performance footage from 2009, as well as archive clips from years before.  You can also expect to see interviews, backstage scenes and Damion Albarn stage dives.

Although Blur re-united during Spring 2009, their last gig this July was decided to be the last.  There are no further plans to play together again.

No Distance Left To Run is showing at cinemas in January 2010

Situation: I have a Docbook project that builds in Publican. However the same book also needs to be able to be built by a different team using Maven and jDocbook. How do I make this happen.

1 – You’ll need a Maven POM (pom.xml)

Publican 1.0 currently no longer includes POM creation. The previous generation of Publican, ie 0.45 and earlier, would produce a Maven POM (pom.xml) with the command make pom. Either generate one with a pre-1.0 version of Publican or make a copy of a pre-existing one.

2 – Add the jboss.org Maven repository configuration to the POM
The POM produced by Publican lacks the repository configuration to actually make it work.

EDIT: Apparantly this is because users were being instructed to add this configuration to their ~/.m2/settings.xml.  In my opinion this is counter to the design of Maven.  Projects should be self contained and not rely on local configuration.

The missing sections are:

<repositories>
    <repository>
        <id>repository.jboss.org</id>
        <name>JBoss Repository</name>
        <layout>default</layout>
        <url>http://repository.jboss.org/maven2/</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

<pluginRepositories>
    <pluginRepository>
        <id>repository.jboss.org</id>
        <name>JBoss Repository</name>
        <layout>default</layout>
        <url>http://repository.jboss.org/maven2/</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

These are the repositories that contain the jDocBook Maven plugins as well as the default JBoss style plugins. Just add this XML to the POM within the scope of the <project> tag, e.g. just before the <build> element.

3 – Make sure the POM matches the book.
If you didn’t use Publican to generate a new POM and are reusing a POM from another project then the <properties> section will probably not match your book and will need to be edited.

<properties>
     <translation>en-US</translation>
     <docname>A_User_Guide</docname>
     <bookname>A User Guide</bookname>
</properties>

<docname> needs to have the same value as the file name (minus the .xml) of the starting XML file of your book, i.e. the one containing the <book> or <article> element.

<bookname> is only used in the <name> element of the <project> … and nothing in this POM makes use of it, so it doesn’t really matter what you put here. I’d set this to whatever the title of the book is.

4 – Add entity declarations to the top of each of your XML files.

Publican enforces some good habits, like having all your entities declared in one file. However entities actually need to be declared in every file that they are referenced from. Publican as a part of it’s “pre-build” process inserts the declarations into each file for you. jDocBook doesn’t do this however so you need to add a reference to your entities file (A_User_Guide.ent) in the header of every XML file that uses those entities. If you don’t do this, the entities will not populate in your book.

<?xml version='1.0'?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "A_User_Guide.ent">
%BOOK_ENTITIES;
]>

EDIT: The filename of your entities file is a relative path.  This means that if the entity file is not in the same directory as the XML file that you are editing then you must supply the relative path.  In the example above, if the XML file is in a sub-directory, and the entity file is in the parent directory then you would need to specify the file as “../A_User_Guide.ent”.

Note Publican is smart enough not to duplicate this during its own build process.

4 – Specify both role and language for <programlisting>

In Publican, to make use of language syntax highlighting in <programlisting>, you specify the attribute language with the value of the language that the <programlisting> contains. This is actually the correct behavior according to the Docbook specification.

<programlisting language="xml">

However the underlying highlighting library that jDocBook uses requires that the language be specified with the attribute role.

<programlisting role="XML">

You can simply specifying both attributes so it works in both systems.

<programlisting language="xml" role="XML">

Note that Publican 0.45 requires the value to be lowercase, and jDocBook requires it to be uppercase.

EDIT: For Publican 1.0, the capitalization of the language value needs to match the LANGUAGE column at http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS.

That’s the easy stuff. Dealing with Publican’s Common Content is a little trickier. In many cases you can simply supply a Feedback.xml, Conventions.xml and Legal_Notice.xml to satisfy the fallbacks. But that isn’t really a good long term solution for a couple of reasons which I’ll deal with that another time.

Maven will build this book with the command mvn compile. The Publican supplied POM will build html, html-single and PDF versions of the book using the default JBoss documentation styles.

If you do not want to use the default JBoss documentation styles then you will need to create your own jDocBook style Maven plugin. This isn’t terribly difficult but is also a topic for another time.

The Truth About Online Anorexia outlines the issues surrounding anorexia and its “pro-ana” online community.  The ITV documentary bluntly raises the point that anorexia is rapidly becoming more than a disease.  It is almost becoming a religion – a cult by “commandments”, followed by those participating in websites online.

“Pro-ana” websites function as a place for sufferers to come together in order to “support” each other.  Participants are actually encouraged to post their own blogs, sharing knowledge of their thoughts and their very own extreme dieting tips.  And the reward? To become more like their own ‘thinspirations’.  In fact, Fearne Cotton, the presenter of the documentary, was shocked to find herself as an actual member of a ‘thinspiration’ list among many other famous women.

It seems that we have reached an age where we are so dependent on technology that we can even rely on it to practically promote diseases such as eating disorders.  All a person really has to do is type in Google “pro-anorexia” and the result is swarms of links which share exactly that view. People who were once sufferers almost become competitors in this web-based environment.  The “pro-ana” community is driven by comparison and jealousy that is portrayed as anything but harmful.  But, by criticism, we are only strengthening the “pro-ana” cause.  Online communities continue to strive on values that are deeply threaded into society, regardless of individual opinions.

But with the recent size zero debate and constant displays of ‘beautiful people’; is the uprising of the “pro-ana” revolution really that shocking? The anorexic figure shown online is no longer ugly, but an example of pure beauty.  It seems that as members of the youth generation in the 21^st century, we are slowly becoming desensitized to images of thin men and women.  The more we look at them, the more we expect them to be thin. The more we look at them, the more we expect them to be beautiful.  People are not people, but spectacles.

After hearing “ordinary 10 year old children” in this documentary discussing “big thighs” and sharing their knowledge of 109 calorie Kit-Kats, it is clear that eating disorders are emerging in our youth more than ever.   With one girl in particular claiming that she had learnt how to diet through “magazines and websites”, it is obvious that the media is having some sort of impact on the core values of people today.  And as a result of sites such as those that welcome “pro-ana” communities, the concept of individuality is becoming fragile and becoming a ‘thinspiration’ is perceived as a key to happiness and success.

By Natasha Devan

If you suffer from an eating disorder or if you would like any more information, please make use of the following websites or telephone numbers:

www.b-eat.co.uk 0845 634 1414

www.edauk.com

www.nhs.uk/conditions/Eating-disorders

Bé, d’entrada podria semblar que el comentari de l’arnau se’n va fora del nostre debat. En el seu dia vam fer la nostra reunió per escollir entre DocBook o DTBook, I ara ens parlem d’una nova opció, DITA.

Doncs, tot i que d’entrada el més fàcil seria no fer cas del comentari i tirar pel dret, crec que realment val la pena fer un cop d’ull a DITA. Perquè? Doncs bé, crec que no hem de caure en el parany de voler canviar de format sense canviar els materials de la UOC. Tots sabem que els nostres materials han de canviar. DITA és una oportunitat per al canvi.

Dit en poques paraules (i més val que llegiu els articles que cito més endavant per tenir la vostra pròpia opinió), DocBook està més pensat per fer el llibre de tota la vida, mentre DITA agrupa mòduls d’informació.

Ja sabeu que sóc un gran defensor dels mòduls com a unitats de contingut. Doncs bé, deixem de fer llibres! Al cap i a la fi, no som una editorial. Oblidem-nos de portades, de contraportades, de cobertes… Agrupem la informació en mòduls de contingut, i els enllacem de la manera més convenient.

És clar que aquesta és una discussió que probablement sobrepassa aquest projecte, però aquesta és una barrera que més tard o aviat haurem de trencar, i penso que si presentem un bon projecte podem intentar vendre’l.

En tot cas, DITA segurament ens permetrà fer una estructura similar a la que fem ara, però també ens permetria en un futur anar a una estructura modular, mentre que DocBook sembla que ens lliga més a quedar-nos com estem.

Sigui com sigui, cal mirar-s’ho amb calma abans de prendre una decisió en aquest sentit. Us convido a llegir els articles que cito a sota i a valorar-los (no gaire més de mitja hora de lectura).

LA DOCUMENTACIÓ SOBRE EL TEMA

Aquests posts tracten precisament sobre com decidir entre DocBook i DITA. El segon és una resposta al primer:

• Choosing an XML Schema: DocBook or DITA?
• Resposta al post anterior.

També tenim les entrades a la wikipedia que tracten sobre tots dos esquemes:

• DocBook
• DITA

I les comunitats de suport, amb gran quantitat de documentació:

• DocBook
• DITA

Hace algún tiempo comenzamos con el desarrollo de un proyecto utilizando tecnología OpenCms, como fruto de este trabajo hemos liberado cinco nuevos módulos que esperamos sea de utilidad para la comunidad (los módulos están modelados con maven y documentados con docbook):

RestrictedVFSWidget

Este módulo es una evolución del wdiget de exploración de OpenCms, con él se modelará el comportamiento de un árbol de exploración del directorio virtual de OpenCms en el que tan sólo se mostrarán los directorios y aquellos tipos de contenidos que se hayan configurado en la declaración del tipo de contenido que lo use.

SurveyModule

Con este módulo se amplía el funcionamiento del módulo Alkacon OAMP Survey Module, de manera que se ofrece la posibilidad de generar las gráficas de los informes en flash mediante Open Flash Chart.

Modulo Alfresco

El objetivo de este módulo es proporcionarle a los usuarios de OpenCms una herramienta con la que asignar recursos de un gestor documental Alfresco para ser utilizados en el portal. De esta forma se consigue separar la capa de gestión de contenidos de la capa de gestión documental, pudiendo aprovechar todas las funcionalidades que un gestor documental como Alfresco proporciona.

Georeference

Este módulo permite llevar a cabo la geolocalización de puntos a través de Google Maps, estableciendo las localizaciones directamente sobre un mapa que se muestra en el formulario de alta/edición de contenidos de OpenCms.

Thesaurus

El objetivo de este módulo es proporcionarle a los usuarios de OpenCms una herramienta con la que etiquetar los contenidos (noticias, eventos, etc) que se utilicen en el portal.

El software es como el sexo, es mejor cuando es libre. Linus Torvalds

Estos días ando enfrascado con el anteproyecto de mi PFC, pues quiero entregarlo antes de finalizar el mes. Dado que ya tengo todo el trabajo técnico terminado, la idea es escribir durante el verano la memoria, para entregar los tomos y leerlo a la vuelta de vacaciones.

Llegados a este punto, me enfrento a la decisión de cómo desarrollar la memoria del proyecto. Utilizar Word queda descartado por defecto, como si su nombre representara para mí una tautología negativa. En primer lugar, porque no utilizo Windows, y necesitaría liarme la manta a la cabeza con las máquinas virtuales, lo cual no me apetece en absoluto. Y en segundo lugar, he podido comprobar en pellejo ajeno los problemas que puede ocasionar. Cuando las barbas de tu vecino veas cortar…

OpenOffice.org, por más que me guste, y aunque lo utilice habitualmente, incluso de forma “profesional” (los artículos de @rroba los desarrollo en OOo); creo que tampoco es una opción muy adecuada para documentos de esa magnitud.

Mi idea, desde que Abián y Jaime lo utilizaran en su proyecto, era usar DocBook para desarrollar la memoria del mío. Pero al final, uno de mis jefes (que es también mi director de proyecto) me ha convencido para pasar directamente al modo hardcore y hacerlo en LaTeX. Partiendo de una plantilla para la realización de este tipo de documentos, la verdad es que no parece tan complejo como en un principio creía que sería.

La semana pasada comencé a trastear un poco con el entorno de TeX en Linux, usando Kile para ello. Como no quiero tener que estar desarrollando la documentación en distintos ordenadores, y dado que están acercándose las vacaciones, y los habituales “saltos cuánticos de localización” asociados a ellas; finalmente he optado por desarrollar todo el trabajo en el portátil.

Así pues, ayer me puse a buscar información sobre el desarrollo de LaTeX en Mac OS X, y finalmente terminé instalando MacTeX 2008 como distribución de TeX (¡más de 1 Gb de descarga!), y TeXShop como editor. No tiene las chorraditas WYSIWYG de Kile, pero la generación automática de documentos en PDF es tan sencilla como pulsar un botón. Los resultados, desde luego, son impresionantes: meter el zoom a tope con Vista Previa y ver la suavidad de las fuentes es una auténtica gozada.

No sé si más adelante me arrepentiré y defecaré en todo el Panteón, pero de momento estoy bastante contento con lo poco que he probado. Además, si me habitúo al sistema, creo que los papers a partir de ahora podrán decir adiós al Word…

I had to learn a little about a software tool named DocBook.  I was reading DocBook 5.0: The Definitive Guide, by Norman Walsh, when I came across an example that used this quote:

The universe that we observe has precisely the properties we should expect if there is, at bottom, no design, no purpose, no evil and no good, nothing but pitiless indifference.

–Richard Dawkins

The irony was striking.  This book is available, for free, on-line.  Presumably then, Norman Walsh is a caring, generous fellow who is willing to make his work freely available to others.  That raises an obvious question: how is it that in this indifferent universe, a caring, concerned, generous benefactor such as Norman Walsh exists?  That is to say, how does an indifferent universe give rise to beings who are not at all indifferent?  Similarly, consider Dawkins himself.   He strenuously promotes atheism.  Doesn’t he believe it is true?  Doesn’t he desire for everyone to see it’s truth?  Doesn’t he care about the state of his fellow man?  I expect he does all of these things, and is therefore also hardly indifferent, nor lacking some sense of the difference between good and evil.

I can only conclude Dawkins is quite wrong.   From a universe that is indifferent and void of good or evil, we would expect to find only indifference, and no sense of right or wrong.  Yet, we find quite the opposite, even in those who claim we live in a Universe of pitiless indifference.

Finalment, hem escollit DocBook com a candidat per substituïr el nostre entranyable sistema de marques. Tots hi hem estat d’acord. Entre els motius que ens han portat a pendre aquesta decisió, cal destacar el fet que el conjunt d’etiquete de DocBook és molt complert, que és molt conegut en el món editorial i que tè una comunitat activa i nombrosa al darrera. El punt a favor de DTBook és el suport de la indústria, un suport que també tè DocBook.

Ara hem d’analitzar amb detall si és possible adaptar els nostres continguts a DocBook i què fem amb les incompatibilitats que apareguin – que n’hi haurà. Encabat haurem d’escriure un full de ruta per a l”adaptació del procès editorial al nou marcatge. I sol serà aleshores que prenguem la decisió final.

Com segurament coneixeu, els estudiants de la UOC reben tots els materials didàctics que necessiten a casa abans de l’inici de les classes. Tots aquests materials pertanyen a la Universitat i han estat elaborats per la nostra editorial. Sumant totes les assignatures, disposem de més de 2000 obres: un volum important.

En  un principi aquests materials eren llibres. Desrpès van aparèixer algunes webs que es distribuïen en CD. Ens vàrem adonar que els estudiants que rebien els CDs reclamaven els materials en format paper, principalment per llegir a casa, i els que rebien els llibres volien la web per a eralitzar consultes puntuals.

Així doncs ens vam decidir per incloure la tecnologia XML al nostre procès editorial, cosa que ens permetia generar sortides pdf i web automàticament. El canvi va ser tot un encert. Actualment la meitat dels nostres continguts estan en format XML i gràcies a això els podem lliurar en sis formats diferents sense que això ens suposi un cost extra: pdf, web, mobipocket, epub, audio sintètic i uns “videollibres” que anomem “karaoke”. El nom que fem servir per a agrupar tots aquests desenvolupament és MyWay: donem el contingut en diferents formats i els estudiants fan servir el que volen segons les seves necesstats concretes.

Com sempre, varem començar a marcar en XML amb més ganes que coneixement. Vam utilitzar els nostres pròpis tags sense tenir en compte que en el mercat ja existien sistemes com DTBook i DocBook. Un exemple: el que per a nostres és un “mòdul”, per a DTBook és un “level” i per a DocBook és un “chapter”.

Tenir un sistema de marques estàndard no és imprescindible, però ajuda a compartir els desenvolupaments amb altres institucions i a aprofitar programes ja existents. I és precissament això el que volem. Així doncs, ens hem decidit a adoptar algun dels sistemes de marques ja existents. Ara el dubte és saber quin.

Els dos sistemes que coneixem son DocBook i DTBook. Encara no ens hem decantat per cap d’ells. Tot just estem analitzant els pros i els contres de cada un d’ells. Us deixo aquí les notes que hem anat prenent per si és del vostre interès:

DTBook

• Hi ha plug-ins de “save as…” per a word (+1)
• Hi ha plug-ins de “sace as…” per a openoffice (+1)
• Compatible amb ePub (+1)
• Compatible amb Daisy (+1)
• 80% dels nostres tags (-1)
• Es pot incloure MathML (+1)
• Al formar part de l’especificació DAISY, reb el suport d’institucions que vetllen per l’accessibilitat dels continguts (+1)

Stamani, durante una riunione, la mia collega propone di cominciare a scrivere la documentazione del nuovo progetto in docbook. Questo è un formato xml molto utilizzato per la produzione di documentazione, perché ha l’immenso vantaggio di poter essere convertito molto facilmente nei vari formati (pdf, doc ecc) ed essere comunque un file di testo, cosa che permette di condividerlo attraverso un server di Concurrent Versioning System.

Di tre persone presenti alla riunione, soltanto questa collega lo aveva già usato, io allora mi son chiesto se potevano esistere strumenti semplici per salvare in questo formato.

Sapendo che OpenOffice.org riesce a salvare in moltissimi formati e considerando che ODF stesso è un file xml, ho provato a vedere se c’era qualche riferimento. Infatti tentando di salvare un documento di Writer è possibile scegliere il docbook

La questione, a questo punto, diventa semplicissima, perché con un editor così potente sarà facilissimo esportare in docbook e poi produrre la documentazione necessaria.

E’ comunque sempre possibile usare altri editor testuali, come l’ottimo Notepad++, o qualsiasi editor per xml.

What is DocBook?

DocBook is a schema (available in several languages including RELAX NG, SGML and XML DTDs, and W3C XML Schema) maintained by the DocBook Technical Committee of OASIS. It is particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

Because it is a large and robust schema, and because its main structures correspond to the general notion of what constitutes a “book,” DocBook has been adopted by a large and growing community of authors writing books of all kinds. DocBook is supported “out of the box” by a number of commercial tools, and there is rapidly expanding support for it in a number of free software environments. These features have combined to make DocBook a generally easy to understand, widely useful, and very popular schema. Dozens of organizations are using DocBook for millions of pages of documentation, in various print and online formats, worldwide.

View more

I was sad to get the news this morning of the demise of the DocTrain conferences. I’ve been to DocTrain West twice and was privileged to be able to present at this year’s conference. And, I was getting prepared to present two sessions at DocTrain/DITA, both on DocBook. Scott Abel, who was contracted by PUBSNET to market and run DocTrain, agreed with me that some sessions on DocBook would be a nice counterpoint to the incessant DITA drumbeat. I was especially looking forward to some spirited give and take on DITA and DocBook.

Scott’s involvement is the thing that distinguished DocTrain in my mind. He is an indefatigable organizer who kept the programs lively and attracted a broad base of presenters and attendees. Whenever someone posted the inevitable, perennial question, “which conference should I go to,” on a mailing list or news group, the inevitable, perennial reply was “go to DocTrain if you want substance and interaction.”

That was in no small part due to Scott. While the demise of DocTrain is bad news, the good news is that Scott is continuing to look for ways to connect people (Scott is a connector in the best Malcolm Gladwell sense; Gladwell detractors be damned, I think he’s spot on about connectors). You can be sure there will be new events, virtual and in-person, and I plan to be there.

K15t Software have just announced release 1.0 of Scroll, a Confluence plugin that converts wiki documentation to DocBook and PDF. I’ve been interested in this project since the early beta days and I’m excited for the K15t guys about the functionality Scroll offers already and about their plans for even more awesome developments.

First things first: You’re probably wondering why they’re called “K15t Software” It’s because one of the developers and company founders is Stefan Kleineikenscheidt. I guess that most people, like me, go cross-eyed upon encountering his surname. So he uses “K15t”, in the proud tradition of “i18n” and other such abbreviations. Another K15t Software developer is Tobias Anstett, fondly known as “t11t”. During Scroll’s beta period we’ve had some good conversations via Twitter, blogs, video conferencing and email.

History in the making

The guys founded K15t Software as a company just a few weeks ago. If you’re a technical writer, you’ll like their mission statement:

“K15t Software is a small development shop from Stuttgart, Germany. Its mission is to build useful software products with the focus on tools for wiki-based documentation.”

It all started five years ago, when Stefan lodged a request for a DocBook export from Confluence wiki. The request is on the Atlassian JIRA site — CONF-762. A DocBook exporter is not on the roadmap for core Confluence, so Stefan and the team decided to build one as a plugin. And the rest is history! Well, it’s the future too, because K15t plan to keep adding features to Scroll.

How does Scroll work?

It’s a plugin (add-on) to Confluence. If you have administrator permissions on your Confluence site, you can install the plugin as described in the Scroll Installation Guide.

Once it’s installed, the “Scroll Wiki Exporter” option will appear in your Confluence menu. Here’s a screenshot of the option in Confluence 2.10. I’m on a wiki page called the “Crowd User Guide” and have opened the “Tools” menu on the right:

Scroll converts wiki to DocBook and PDF

When you choose the “Scroll Wiki Exporter” option, you get a screen with some tabs where you can choose either PDF or DocBook output and set some formatting options. On the “Document Information” tab you can set the document title, author and version. Scroll will provide default values based on the wiki page, but you can change them:

Scroll converts wiki to DocBook and PDF

The “Page Tree” tab shows you a hierarchical view of the pages you are about to export. The top level of the tree is always the page you were on when you clicked the “Scroll Wiki Exporter” option. The export will include that page plus all its sub-pages and their sub-pages etc. At the moment, “Page Tree” tab is view only. Scroll may allow re-ordering in a future release.

Next is the “Formatting” tab. Here’s where you choose either PDF or DocBook. If you choose PDF, you can select a theme, language, etc. Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation.

Scroll converts wiki to DocBook and PDF

The Scroll documentation tells you more about the formatting options.

On the “Advanced” tab, you can tell Scroll what to do if it encounters some wiki markup or macros that it doesn’t recognise.

Scroll exports wiki to DocBook and PDF

When you’re ready, you kick off the export. Scroll will show its progress and then present you with a file for downloading.

Scroll exports wiki to DocBook and PDF

If you chose to export as PDF, the output will be a PDF file. If you chose DocBook, it will be a zip file containing the DocBook 5 XML and all images and other attachments.

Some comments from me

I’ve really enjoyed my contact with Tobias and K15t. They’re passionate about their software, passionate about Confluence wiki, and keen to hear feedback. Here are some useful titbits from my experimenting with Scroll:

• Note the {scroll-ignore} macro. You can put it onto your wiki page to tell Scroll not to export a particular chunk of text/content.
• Scroll supports a number of wiki markup elements and macros. The Scroll Authoring Guide tells you how to write your text for best Scroll results.
• Scroll exports DocBook version 5.0.
• The “Scroll Quick Help” tips on the right of the export screens (see above) are useful and concise.
• It’s really useful to be able to determine error handling, telling Scroll what to do when it encounters some wiki markup or a macro that it doesn’t know what to do with. See the “Advanced” tab described above.
• In the PDF export, the “Simple Documentation” theme is neat and attractive.
• For PDF, Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation. They’re also planning to allow pluggable themes, so that developers can create their own themes for Scroll.
• I’ve suggested an addition to the Scroll documentation, to provide more information about the DocBook XML produced. The Scroll team have added this to their “to do” list.
• The section on nesting of headings in the Scroll documentation explains why your heading levels may sometimes be different to what you expect.

Some comments from Giles

Giles Gaskell is a technical writer and colleague at Atlassian. He’s had extensive experience with DocBook, so he’s very interested in the Scroll plugin for Confluence too and I’ve been delighted to have his help with the plugin analysis. Here are Giles’s comments:

• I really like the XML indenting that Scroll generates. It makes the XML output very readable via a standard text editor. I’ve worked with several XML editors in the past that force you to use their products to read/edit your XML content, since they either implement their own strange XML indenting or remove all white space > 1 character in length, in their XML output files.
• It’s great that the version of DocBook XML exported by Scroll is 5.0. There are several processing advantages in DocBook XML 5.0 (via the RELAX NG schema) over what’s available in previous versions of DocBook XML (which are based on DTD schema only). Furthermore, it seems that RELAX NG is the way DocBook XML processing is headed.
• I validated both DocBook XML exports using my own installation of jEdit and both were without any errors
• Scroll does not add a document type declaration at the top of the XML output. It seems that DocBook XML 5.0 files which make use of RELAX NG-based processors typically do not possess a document type declaration. Likewise, it seems that DocBook XML 5.0 output without a document type declaration can only be processed by tools which are RELAX NG-compliant. Hence, it might be useful to have an option in the Scroll Wiki Exporter to add a document type declaration to the XML output, so that XML processing tools which verify XML against DTDs only can process these exports. [Giles would be very interested to hear any comments on this point from other DocBook users.]
• It might also be worth providing an option to choose the version of DocBook XML exported — 4.0, 4.5 or 5.0. However, k15t might consider conducting a brief feasibility study on this first as I suspect integrating this feature would require a fair bit of work and some understanding about the differences between each version of DocBook. The main area of demand for this feature would be customers who have an existing/legacy tool setup that manipulates DocBook XML 4.x content, but do not have resources to upgrade their entire system to DocBook XML 5.0. DocBook XML 5.0 was only officially released in January 2008, so I suspect many DocBook XML customers would still be using DocBook XML 4.x.
• Regarding the use of the <article> root element as opposed to <book> in the DocBook XML output: I believe this is an advantage, as it gives the author more flexibility to structure their books. The <book> element encapsulates information about a book’s content at a higher level than what is contained within an <article>. For example, an author may want to export multiple DocBook <article>s from a Confluence installation. These might be sourced from a variety of Confluence spaces or subtrees. They might then wish to combine these exported DocBook XML <article>s into a single DocBook <book>, using their own DocBook XML editor. If Scroll exported to a DocBook <book>, this would not be possible without additional XML processing.

Giles is also discussing a couple of minor points about the DocBook XML, such as the fact that each <link> element defines its own xlink namespace, and the production of the <?linebreak?> processing instructions.

Try it out yourself

You can either download the plugin for evaluation from the K15t Software site and try it on your own Confluence wiki, or you can use their demo Confluence site to see the pages already there, create your own pages, and then export them to DocBook or PDF. Awesome!

That’s all folks

Both Giles and I enjoy working with the K15t Software guys. They’re very quick to respond to feedback and I’m sure they’d be delighted for more input from other technical writers.

I’ll be headed to Indianapolis for the DocTrain/DITA conference (June 2-5) to talk about DocBook, of all things. More on that in a moment, but first a quick plug for the conference itself.

If you have been to any of the DocTrain conferences, you know they combine in depth pre- and post-conference workshops with excellent keynotes, demonstrations, and talks. I like the flexible format; talks and workshops range from an hour to all day, depending on the topic, so you can get a taste or full immersion in the topics of your choice. This one is devoted 95% to DITA (my DocBook presentations are the only exceptions I’m aware of).

Until April 30th, the organizers are offering a great hotel+conference offer that includes the full conference, workshops, several meals, and three nights hotel for $999. Details here, or call Eileen Savary at +1 978-649-8555 and use discount code “Conference Plus Hotel.”

I’ll be doing two sessions, the first titled: DocBook in the 21st Century: Yes, Virginia, There is a DocBook, and it is Alive and Well, which has the following blurb in the program:

The latest release of DocBook, V5.0, is a significant break with earlier releases. While the differences between DocBook V4.x and V5.0 are quite radical in some aspects, the basic ideas behind DocBook remain the same, so moving from earlier versions to V5.0 is straightforward.

DocBook V5.0 includes new markup for annotations, a unified markup for information sections, and a new and flexible system for linking. In addition, V5.0 is more extensible; it can be more easily modified, and it can be extended in separate namespaces to allow you to easily mix DocBook markup with SVG, MathML, XHTML, and other XML-based languages.

This talk will start with a quick orientation to DocBook for those who have not seen it before, then look in depth at V5.0.

I’ll also be doing a workshop titled Getting Started with DocBook, which is designed to do just that. Here is the blurb:

This workshop will get you up and running with DocBook. If you bring your laptop with you, by the end of the session you should be able to create and publish a DocBook document in html and pdf output formats. The workshop will include basic information about the DocBook schema, DocBook stylesheets, supporting software, and how to put it all together.

If you’ve wondered what DocBook is all about, if you are evaluating it alongside other schemas, or if you want to use DocBook for a new project, this workshop will get you started.

I’ll be interested to see how much, if any, interest there is in DocBook at a DITA conference. I’m cautiously optimistic that there will be enough curious folks to fill the room; we’ll see.

In one last moment of shameless promotion, there will be copies of Managing Writers for sale at the conference.

click on three links bellow then click around:
bash
secure programming
Docbook

if you did click around, you would have probably noticed something; all the documents are presented in a consistent way even though they where written by deferent people, living in deferent places.
if you were adventurous, and went up a few directories you might have noticed that each document had a pdf version, and that each pdf of the three was organized in the same way as the other.
can it be that each writer thinks in the exact same way? i think not.. at least i hope not.
the tool behind producing these online/offline documents is ether Docbook or LaTex. this article discusses Docbook, an schema (XML or SGML) developed to facilitate documenting software or hardware. However, it is not limited to these two fields. in fact, it can be used to document anything.
Docbook focuses on content structure rather then appearance. this – in my opinion – is what makes Docbook so great. instead of using open office and constantly indenting, changing fonts, spacing paragraphs, and so on, i can focus on what is more important: what i’m actually writing!
the following docbook code:

<book>
<bookinfo>
<title>My software is the COOLEST</title>
<authorgroup>
<author>
<firstname>Sulaiman</firstname>
<othername>A.</othername>
<surname>Mustafa</surname>
</author>
</authorgroup>
</bookinfo>
<chapter id="Introduction">
<title>Introduction: Installing and Starting</title>
<para>
This program is written in python and requires a python iterpitor along
with the standared module library to run. the version used is 2.6.1, and
other versions might not be compatable. to istall simply copy the archive to the desired directory. to start the program, you have two
options; first, you can start the script directly by issuing the following command:
(while in the same directory)
<example>
<title> Starting the program </title>
<programlisting>
./ConfParse.py
</programlisting>
</example>
of course youm may also start it by suppling it as an agument to a pthon interptor.
<warning><para>This software was written with python 2.6.1, using ether older versions or newer ones might <emphasis>break</emphasis> the program!</para></warning>
</para>
</chapter>
</book>


should give:

note that docbook can save in many deferent styles and formats. for more information, you may want to look at this.

SIGTERMer

Txt2tags yang lebih dikenal sebagai “document generator” adalah sebuah tools yang mampu melakukan konversi sebuah file text ke berbagai format seperti HTML, XHTML, SGML, LaTeX, Lout, Man Page, Wikipedia, DokuWiki, MoinMoin, MagicPoint, PageMaker, Plain text dengan hanya “satu kali klik”. Bayangkan, kita tidak perlu repot mengetahui bahasa-bahasa aneh (tag) untuk setiap jensi dokumen diatas untuk membuat sebuah dokumen. Extremnya, kita cukup memiliki sebuah file text dan kita bisa menggenerate dan mempublishnya ke dalam format lain tanpa perlu tahu apa-apa, enak bukan . Lebih detailnya tentang fitur yang dimiliki oleh txt2tags silahkan baca di alamat berikut http://txt2tags.sourceforge.net/features.html

Langsung saja kita coba deh (versi windows):

• Untuk pengguna Linux download txt2tags di sini, atau bagi anda pengguna Windows silahkan download di sini.
• Installasikan seperti biasa
• Kemudian kita buat sebuah file text dan berinama “contoh-konversi-txt2tags.txt”, mudahnya anda ketik contoh file text berikut:

Minimalist tools for Writers (txt2tags)
Cecep Khaerudin
Tangerang, %%mtime(%d/%m/%Y)
% IT Dept. SMKN 1 Panongan Tangerang Banten Indonesia
% Kampus SMKN 1 Panongan
% Jl. Ds. Peusar Perum Mekar Asri Citra Raya Kecamatan Panongan 15710
% Kabupaten Tangerang Banten Indonesia Telp. 0215963277

=Tentang txt2tags=

Txt2tags adalah sebuah tool konversi yang ditulis dgn bahasa //Pyton// yang mampu meng-generate sebuah
dokumen HTML, XHTML, SGML, LaTex, Man Page, MoinMoin, Magic Point dan PageMaker dari hanya sebuah file text
dengan cepat.

=Download txt2tags for windows=

- Pilih versi yang kita perlukan, apakah Compact Version dimana diperuntukkan bagi komputer yang
sudah terinstall Python atau Full Version bagi komputer yang belum terinstall Phyton
- Download
- Install
- Jalankan program
- Selesai

=Mencoba txt2tags=
+ buat tulisan seperti contoh ini (download file [%%infile %%infile] berikut)
+ simpan file tersebut dan beri nama "contoh-konversi-txt2tags.txt"
+ buka aplikasi, Start -->All Programs --> txt2tags -- txt2tags

[images/txt2tags.jpg]

+ pilih target konversi, misal HTML
+ klik tombol "Convert"
+ buka hasilnya dengan menggunakan browser
+ selesai

--------------------
=Contoh=
==Beautifier==

Huruf cetak **TEBAL** didapat dengan mengapit huruf dengan dua tanda bintang (*).

Huruf cetak //miring/italic// didapat dengan mengapit huruf dengan dua tanda slash (/)

Berlaku juga huruf **//Cetak Tebal dan Miring//** dengan mengapit dua tanda bintang dan hash (*/huruf/*)

Huruf __bergaris-bawah__ didapat dengan mengapit huruf dengan dua tanda low dash (_)

==Pre-formated Text==
Huruf untuk coding atau preformated text
```
   Ini contoh preformated text yang biasa digunakan untuk coding
   bentuk **cetak tebal** maupun //cetak miring//
   tidak akan di ``interpretasikan``
```

Bisa digunakan untuk satu baris tersendiri seperti:
``` prompt$ ls /etc/apt/sources.list

ataupun dalam satu kalimat yang sama seperti ``prompt$ ls /etc/apt/sources.list``

Contoh lain:

```
   C:\Documents and Settings\user>route print
   ===========================================================================
   Interface List
   0x1 ........................... MS TCP Loopback interface
   0x2 ...00 90 f5 8c d7 80 ...... SiS191 Ethernet Controller - Packet Scheduler
   Miniport
   ===========================================================================
   ===========================================================================
   Active Routes:
   Network Destination        Netmask          Gateway       Interface  Metric
           127.0.0.0        255.0.0.0        127.0.0.1       127.0.0.1       1
     255.255.255.255  255.255.255.255  255.255.255.255               2       1
   ===========================================================================
   Persistent Routes:
   None
```

Terlihat bedanya bukan ?, Cukup apit kalimat yang dimaksud dengan dua tanda berikut (``)

==List==
Untuk mebuat sebuah list cukup awali kalimat dengan tanda **plus** (+) maupun **dash** (-)

===Plain List===
Tanda dash (-) adalah tanda default yang digunakan untuk membuat list, cukup berikan tanda spasi bagi list
dibawahnya, contoh:

- dunia
  - asia
    - indonesia
      - banten
        - tangerang
	- serang
      - jakarta
        - jakarta utara
	- jakarta barat
- mars
  - entahlah ?

===Numbered List===
Sama seperti plain list, bedakan dengan menggunakan tanda plus (+)

+ satu
+ dua
+ tiga
  - campuran
  - list berbeda
    + hitung lagi
    + ...
+ empat

===Definition List===
Definition list di awali dengan memberikan tanda titik dua (:). definisi diletakkan di baris berikutnya
dengan meberikan spasi, contoh

: jeruk
  buah berwarna orange
: aple
  buah berwarna hijau
: durian
  buah berduri
: buah lainnya:
 + nagka
 + cempedak
   - jambu
   - melon

==Tabel==
Gunakan tanda | untuk menghasilkan sebuah tabel. Dua tanda || di awal cell adalah heading. contoh:

|| heading 1 | heading 2 | heading 3 |
 | cel 1.1   | cel 1.2   | cel 1.3 |
 | cel 2.1   | cel 2.2   | cel 2.3 |

Tanpa tanda | di akhir cell berarti tanpa border

|| heading 1 | heading 2 | heading 3
 | cel 1.1   | cel 1.2   | cel 1.3
 | cel 2.1   | cel 2.2   | cel 2.3 

==Gambar==
Cukup simpan gambar di folder yang sama dengan file text, dan sisipkan dengan tag berikut:
``[gambar/photo.jpg]`` tanpa spasi apapun.

==Tanggal==
Makro ``%%date`` akan menunjukkan ``current date``

Contoh, waktu saat ini adalah %%date dalam bentuk format ISO ``YYYYMMDD``

Bisa lebih spesifik dalam format berikut ``%%date(%d/%m/%Y)`` contoh %%date(%d/%m/%Y)

== Cosmetics  ==
Spesial entitas seperti alamat email (papi.nazwa@gmail.com)
dan alamat URL (http://papinazwa.wordpress.com) akan di deteksi secara automagically
selama masih dalam satu baris.

--------------------
^ gari tipis atapun garis tebal v (minimal 20 karakter)
====================

=Hasil Konversi=
Hasil konversi dari file Text di atas ke bentuk HTML terlihat seperti berikut:

[images/txt2tags-convert-html.jpg]

Semoga membantu.
--------------------
(Note: Download file [%%infile %%infile])

• Buka aplikasi txt2tags; Start –> All Programs –> txt2tags –> txt2tags
• Pilih target konversi, dalam contoh ini target konversi adalah HTML
• Klik tombol “Convert”
• Buka file “contoh-konversi-txt2tags.html” hasil konversi tersebut dengan menggunakan web browser

  

• Selesai

Dan silahkan konversi file/tulisan/artikel/buku anda ke dalam format yang lain.

Dan bagi  anda yang tidak sabar, coba download di sini.
Semoga membantu !

A WWW daria uma lousa e tanto… se a gente conseguisse rabiscar uma equação

A WWW foi concebida no CERN e, desde então, o patamar em que chegamos atualmente (chamado de Web 2.0) é bem diferente daquilo que se imaginava na época da criação da Web. Hoje em dia já se fala em Web 3.0, que é uma espécie de codinome para Cloud Computing. Porém, o sonho original para a WWW é a chamada Semantic Web. Eis o próprio T.B. Lee falando sobre esse assunto,

De fato, a tal “Web 3.0″ deve incluir toda essa parte “semântica” (veja mais em W3C Semantic Web Activity, The Semantic Web e The Semantic Web Revisited (PDF)), chamada tecnicamente de Metadata — apesar de que a incorporação de todos esses “metadados” em bancos-de-dados e aplicações (“cloud”) afins ainda vai levar algum tempo.

De qualquer maneira… essa “simples” idéia — de assimilar os “metadados” de forma fundamental e intrínseca nas entranhas da Web — tem um enorme potencial quando o assunto é Publicação Científica. Um exemplo claro disso é o Scientific Publishing Task Force: Mindswap: Science and the Semantic Web, Science and the Semantic Web (PDF), Semantic web in science: how to build it, how to use it, ScienceOnline09: The Semantic Web in Science.

Então, como se pode ver com clareza, essa idéia de se associar “semântica” aos elementos já pertencentes da WWW, realmente será algo revolucionário.

A razão pra essa longa introdução é o paradigma adotado pelo MathML, que é a linguagem que permitirá a introdução de linguagem Matemática na WWW. Existem dois modos de se “descrever” uma informação em MathML, Presentation MathML e Content MathML — enquanto o pMathML foca na apresentação e aparência das equações e elementos matemáticos, o cMathML foca no significado semântico das expressões (num esquema bem parecido com Cálculo λ ).

Então, fica claro que o objetivo de MathML não é apenas o de “apresentar” uma informação, mas também de dar significado semântico a ela, o que fará com que a comunicação matemática seja muito superior do que a comunicação atual, feita em HTML!

O paradigma atual:

Hoje em dia, efetivamente, quem tem necessidade de publicar muitas equações usa , mais especificamente, usa-se — esse é o de facto padrão.

Essa linguagem é extremamente poderosa, versátil e flexível, podendo ser extendida de várias maneiras diferentes. E isso facilita muito sua aplicação em várias áreas diferentes: desde símbolos matemáticos, gráficos vetoriais, …, até símbolos musicais, de xadrez e tipografia em línguas gráficas, como árabe, hindu, chinês e afins!

Por essas e por outras, atualmente é muito mais comum de se encontrar programas que convertem de para MathML do que programas que nativamente facilitam a edição nativa [em MathML]. Tanto que existe um livro unicamente dedicado a esse assunto: The LaTex Web Companion. Aliás, nessa linha, eu recomendo o uso do formato DocBook, cuja saída pode ser HTML, PDF, (via o uso de XSLT), etc.

Portanto, o que acabou acontecendo é que quando alguém precisa publicar fórmulas e afins, ou se cria um documento em PDF, ou se usa de “algum desvio” para colocar a informação na Rede — em geral, esse desvio consiste em se converter o conteúdo desejado em alguma imagem, e inserí-la no HTML em questão.

A saída: habilitar os navegadores

A alternativa pra tornar tudo isso integrado (Web 3.0, MathML, etc) e unificado é prepararmos os navegadores para essa nova jornada, nova etapa, da WWW. Por exemplo, o Firefox tem toda uma infra-estrutura dedicada para MathML: MathML in Mozilla. Porém, pra isso, é preciso que os desenvolvedores de navegadores sigam os padrões já definidos para MathML. Essa é uma lista dos navegadores que suportam MathML. Além disso, pra quem usa Firefox, esse é um ‘add-on’ bem interessante, Firemath (eu não tenho uma conta com o Mozilla, então, se alguém que tiver uma conta quiser me mandar o add-on, eu agradeço ).

Portanto, o caminho ainda se encontra aberto… e as possibilidades são infinitas!

Referências…

• Writing Math on the Web
• What Is New in Latex? (PDF), The TeX Family in 2009 (PDF), comp.text.tex
• DockBook (Wikipedia), DocBook, DocBook (SourceForge)
• DocBook to LaTeX XSL stylesheets
• LaTeX, XSLT to XHTML+MathML, XSLT from XHTML+MathML to LaTeX, XSLT MathML Library
• MathML (Wikipedia), MathML, MathML in Mozilla, Wolfram’s MathML Central
• XHTML+MathML+SVG (Wikipedia), An XHTML + MathML + SVG Profile

The LDP new activity seems to become better known, we have several old authors coming back, this is very pleasant.

So I could convert some HOWTOs to the wiki to ease the proofreading process.

Convert any document to MoinMoin wiki is not that easy. There is only one good script (html2wiki) and it needs html source.

LDP always had problem with html. When one write for the Web, html seems an obvious choice. However html allows virtually anything – and when one do anything it’s mostly bad .

LDP strenght is to ask for structured documentation. A good doc have to include table of content, revision history, carefully designed structure. All this is possible with html, but not for casual writer.

On the contrary, when using linuxdoc or docbook, the parser don’t accept too lazy layout. Also, people able to cope with linuxdoc and even more docbook, are not usually lazzy people .

The wiki have the same drawback, but being openwriting, we can hope experienced users to help new commers.

We yet have to document and develop a more structured help…

DocBook me está gustando porque simplifica la tarea de la generación y mantenimiento de la documentación. En esta entrada voy a comentar cómo utilizar XInclude para insertar ficheros externos en la documentación, ahorrando la tarea de editarlos, escapar caráctares e insertar. Porque si eso lo vamos a hacer con todos los fragmentos de código, ficheros XML, etc y es programable, pues que lo haga el ordenador.

Concretamente se ilustra el caso con la inserción de un fichero XML, que de otra forma deberíamos editar para escapar los carácteres XML. Con XInclude e indicando text en el atributo parse, tendremos lo mismo pero sin hacer ese trabajo.

Tenemos en un nuestro directorio de trabajo dos ficheros XML: el primero (articulo.xml) es la fuente DocBook, mientras que el segundo (pom.xml) contiene el fichero XML que deseamos insertar en docbook.

<?xml version=”1.0″ encoding=”utf-8″?>
<article xmlns=”http://docbook.org/ns/docbook”
xmlns:xi=”http://www.w3.org/2001/XInclude”
xml:lang=”es”>

<section xml:id=”pom”>
<title>Fichero POM</title>

<para>Aquí va el fichero pom.xml</para>

<programlisting><xi:include href=”pom.xml” parse=”text” /></programlisting>
</section>

</article>

Finalmente basta añadir la opción –xinclude en la llamada a xsltproc:

xsltproc --xinclude --o articulo.xhtml /sw/share/xml/xsl/docbook-xsl/xhtml/docbook.xsl articulo.xml

Si lo que se desea es insertar un fragmento de XML se puede realizar con el xinclude, por ejemplo si se quiere añadir el noveno elemento del elemento raíz mostrando un mensaje de error en caso de fallo, de esta forma se procesa el documento.

<programlisting>
<xi:include href=”pom.xml” xpointer=”element(/1/9)”>
<xi:fallback>no cargado pom.xml</xi:fallback>
</xi:include>
</programlisting>

Publican, a single source publishing tool based on DocBook XML has been updated to version 0.39. Be sure to check out the new SELinux User guide for the end result of a publican book.

The Publican 0.39 package is still in testing Fedora 9 and Fedora 10, so try it out, and leave some postive khama:

https://admin.fedoraproject.org/updates/publican-0.39-0.fc10,publican-fedora-0.16-0.fc10

https://admin.fedoraproject.org/updates/publican-0.39-0.fc9,publican-fedora-0.16-0.fc9

My main box is broken. Something with the power supply or/and the I/O controllers. Usually, the OS hangs in the middle of booting, mostly when it comes to some I/O thingy. Most recently, that got added up by middle-of-the-session instant-shut-downs. Like if someone pulled the power plug. Until now, the file system survived that. However, a backup’s urgent to make.

On the other hand, a while ago I thought it’d be an improvement to get rid of all these power consuming, audible machines. Also, I want to get rid of that hardware fiddling. I’ve been doing this since twenty years now. IT has outgrown that state of the art. Why not use any one-piece boxes? — I’d like to replace my current home system by embedded systems or netbooks or the like. One issue, however, might be in backups, as those need to go out of the grid somewhere, to any optical media, so I can keep the backup distinct of the system.

As the main box is broken, I increased the amount of time spent on that old 400 MHz box. It’s no miracle of speed, but it’s okay.

Also, I just set up my first net-bound system, that is a box on a virtual host, something like Slicehost, but with lower fees.

I am amazed of the possibilities.

Yet, I long for getting a bliki of my own, as I see wiki-bound documenting works out for me. Plus, apparently, I am better in that than in blogging. Which could be/become some kind of business card for me. (I’m after to get into the trend of building a brand around yourself.)

But what about having a netbook for mobile operation, no internet connection on the train, and the wiki/bliki net-bound somewhere there — on the net? Yet sniffed around a bit for ”wiki synchronization” wiki synchronization.

However, about my net-bound box, I’m short of finishing the backup scheme (I might follow the proposed rsync approach) and have work to be done on the plate — like rendering 500 MBs of screenshots into a Word file — I’ll use DocBook instead, then bump it out to RTF. (Did I blog about my toolchains from DocBook to HTML/PDF/RTF/ODF, anyway? — Still need to accomplish that. — See, why I am in need of a bliki?)

However, therefore, I need to skip the bliki intend for now. And keep the netbook chance on my radar.