Commits

shl...@cec68495-dca5-4e2b-845c-11fdaaa4f967  committed ac054a3

Added the choice of docs formats essay.

  • Participants
  • Parent commits 9f50273

Comments (0)

Files changed (3)

File lib/Shlomif/Homepage/SectionMenu/Sects/Essays.pm

                     'url' => "philosophy/computers/open-source/gpl-bsd-and-suckerism/",
                     'title' => "The GPL, The BSD License and Being a Sucker",
                 },
+                {
+                    'text' => "Choice of Doc Formats",
+                    'url' => "philosophy/computers/web/choice-of-docs-formats/",
+                    'title' => "Coverage of the Current Choice of Document Formats",
+                },
             ],
         },
         {

File t2/philosophy/computers/index.html.wml

 </p>
 </div>
 
+<h3><a href="$(ROOT)/philosophy/computers/web/choice-of-docs-formats/">The 
+Choice of Document Formats</a></h3>
 
+<div class="indent">
+<p>
+An email-turned-to-a-feature about the current (2006ish) choice in document 
+formats for writing documents.
+</p>
+</div>

File t2/philosophy/computers/web/choice-of-docs-formats/index.html.wml

+#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 wroted 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>
+<b>P.S:</b> DocBook/XML is problematic for using in Bi-Directional texts 
+because of implementation problems. Otherwise, its Unicode support should be 
+very good.
+</p>
+
+<h2 id="coverage">Coverage and Comments</h2>
+
+<p>
+TODO: Fill in.
+</p>
+