Source

shlomi-fish-homepage / t2 / philosophy / computers / web / choice-of-docs-formats / index.html.wml

Full commit
#include '../template.wml'

#include "xhtml/1.x/std/toc.wml"

<latemp_subject "Choice of Document Formats" />
<latemp_meta_desc "Choice of Document Formats" />
<latemp_more_keywords "HTML, DocBook/XML, POD, TeX, LaTeX, documents, formats, document formats, perl, wiki, MediaWiki" />

<h2 id="about">About this Document</h2>

<p>
This is an overview of popular file formats, which is
derived from a reply I wrote to a thread in the
<a href="http://mail.pm.org/mailman/listinfo/boston-pm">Boston Perl Mongers
mailing list</a>.
</p>

<h2 id="toc">Table of Contents</h2>

<toc />

<h2 id="meta">Document Information</h2>

<dl class="meta">
<dt>
Written By:
</dt>
<dd>
<a href="http://www.shlomifish.org/">Shlomi Fish</a>
</dd>
<dt>
Finish Date:
</dt>
<dd>
23-July-2006
</dd>
<dt>
Last Updated:
</dt>
<dd>
23-July-2006
</dd>
</dl>

<h3 id="licence">Licence</h3>

<p>
<a rel="license" href="http://creativecommons.org/licenses/by/2.5/"><img 
alt="Creative Commons License" class="bless"
src="$(ROOT)/images/somerights20.png"
/></a><br />
This work is licensed under a 
<a rel="license" href="http://creativecommons.org/licenses/by/2.5/">Creative 
Commons Attribution 2.5 License</a>.
</p>

<h2>The Article Itself</h2>

<p>
A previous correspondent wrote:
</p>

<blockquote>
<p>
Write it in POD?
</p>
<p>
I'm not aware of any POD based Wikis, but it doesn't seem like it would
be hard to merge the two approaches, with a "traditional" web-facing
wiki front-end that stores things as a POD-like syntax on the back.
</p>
<p>
This way, you get the collaborative editing and there are already tools
out there to convert the POD source to PDF etc.
</p>
</blockquote>

<p>
I think <a href="http://www.kwiki.org/">Kwiki</a> has a 
plugin for <a href="http://perldoc.perl.org/perlpod.html">POD (Perl's so-called
"Plain, Old, Documentation")</a>.
</p>

<p>
Just a note about POD: POD is incredibly limited. Some things that you may 
want to try to do with it are not possible. It is not the only generic format 
available, however. One option is naturally 
<a href="http://www.docbook.xml.org/">DocBook/XML</a>, which can be 
translated into HTML as well as PDF, Microsoft Word, LaTeX and other 
formats. It cannot be directly translated to plain text, but can through
an intermediate format. POD can be translated into DocBook/XML using 
<a href="http://search.cpan.org/~nandu/Pod-DocBook-1.2/">Pod-DocBook-1.2</a>.
</p>

<p>
Don't use the original module by Alligator Descartes which is the still the 
default on <a href="http://www.cpan.org/">CPAN</a> out of being 
<a href="http://www.mail-archive.com/module-authors%40perl.org/msg00793.html">a
Dead Camel</a>. It is old and broken and has been unmaintained for a long time.
</p>

<p>
Note that the DocBook generated may not be perfectly semantically-correct due 
to the fact DocBook is richer than POD.
</p>

<p>
Other alternatives for such markups that are somewhat 
text-with-brief-style-specifiers can be found in 
<a href="http://zgp.org/pipermail/linux-elitists/2005-August/011252.html">this 
Linux-elitists thread</a>.
</p>

<p>
They all can be converted to HTML and some of them to DocBook too. One Wiki or 
another is also an option, but note that they tend to have incompatible 
formats, and some may not have an ability to export as DocBook. I like the 
<a href="http://www.mediawiki.org/">MediaWiki</a> format which is an 
extension of that of 
<a href="http://www.usemod.com/cgi-bin/wiki.pl">UseModWiki</a> (and its 
<a href="http://www.oddmuse.org/">Oddmuse Wiki fork</a>, which should be 
better.), but I think that DokuWiki's format is 
also quite good. I really dislike the default Kwiki format, and despite all
the flood of Kwiki plugins, no-one has written a 
UseModWiki/Oddmuse/MediaWiki-subset format for it yet. I keep intendening to 
do that, but I could not find the time yet.
</p>

<p>
You can also try to use XHTML 1.1 with semantic markup of elements for use
as a good generic markup.
</p>

<p>
All that put aside, I should note that if you are thinking about using TeX or 
LaTeX, please re-consider. Tex/LaTeX are very convenient for generating 
PostScript or PDF but:
</p>

<ol>
<li>
<q>The only thing that can understand TeX is tex</q>. I believe it was said 
much earlier than when Tom Christiansen ported it to the Perl world. It is in 
fact much more true for TeX than it is for Perl.
</li>

<li>
Conversion of LaTeX to DocBook or HTML often doesn't work quite well. 
Often, the tools are outdated and generate old or invalid HTML, and often 
they break on more than complex LaTeX. TeX and LaTeX are Turing-complete, and 
the syntax is incredibly problematic.
</li>

<li>
LaTeX has poor support for hypertext, and other PDF niceties.
</li>

<li>
PDF and PostScript, which are the default-and-least-error-prone TeX 
formats, have relatively poor accessibility and internationlisation. For 
example, from my understanding Bi-directional text (mixed Arabic-English 
text, etc.) is rendered visually.
</li>

<li>
It is easier to convert semantic XHTML or DocBook/XML to LaTeX than the 
other way around.
</li>
</ol>

<p>
LaTeX is much less verbose than DocBook/XML, but I think you can find a less 
problematic format. It is is still excellent for writing texts with lots of 
mathematical formulae, but still a very problematic format. When working with 
LaTeX I often get obscure TeX errors that I can't tell immediately what 
exactly went wrong. In DocBook/XML it just reports that one tag is missing, or 
that the order of tags are incorrect, which takes me much less time to solve.
</p>

<hr />

<p>
Going full circle now - POD is a good option if it does what you need. The 
Camel Book and other perl books were written in POD. I wrote some
documentation for Perl and non-Perl projects in POD. I also write all my man
pages in POD because nroff scares me.
</p>

<p>
But if you feel that you want something better, you have many options.
</p>

<p>
One final note is that DocBook/XML was problematic for using in bi-directional
texts because of implementation or standard problems, last time I checked. 
Otherwise, its Unicode support should be very good.
</p>

<h2 id="coverage">Coverage and Comments</h2>

<p>
TODO: Fill in.
</p>