apiote-website/manifestos/formats.rst

Formats manifesto
================

Why?
---

Mainly, because a friend of mine once showed me `Coding2Learn <http://coding2learn.org>`_, a great blog by Marc Scott containing an entry entitled `Please stop sending me your shitty Word documents <http://coding2learn.org/blog/2014/04/14/please-stop-sending-me-your-shitty-word-documents>`_.

But also because I think it’s proper and, what is probably most important, convenient.

Prologus
--------

I love standards. And I love them open, free (as in beer and speech), and simple. Without standards we couldn’t watch funny cats on the Internet.

Meritum
-------

This website
~~~~~~~~~~~~

This website works as intended with the latest stable version of Firefox®`[1] <#ref1>`_. It means that—for now—it should work on all major browsers.

This may change when Firefox decides to implement WebP support. Then, `some browsers <http://caniuse.com/#search=webp>`_ may not show images.

Text
~~~~

Text should be plain. I could call “period” here but I’ll explain my point of view.

There are actually two disjunctive cases:

**formatting is not important**

    Then don’t include it. You don’t have to wrap a little of text into a huge binary format of any office suite. Open a notepad of choice, type it, and save as text file. Formatting text that doesn’t need it is a waste of time and resources. And it hurts the eyes of the reader.

    If You want to emphasize something, put a list, or a header, then use a markup language. Previous versions of this manifesto recommended Markdown. I realised however that Markdown is not a standard and comes in various flavours. Since then I’ve been recommending RestructuredText. Still, it’s just a recommendation, You can send me any reasonable markup language. But I repeat: *resonable*.

**formatting is important**

    I get it, there are official documents, CVs, company print-outs with logos, books, articles, etc.  Still, it’s even worse idea to use office suite formats in this case, because what You send may not be the same to what I receive—my program may be different, I may have to import Your proprietary format, or my program may just be a different version—the document may fall apart.

    Use PDF if You want to give me a finished document, use LaTeX if You work with me on the document.

I hereby promise not to ever send You office suite documents, and to use plain text, RestructuredText, PDF, or LaTeX instead.

Typography
~~~~~~~~~~

We fortunately live in the times of Unicode, when with single encoding we can produce a text containing characters from enormous number of languages. It’s painful when people use ‘-’ (hyphen-minus, U+002D) when it should be ‘–’ (en dash, U+2013), ‘—’ (em dash, U+2014), or rarely ‘−’ (minus, U+2212). Also " and ' (typewriter quotation marks) are not the same as “,” (double quotes, U+201C and U+201D) and ‘,’ (quotes, U+2018 and U+2019). It’s especially the case in Polish in which the left quotes are respectively „ (U+201E) and ‚ (U+201A). One more notable example is ... (three dots) instead of … (ellipsis, U+2026).

Specific list of proper characters is way beyond the capacity of this entry.

Please, review the use of proper characters You write, which I also hereby promise to do. 

Emails
~~~~~~

As I stated above “Text should be plain.” Not only is HTML in emails a waste of time and resources, but also security threat, as it may contain malicious code. Moreover, people using text-based email clients hardly ever receive HTML emails properly (this apply to me).

I hereby promise not to send HTML emails.

Date & time
~~~~~~~~~~~

For expressing date and time there is the way standardised by `RFC 3339 <https://tools.ietf.org/html/rfc3339>`_.

If the time-zone is omitted, I understand that either the local time-zone applies—if the place is given—, or the time is in UTC, otherwise.

On a side note neither is the calendar nor the clock we use logical. That’s why I prefer `dozenal clock (with 24 hours) <http://dozenalsociety.org.uk/apps/timeunits.html>`_ and `thirteen month calendar <https://en.wikipedia.org/wiki/International_Fixed_Calendar>`_. However—logical as they are—they are unusual so I won’t use them without Your explicit consent.

Photos & pictures
~~~~~~~~~~~~~~~~~

For vector graphics there is an open standard – SVG.

For raster graphics there’s not one, perfect standard so I’ll accept all major formats. From me, You can expect exactly 2:

- if I have access to the original, raw data, I’ll use TIFF with LZW compression,
- otherwise, I’ll use WebP.

The reasons for using WebP are:

**versatility**

    it can be animated (instead of GIF/APNG) and can hold alpha (instead of GIF/PNG) at the same time,

**size**

    it’s visibly smaller (in bytes) than other formats with the same quality.

**colour space**

    it’s not indexed (unlike GIF), and so it’s more convenient to edit.

Sound
~~~~~

Like with images, there’s no standard.

From me, You can expect 2 formats:

- if I have access to the original, raw data, I’ll use FLAC,
- otherwise, I’ll use Opus.

Videos
~~~~~~

Again, no standard.

This time, You can expect: WebM (when it takes reasonable time to encode) or Matroska with H.265 for video and Opus for sound.

(I’m following the development of AV1, and I’ll be more than glad to use it when it’s ripe and encoders are fast.)

Epilogus
--------

As I said, it’s for convenience and to respect the receiver—nobody has to use some esoteric software.

If You feel I offended You, have some remarks, think something is better, then feel free to use any kind of contact to share Your thoughts with me, e.g. the contact form available `there </contact>`_.

.. div:: refs
    .. _ref1:
    1. Firefox is a trademark of the Mozilla Foundation in the U.S. and other countries.