Re: [documentliberation-discuss] File Format Documentation

Hi,

On Sat, May 24, 2014 at 12:19:34AM +0400, Jay Philips wrote:
> Hi All,
>
> I recently watched Fridrich's talk in Brazil <
> http://www.youtube.com/watch?v=tHgER_7febE > and was saddened to hear
> that the project has no intentions to do documentation of the formats it
> creates libraries for.

That is not quite true. We have no intention to provide written
specifications; however, we maintain a programmatic description of many
formats in OLEToy (https://gitorious.org/re-lab/tools/). OLEToy does not
do any conversion, it just displays the structure of a binary file as a
tree. So there is very little (if any) additional code that would
distract the reader. OLEToy is written in Python, so it is quite
high-level and much easier to read than C++ (which is our language of
choice for import libraries). Consequently, we believe this form of
"documentation" is much more suitable for writing an import library than
any formal specification. Plus, one can load a document and immediately
see the details of its content. One cannot do that with a
specification...

> I believe documentation will liberate document
> formats even further and can bring in collaboration of format
> information from contributors who are/have also work on opening those
> same file formats in other applications, programming languages and
> operating systems.

Our understanding of any given file format is often "work in progress",
which means we have to change our assumptions as we encounter new files
that do not fit them. Trying to maintain an up-to-date specifications
would be a lot of extra work, that, by our belief, would not add much
value. That said, if someone wanted to jump in and write a specification
for a format based on the code in OLEToy, we would not discourage him.
We just do not see that as our primary objective.

> So i humbly request that you consider doing some documentation,
> even if it were an outline or summary to begin with.

As I explained above, we believe that a programmatic description of a
file format in OLEToy is actually superior to a written specification,
for the purpose of writing an import filter.

D.

-- 
To unsubscribe e-mail to: discuss+unsubscribe@documentliberation.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.documentliberation.org/www/discuss/
All messages sent to this list will be publicly archived and cannot be deleted