view · edit · history · print

SourceDoc

Don't you hate it that you always have to wonder what documentation format you will use next? You've got HTML here, some ASCII there, a Wiki somewhere on the web, numerous Word(tm) documents, PDF documents, maybe some Docbooks, TeX documents, POD, XML, etc... I WANT 1 SIMPLE FORMAT. But hey, where do i start?

Rules:

  • We obviously need all these different formats for different purposes and requirements - conversion should be (made) possible.
  • It should be easy to read withouth a interpreter, the markup should not bother us too much - no propriatary Word(tm) formats.
  • Not only be reading but also editing withouth a special editor is importand- no Docbook.
  • We must be able to modify at all times, no read-oly formats - no PDF.
  • The source document must allow formating characters that can be interpreted by converters - no ASCII.
  • Converting documents can be done in multiple steps, allowing to refurbish more existing converters.
  • Converting back is not a luxury, we need to get our spread info down to 1 format.
  • The wiki philisophy compared to html is valuable.

Conversion tools:

  • pod2html, pod2latex, pod2man (plain old documentation =>)
  • a2ps (any => postscript)
  • man2texi (nroff => texinfo)
  • man2html (nroff => html)
  • unroff, troff2page (troff => html)
  • troffcvt (troff => rtf)
  • texi2html, an (actively maintained) alternative translator for generating HTML, roff, and chm.
  • texi2latex, converting Texinfo to LaTeX via XML.
  • texi2roff, an old standalone program that converts to troff format; it is not maintained and not up to date.
  • texinfo2rtf (=>Rich Text Format)
  • latex2pdf, tex2pdf, pdflatex (TeX->DVI->PS=>PDF)
  • latex2ps (=>PS)
  • latex2html, vulcanize (=>HTML)
  • latex2rtf, ltx2rtf (=>RTF)
  • Word2TeX, TeX2Word (Ms. Word(tm) <=>TeX) NON FREE
  • Writer2LaTeX, Writer2BibTeX, Writer2xhtml, Calc2xhtml (Open Office =>)
  • sgml2tex (sgml => tex)
  • doc2rtf, doc2ps, doc2txt, doc2html, doc2pdf (ms word(tm) =>)
  • wt2db (WikiText => DocBook XML/SGML)
  • html2wiki (html => wiki)
  • rtfdtohtml (NEXT rtf => html)
  • asciidoc converter
  • ...

Links:

Interesting formats:

  • RTF : propriatary but widely supported in lots of editors as secondary format and human readable.
  • RTFD : NEXT / OSX format, a bundle (folder) with attachements and a TXT.rtf doc.
  • POD : good simple basic markup with different available converters.
  • PS & PDF : read-only but generic, a must-have.
  • HTML : Still alive out there!
  • man-pages (nroff & troff) : people like me need this!
  • (La)TeX : THE document formatter with different available converters.
  • ...

Typical formats:

  • Source: pod,word,writer,tex,sgml,asciidoc
  • Intermediate: tex,ps,roff,xml
  • Target: rtf,html,pdf

Investigating different documentation formats...

Extended Backus-Naur Form (EBNF)

ASN #1

The XML/CSS combination (for the web)

  • hype? special editor, badly readable, 2 files!

SGML

  • obsolete hypertext format? too monstrous, use the XML subset?

XML

  • most converters are graphical win32 ones.
  • not readable in source format.

PODs

  • obsolete or just "Plain Old Decent"?

TeX

  • good target and intermediate format?
  • complex.

roff (man pages)

  • troff/nroff is not too difficult.

ASCII

  • no markup for interpretation

tools: Lex / Yacc

  • N/A dinosoft?

Something "LISP Machine" - like ?

RTF/RTFD

Markup:

Basic

  • headers
  • paragraphs
  • bold & italic
  • sepparator line (<hr>, page break)
  • monospaced text
  • indentation

Optional

  • color
  • tables
  • size
  • attachments (in rtfd, pdf, html, TeX)

Specials

  • index generation
  • special headers (like for UNIX* man pages (synopsis))
  • graph

Lets not jump to conclusions here but for now i tend to think the following... Editable via on-line editor or any other locally available editor! Wiki? Bad choice, out of scope, na. or... good choice? which dialect? Available conversion tools? It served we well for "this" website! But 1 teenie wienie problem. Not a lot of converters. And surely not to source formats.

At first i wanted to get my mind away from this crazy wiki idea as a general purpose document system but the longer I think abouth it the more it starts making sense. But [for now] it won't hapen withouth getting my hands dirty.

Exploring the wiki option:

The best editor is an overall available editor and every platfor has its own ASCII editor so we can use that one. But today we may have an alternate option, the general purpose interface for all patforms is the browser. If your system is connected to the net the better that allows you to access your docs at all times. Having no web acces can be solved by mirroring the data on a portable system.

The easyest method known today for creating and editing on-line documetation is the wiki method with all it's benefits. Conversion to other formats can also be made available throug this web approach by providing "conversion buttons", "uploads" and "send me e-mail" functionalities.

One thing is clear, tools will have to be written to convert wiki code to other source formats and back if i choose this path.

admin · attr · attach · edit · history · print
Page last modified on January 30, 2010, at 12:19 PM