Hi,
On Jan 3, 2006, at 3:26 AM, Alberto Bertogli wrote:
On Sat, Dec 31, 2005 at 11:37:48AM +0000, Pedro Melo wrote:
My suggestion:
- _darcs/third_party is the base for all this;
- BASE/common can have common attributes to all applications. We
could have a wiki page as the "official" spec. Some of the attributes
would include:
- description: one line short description of the repo, plain-text;
- abstract: longer description of the project. The first line can
be a "Content-type: MIME\n\n". If not present assume text/plain;
- project_homepage: an URL
- authors (?): list of authors? Different from owner/author of
the repo sometimes.
- BASE/app_name: you own private variables.
Well, since I guess we all agree on the basics, here's a small
draft for a
proposal we can build on (or discard, if you think it's crap).
Please let
me know what you think of it =)
I've included what's shown up there, except for the authors part,
which I
don't find really clear (is it a list of people who commited?
arbitrary
list of authors? is that really useful and meaningful?) and I
prefer to
add it later if necessary.
Agreed.
I've also added an "encoding" file, because I think that's really
useful
for most, if not all, third-party applications in some way.
Thanks,
Alberto
Third-party applications directory
----------------------------------
Introduction
------------
This document specifies the policy third-party applications should
follow
if they want to be nice to the rest of the darcs community and make
the
world a better place for the children.
It was written taking David Roundy's suggestion as a base, you can
find it
in
http://www.abridgegame.org/pipermail/darcs-users/2005-November/
008745.html.
If you don't agree with this document, please don't ignore it, but
discuss
the issues with the community so we can all benefit from comments and
present the user a coherent interface he can rely on.
You can send comments to the darcs-users and/or darcs-devel mailing
lists.
Please do NOT modify this Wiki page without authorization, as it is
used
as a standard guide. Suggestions should be sent to the list to be
discussed, and modifications will be done appropiately when there's
agreement.
Directory layout
----------------
Third party applications that need to store repository-specific
data can
make use of the "_darcs/third_party/" directory.
They should create a directory named after their application, like
"_darcs/third_party/darcs2rss/" and place appropiate files there.
What's stored inside this application-specific directory is up to the
application author.
As a recommendation, remember that darcs runs in multiple platforms,
including Windows, where filenames are case-insensitive. If you expect
your application to be portable, don't rely on file casing.
The "common" directory
----------------------
There's a special directory, "_darcs/third_party/common/", where a
defined
set of files that most third-party applications find useful are
stored.
You should NOT store additional files there, or modify them
automatically.
You should only modify them under user authorization, and after
notifying
that those settings are shared with other applications.
The following is the list of files that live in this directory,
along with
their description. Examples are below.
* description
A one-line, plain description of the repository, in the repository
encoding.
* project_homepage
The URL of the project the repository refers to. Only one, in one
line, properly escaped if necesary.
* abstract
A brief description of the project. It can span multiple lines.
It should be in plain text in the repository encoding, unless you
specify, in the first line, the content type in MIME-style.
We need a way do disambiguate this first line. Maybe we should write
this instead.
--------
A brief description of the project. It can span multiple lines and it
should be in plain text in the repository encoding
If a diferent format or encoding is required, the file can start with
"Content-type: your_content_type_here; charset: your_charset_here\r\n
\r\n"
--------
I would like a better text... But that's the best I can do right now.
* encoding
The encoding used for repository data and metadata (ie. covers
files AND patch descriptions).
I agree that this file is better than nothing, but eventually this
should be done by darcs it self. IMHO, all patch descriptions should
be UTF8 always.
If I import patches with a different encoding, this file will be
lying to me :)
But apart from this, looks great!
Best regards,
--
Pedro Melo
JID: [EMAIL PROTECTED]
_______________________________________________
darcs-users mailing list
[email protected]
http://www.abridgegame.org/mailman/listinfo/darcs-users
