Re: [ros-dev] Documentation

[Klemens Friedl]

My thoughts...

Plain Text
It cannon be denied that plain text is the single one format that
everyone can process on every system. A second format that is used
almost everywhere is the HTML syntax. Every platform has its
web-browser clients, be it text or graphical ones.

HTML
Additionally the HTML syntax is really simple, you don't have to use
extensive tags, some basic tags for bold, italic, underline, indent,
paragraph, line-break and how to create a simple table are enough. No
one has to use a simple text editor to write html documents, there are
a lot of WYSIWYG-Editors around (just don't use MS Word for that task,
or at least clean up afterwards).
In my opinion, it would be a good idea to use real standard formats
that are already in use for years and will be around in years too.

PDF
If you really want to use a read-only format, use PDF (version 1.4) or
PDF/A (archive).
Text documents should be saved in UTF-8, UTF-16 (or ANSI) and don't
forget to set the "svn:eol-style=native" svn tag.

SPREADSHEETS
For special cases like spreadsheets, CSV format or HTML tables would
be suitable too.

PRESENTATIONS
Presentations can be exported as PDF files or optionally as HTML
file(s). Nevertheless, PowerPoint presentation files are quit common
too.

PICTURES
Given the popular image formats, I would like to propose JPEG, PNG,
TIFF (and BMP) for bitmap graphics and maybe SVG, EPS (and AI) for
vector graphics.

OFFICE FORMATS
Regarding popular but (non-)standard and vendor specific office
formats, avoid them in svn repo, if possible. In general try to save
it as MS Office 97 documents. Almost every office software package can
at least import and read word 97 documents, additionally several (3,
one still active) open source projects exist that allow you to process
MS Office 97 files.

NEW OFFICE FORMATS
XML based office formats like the one form AbiWord,
OpenOffice/StarOffice, MS Office have one in common, all use the zip
format as container for its xml based documents.
While it can be opened and accessed more easily, currently only
limited range of tools exist that are able to parse them. Furthermore,
from current point of view we can only guess if most of these formats
will be still around and readable in the next few years. And don't
forget, to a certain degree it's already valid for MS Office 1-6, MS
Works, Lotus, etc. formats.


Klemens