perldoc2-developers — perldoc 2.0 - International Perl Documentation - developers

Re: [perldoc2-developers] which framework?

[Gregor G. <7go...@in...>]

Joergen W. Lang wrote:
> Which framework are we going to use?
> Maypole, Catalyst or something completely different?
>
> Your opinions, please!
>   
Since I have no experience with any framework at all I'll just agree to
whatever your other guys choose ;)
I understand at least one member of this list hacks on Catalyst. Is
there any reason to *not* pick Catalyst then?

I expect all of these are easy to set up, flexibel, perlish, pluggable
etc... am I wrong?

  Gregor

Re: [perldoc2-developers] Meet the team

[Joergen W. L. <joe...@gm...>]

Hi Nicolas and all the others,

thanks for committing the french POs and the Makefile. I hope to find 
some time to have closer look during the next few days.

5.9.2 directories: This is obviously a mistake on my side. I will change 
that - well - actually - now.

Joergen

Nicolas François schrieb:
> On Sat, Nov 18, 2006 at 01:12:08AM +0100, Joergen W. Lang wrote:
>> Otherwise it would be great to have those french pot files in the 
>> repository to play with. If something changes just commit the new 
>> version. After all, that's what SVN is for. :o)
> 
> I committed the French POs for perldoc 5.6.2 and 5.8.8 and the Makefile to
> play with them.
> 
> The top of Makefile explains some of the rules.
> 
> I noticed that you committed some 5.9.2 directories instead of 5.9.4. Is
> there a reason, or is it just a typo?
> 
> If you want to play with the Makefile, you can for example change the
> translation of "NAME" in one PO, then run "make merge_fr" and see how this
> change is propagated to other POs.
> You can also generate the translations with "make translate_fr".
> 
> Kind Regards,

Re: [perldoc2-developers] datase vs. versioning

[Joergen W. L. <joe...@gm...>]

Hi Nekral,

now *this* is important! Maybe we don't have to build from scratch at 
all. Especially TransDict looks interesting since it's written in Perl. 
I will have a look at it tonight.

Joergen

Nicolas François schrieb:
> Hi,
> 
> Just a note about the specifications.
> 
> Building a generic translation framework is something quite difficult, and
> other projects are already working on it: Rosetta, Pootle, Transdict, etc.
> 
> IIRC, the specifications for Rosetta are publicly available (but the
> implementation is not free). The Pootle's specifications are publicly
> available
> (http://translate.sourceforge.net/wiki/wordforge/functional_specificaions)
> 
> They may be worth reading if you want to build a translation
> infrastructure .
> 
> Best Reagrds,

Re: [perldoc2-developers] Meet the team

[Nicolas <nek...@gm...>]

On Sat, Nov 18, 2006 at 01:12:08AM +0100, Joergen W. Lang wrote:
> 
> Otherwise it would be great to have those french pot files in the 
> repository to play with. If something changes just commit the new 
> version. After all, that's what SVN is for. :o)

I committed the French POs for perldoc 5.6.2 and 5.8.8 and the Makefile to
play with them.

The top of Makefile explains some of the rules.

I noticed that you committed some 5.9.2 directories instead of 5.9.4. Is
there a reason, or is it just a typo?

If you want to play with the Makefile, you can for example change the
translation of "NAME" in one PO, then run "make merge_fr" and see how this
change is propagated to other POs.
You can also generate the translations with "make translate_fr".

Kind Regards,
-- 
Nekral

Re: [perldoc2-developers] datase vs. versioning

[Nicolas <nek...@gm...>]

Hi,

Just a note about the specifications.

Building a generic translation framework is something quite difficult, and
other projects are already working on it: Rosetta, Pootle, Transdict, etc.

IIRC, the specifications for Rosetta are publicly available (but the
implementation is not free). The Pootle's specifications are publicly
available
(http://translate.sourceforge.net/wiki/wordforge/functional_specificaions)

They may be worth reading if you want to build a translation
infrastructure .

Best Reagrds,
-- 
Nekral

[perldoc2-developers] which framework?

[Joergen W. L. <joe...@gm...>]

Me again,

another question that needs to be clarified before we start:

Which framework are we going to use?
Maypole, Catalyst or something completely different?

Your opinions, please!

Joergen

[perldoc2-developers] datase vs. versioning

[Joergen W. L. <joe...@gm...>]

Hello everybody,

here is one question that needs to be resolved, before we start coding. 
Currently we are simply using SVN to store the documents and their 
translations.

As I wrote in the specification Vs. 0.1 a database could also be used 
for storage. The advantage appears to be that we do not have to add 
another layer of complexity to the application. Only one method is 
needed to access application data, documents and meta information.

Now - there appears to be one problem: What about versioning the 
translations? In one or the other situation there might be a need to do 
a "rollback" to a previous version of a translation.

Versioning systems like SVN are made exactly for this, but might not 
have the convenience of a database.

If we decide in favour of a database, we'd have to implement versioning 
by ourselves which might outweigh the complexity of another layer.

For the moment we could simply use the SVN repository on sourceforge as 
our central storage area which is fine as long as we do not need any 
extra features.

Please let me know your opinions and ideas!

Joergen

Re: [perldoc2-developers] [RFC] Platform Specification Vs. 0.1

[Joergen W. L. <joe...@gm...>]

Hi y'all,

sorry for being so quiet. I was on tour with my band. Apparently I 
marked Robert's mail about the specs as "read" before I actually did 
read it. I am currently preparing Version 0.2 of the specs.

Thanks, Robert for taking the time to review the specs!

Most of the suggestions have found their way into Vs. 0.2 so I will not 
go into much detail here and simply post the new version here and in the 
Blog.

I can see two issues that need to be discussed:

- what platform are we going to use?
- DB vs. SVN

I will start seperate threads for these.

In principle I'd say we should try to get a working example on the way 
ASAP so we have something to look at.



[storing meta data in document]
> * po4a

> I don't really know po4a's metadata capabilities, so I can't comment on
> this.

po4a allows the storage of meta data in two ways:

- by using certain "headers" in the form of .po comments
   These store the meta information about the document itself like
   charset, date of translation...

- by using so-called "addenda" files which are stored seperate from
   the actual document and are merged into the finished translation
   before publishing.

   These contain informations about translators involved, changes, etc.

Expect more, soon,

Joergen

Re: [perldoc2-developers] General Questions

[Joergen W. L. <joe...@gm...>]

Robert 'phaylon' Sedlacek schrieb:
> Joergen W. Lang said:
>> I'd prefer an "out of the box" approach as much as possible unless we
>> have a really good reason not to.
> 
> Define "out of the box"? No external dependencies? This would be hard.
> That's why I proposed using PAR for distribution.

If a web-framework already offers the features we need we should not 
reinvent/reimplement without good cause.

>>> Also a possibility. Although I see the "other projects" and "whole
>>> different languages" target groups more fit to this way of distribution.

>> That would oppose the "simple" principle, though. After all the
>> application itself does not really have to be "distributed", it's the
>> services it offers - and they are distributed over HTTP, etc.
> 
> Yes, but as I have stated a few mails earlier, this application would have
> large potencial to be useful for other projects too. Or do you want to
> host all possible translation projects on this one server?

To be honest, I didn't think of this at all. But I can see your point. 
And I do not think, it would add more complexity to the project if we 
keep in mind that it should be portable to other servers, too. Under 
these circumstances apachefriends XAMPP might actually be not so bad at 
all. Did you ever try it? I mean, installing and configuring a LAMP by 
hand *can* be tedious. XAMPP does it in a few minutes.

>>> Which might be a much better fit. Sidenote: Of course I mean the
>>> translation platform itself, not the hosting of the finally translated
>>> files.

>> Oh - really? :o)
>>
>> Let's hope the translated files eventually reside on peoples harddrives
>> or under xx.perldoc.perl.org.
> 
> This would be the best, yes :)

Basically we have "go" for finished translations of the "actual" version.

>>> For that I'd think a sort of export (e.g. into the projects SVN, so
>>> everyone, including the $lang.perldoc.perl.org space can easily stay up
>>> to date) would be a much better fit for that.

Joergen

Re: [perldoc2-developers] General Questions

[Robert 'p. S. <rs...@47...>]

Joergen W. Lang said:
>
> I'd prefer an "out of the box" approach as much as possible unless we
> have a really good reason not to.

Define "out of the box"? No external dependencies? This would be hard.
That's why I proposed using PAR for distribution.

>> Also a possibility. Although I see the "other projects" and "whole
>> different languages" target groups more fit to this way of distributio=
n.
>
> That would oppose the "simple" principle, though. After all the
> application itself does not really have to be "distributed", it's the
> services it offers - and they are distributed over HTTP, etc.

Yes, but as I have stated a few mails earlier, this application would hav=
e
large potencial to be useful for other projects too. Or do you want to
host all possible translation projects on this one server?

>> Which might be a much better fit. Sidenote: Of course I mean the
>> translation platform itself, not the hosting of the finally translated
>> files.
>
> Oh - really? :o)
>
> Let's hope the translated files eventually reside on peoples harddrives
> or under xx.perldoc.perl.org.

This would be the best, yes :)

>> For that I'd think a sort of export (e.g. into the projects SVN, so
>> everyone, including the $lang.perldoc.perl.org space can easily stay u=
p
>> to
>> date) would be a much better fit for that.
>
> That also should be part of the "workflow" page... more work... oh my!

Heh. That cmes with it :)

gr.,
Robert

--=20
# Robert 'phaylon' Sedlacek
# Perl 5/Catalyst Developer in Hamburg, Germany
{ EMail =3D> ' rs...@47... ', Web =3D> ' http://474.at ' }

Re: [perldoc2-developers] New member glauschwuffel

[Gregor G. <7go...@in...>]

Hi list,

my name is Gregor Goldbach and I've stumbled across this project last week.
I'm another German Perl hacker (apparently from around Hamburg).
Current interests in Perl include laughing about the 'yadda yadda
yadda'-operator in Perl6, testing and documentation.

Experience in Perl: just perl5 (about 5 years), modules, Test::More,
CGI, DBI (with Postgres).

Current most favourite phrase from perldoc:
perldoc -f goto:
[...]
The "goto-&NAME" form is quite different from the other forms of
"goto".  In fact, it isn't a goto in the normal sense at all, and
doesn't have the stigma associated with other gotos.
[...]

  Gregor

P.S. I'm a part-time student and part-time employee. My studies have
nothing to do with perl (luckily), just my work.

[perldoc2-developers] Away for the rest of the week

[Joergen W. L. <joe...@gm...>]

Me again,

I will be on tour with my band for the rest of the week. I will try to 
check my mail as regular as possible but some delays are possible.

Maybe this is a good opportunity to review the specification and add 
your comments and ideas.

There already has been quite a good bit of discussion (mostly between 
Robert and myself). I will try to refine this into some form of digest 
before I go so the rest of you does not have to read each and every 
sentence.

Greetings,

Joergen

[perldoc2-developers] New members

[Joergen W. L. <joe...@gm...>]

Hi folks,

I have invited to more people to join the list:

Steven and Gregor.
(Please introduce yourselves)

Both are willing to give us a hand (or two) with the platform. Please 
make them feel welcome.

Joergen

Re: [perldoc2-developers] General Questions

[Joergen W. L. <joe...@gm...>]

Robert 'phaylon' Sedlacek schrieb:

> CPAN :) The web frameworks manage their own dependencies pretty well. I
> mean we should discuss _which_ XML module we use, _which_ database access,
> and so on. To keep the dependencies as simple and as communicated as
> possible. This should ease deployment too.

I'd prefer an "out of the box" approach as much as possible unless we 
have a really good reason not to.

>>> [stability issues]
>>>
>>> That's rather a deployment and development issue imho. We should
>>> certainly do testruns before deploying/updating the main site. Things
>>> like PAR could also help us with this, as it captures a whole environment
>>> (optionally even including core modules).

>> Or one step further - and you have something like apachefriends.org's
>> XAMPP project.
> 
> Also a possibility. Although I see the "other projects" and "whole
> different languages" target groups more fit to this way of distribution.

That would oppose the "simple" principle, though. After all the 
application itself does not really have to be "distributed", it's the 
services it offers - and they are distributed over HTTP, etc.

[hosting on sourceforge]

> Question is which perl, what kind of webspace, how much influence on the
> perl environment, etc.

perl 5.8.3
Apache 1.3.xx?
...

Well... not very much info.

>> BTW - There's plenty of space on my server... :o)
> 
> Which might be a much better fit. Sidenote: Of course I mean the
> translation platform itself, not the hosting of the finally translated
> files. 

Oh - really? :o)

Let's hope the translated files eventually reside on peoples harddrives 
or under xx.perldoc.perl.org.

> For that I'd think a sort of export (e.g. into the projects SVN, so
> everyone, including the $lang.perldoc.perl.org space can easily stay up to
> date) would be a much better fit for that.

That also should be part of the "workflow" page... more work... oh my!

So far....

Joergen

Re: [perldoc2-developers] Meet the team

[Joergen W. L. <joe...@gm...>]

Hi Nicolas,

Nicolas François schrieb:

> I've made a Makefile to call po4a and update the POTs, POs, and
> translations.
> 
>         http://nekral.homelinux.net/perldoc2/
> 
> You can have a look at it and see how it works (I took the translations
> from the existing French translations

Hey, great job! I downloaded the files at top level but did not want to 
wget all the stuff in /translations/fr/. If you find the time, maybe you 
could make a tarball for that directory. That would be nice!

Otherwise it would be great to have those french pot files in the 
repository to play with. If something changes just commit the new 
version. After all, that's what SVN is for. :o)

(Apart from that, SVN activity keeps us up in the "charts" on 
SoureForge... )

> I also have the French POs for version 5.6.2 and 5.9.4, but I would like
> to make tests for merging from a version to the other (I did it manually,
> but would like to do it in the makefile). The makefile also lack a rule to
> detect strings translated differently from one PO to the other.
 >
> The Makefile has rules like all-pots, all-update-po, all-translate
> 
> update_pots_fr, translate_fr, update_po_fr
> or even update_pots_fr_5.8.8, translate_fr_5.8.8 and update_po_fr_5.8.8
> 
> It can also show statistics: all-stats, stats_fr and stats_fr_5.8.8
> 
> The versions and languages are auto detected.
> 
> I will commit this proposal if we agree on the hierarchy it creates in the
> 'translations' directory.

I can't wait to try it. As far as I can see on your webserver the 
directory structure corresponds with that on the SVN server. Only 
difference is the extra directory 'other' for 'unsupported' versions, or 
versions that might have to be migrated to the project.

>> Paul Gaborit, aka 'gaborit':

[...]

> In addition to helping in the infrastructure, I will also happily
> participate in the translation and review process of the French
> translation.

Yay! So the project *is* moving.

> I'm stopping here my po4a advertisement.

:o)

Joergen

Re: [perldoc2-developers] Meet the team

[Joergen W. L. <joe...@gm...>]

herbert breunung schrieb:

> hallo gentleman, yes i do speak german (wie die meissten hier :)

"like most subscribers" - hopefully this will change since we need 
people of different languages sooner or later.
This hopefully changes.

> so gentleman lets do some great stuff. i think we will need also some
> russian, spanish and portugise speakin people.

I have written to every translation project but feedback is still 
veeeery slow. I especially hope for the spanish, italian, portuguese 
people to get on board.

Well - we'll see.

Greetings,

Joergen

Re: [perldoc2-developers] General Questions

[Robert 'p. S. <rs...@47...>]

Joergen W. Lang said:

> Sorry for being so unclear. I did not think of including anything like
> BBoard or Forum capabilities directly into the codebase (that's why I
> put them under "additional features" in the specification, maybe
> should've called them "add-ons" or something...).

How about "infrastructure"? :)

> Although I feel that things like a BBoard, forum or whatever means of
> communication are very neccessary features they should not clutter up
> the codebase.

Sure. The question is more which way to take. Personally, I prefer mailin=
g
lists.

>> Guidelines are certainly good. If we want to keep it maintainable we
>> also shouldn't start adding dependencies like there's no tomorrow. So =
we
>> might want to discuss those things separately.
>
> Sorry, not clear. What do you mean by "dependencies" is in this context=
?

CPAN :) The web frameworks manage their own dependencies pretty well. I
mean we should discuss _which_ XML module we use, _which_ database access=
,
and so on. To keep the dependencies as simple and as communicated as
possible. This should ease deployment too.

>> [stability issues]
>>
>> That's rather a deployment and development issue imho. We should
>> certainly do testruns before deploying/updating the main site. Things
>> like PAR could also help us with this, as it captures a whole environm=
ent
>> (optionally even including core modules).
>
> Or one step further - and you have something like apachefriends.org's
> XAMPP project.

Also a possibility. Although I see the "other projects" and "whole
different languages" target groups more fit to this way of distribution.

>>> This might be important if we start developing the platform on SF and
>>> then have to move it to whatever the final destination might be.
>>
>> Well, SF can't run it anyway, can it? It should be possible for
>> developers of the platform to check it out and run it on their own
>> systems. Another neutral systems before regular deployments to the end
>> site would imho be another good idea, too.
>
> Well - there's webspace, there's perl, there's shell access - what else
> do we need? Apart from that I do agree to the point of checking out and
> testing locally.

Question is which perl, what kind of webspace, how much influence on the
perl environment, etc.

> BTW - There's plenty of space on my server... :o)

Which might be a much better fit. Sidenote: Of course I mean the
translation platform itself, not the hosting of the finally translated
files. For that I'd think a sort of export (e.g. into the projects SVN, s=
o
everyone, including the $lang.perldoc.perl.org space can easily stay up t=
o
date) would be a much better fit for that.

gr.,
Robert

--=20
# Robert 'phaylon' Sedlacek
# Perl 5/Catalyst Developer in Hamburg, Germany
{ EMail =3D> ' rs...@47... ', Web =3D> ' http://474.at ' }

Re: [perldoc2-developers] General Questions

[Joergen W. L. <joe...@gm...>]

Robert 'phaylon' Sedlacek schrieb:

> I'll concentrate on the points being separate from the spec then :)

[...]

> I'm not sure if it's a good idea to include a bboard into the codebase, as
> this just adds up work distracting from the real thing[tm]. For example,
> the german perl community has a self written board which is in
> re-development. It surely isn't perfect, but it might be fitting for our
> purposes.

Sorry for being so unclear. I did not think of including anything like 
BBoard or Forum capabilities directly into the codebase (that's why I 
put them under "additional features" in the specification, maybe 
should've called them "add-ons" or something...).

We definitely should focus on the creation of the platform itself.

Although I feel that things like a BBoard, forum or whatever means of 
communication are very neccessary features they should not clutter up 
the codebase.

>> With "resources" I meant things like glossaries that might be available
>> to transalators or other people. Maybe people could have their own
>> glossary or dictionary.
> 
> Now I get it. ++ to that then.

:o) There you go.

>> -T comes to mind. The things you mention above could probably be
>> incorporated in some sort of "coding guideline" for the project. For the
>> moment I do not think, we need this, since the people involved had
>> enough time to learn from their own mistakes already, right? ;o))
> 
> Guidelines are certainly good. If we want to keep it maintainable we also
> shouldn't start adding dependencies like there's no tomorrow. So we might
> want to discuss those things separately.

Sorry, not clear. What do you mean by "dependencies" is in this context?

> [stability issues]
> 
> That's rather a deployment and development issue imho. We should certainly
> do testruns before deploying/updating the main site. Things like PAR could
> also help us with this, as it captures a whole environment (optionally
> even including core modules).

Or one step further - and you have something like apachefriends.org's 
XAMPP project.

>> This might be important if we start developing the platform on SF and
>> then have to move it to whatever the final destination might be.
> 
> Well, SF can't run it anyway, can it? It should be possible for developers
> of the platform to check it out and run it on their own systems. Another
> neutral systems before regular deployments to the end site would imho be
> another good idea, too.

Well - there's webspace, there's perl, there's shell access - what else 
do we need? Apart from that I do agree to the point of checking out and 
testing locally.

BTW - There's plenty of space on my server... :o)

Joergen

Re: [perldoc2-developers] General Questions

[Robert 'p. S. <rs...@47...>]

Joergen W. Lang said:

> [This (not Roberts preceding) post should be mostly obsolete since most
> of it should be answered in the Specification. Anyway - for
> completeness' sake... here we go:]

I'll concentrate on the points being separate from the spec then :)

> I was referring to forums that run on the platform or as part of is. Th=
e
> data accumulated by these forums will probably be stored in one or the
> other DB. This DB should be easily maintainable.

I'm not sure if it's a good idea to include a bboard into the codebase, a=
s
this just adds up work distracting from the real thing[tm]. For example,
the german perl community has a self written board which is in
re-development. It surely isn't perfect, but it might be fitting for our
purposes.

> With "resources" I meant things like glossaries that might be available
> to transalators or other people. Maybe people could have their own
> glossary or dictionary.

Now I get it. ++ to that then.

> -T comes to mind. The things you mention above could probably be
> incorporated in some sort of "coding guideline" for the project. For th=
e
> moment I do not think, we need this, since the people involved had
> enough time to learn from their own mistakes already, right? ;o))

Guidelines are certainly good. If we want to keep it maintainable we also
shouldn't start adding dependencies like there's no tomorrow. So we might
want to discuss those things separately.

>> I can't really remember any stability issues with the current popular
>> Perl
>> web frameworks, anyway.
>
> Do they stay up and running even if one or more required modules fail t=
o
> work (maybe due to an update, API change or whatever)? Especially with
> these huge lists of dependencies this could be an issue. But maybe I'm
> just paranoid.

That's rather a deployment and development issue imho. We should certainl=
y
do testruns before deploying/updating the main site. Things like PAR coul=
d
also help us with this, as it captures a whole environment (optionally
even including core modules).

> This might be important if we start developing the platform on SF and
> then have to move it to whatever the final destination might be.

Well, SF can't run it anyway, can it? It should be possible for developer=
s
of the platform to check it out and run it on their own systems. Another
neutral systems before regular deployments to the end site would imho be
another good idea, too.

gr.,
Robert

--=20
# Robert 'phaylon' Sedlacek
# Perl 5/Catalyst Developer in Hamburg, Germany
{ EMail =3D> ' rs...@47... ', Web =3D> ' http://474.at ' }

Re: [perldoc2-developers] [RFC] Platform Specification Vs. 0.1

[Robert 'p. S. <rs...@47...>]

herbert breunung said:

> #####################
> - interface(s)
> #####################
>
> so we do it as webapp not desktop, that would be fine since im also
> involved in several other projects and a tranlation helper is something
> totally different than the pod viewer i want to build anyway.

Hmm. I'd propose we factor the domain logic out of the webapplication. So
that the webface is only the interface between checkins, checkouts,
merges, stage changes etc. This would allow an easy implementation of
something along WebServices, XMLRPC, REST, etc.

> #####################
> - people
> #####################
>
> so we have admins that create and maintain the platform
> and
>
> translators that can be assigned to a whole language a document or as
> reviewer
> more seems to complex for me

Why is it too complex? And what parts exactly? I'd rather think it
shouldn't be too simple, as we have different target audiences and
shouldn't build up barriers.

> even if it should be
> for *ANYONE*
> should be as easy as possible to make comments on any translated passag=
e,
> that can be
> considered later by the assigned translators.

That's for some reason an obviously good idea. The commenting possibility
I mean. As said, I'd differentiate between comments and errata (the latte=
r
being kind of advanced comments). I thought about a ticketized system
because of the history effect and the minimization of duplicate efforts.

> #####################
> Multiple formats
> #####################
>
> we are perl hacker with CPAn on our side so converter tools should be
> least problem.

Full Ack. All the codebase are belong to us. :)

> #####################
> Meta information
> #####################
>
> thats no enough, take me for instace, es i wrote my czech is sophistica=
ted
> but containes
> some terrible orthographical flaws (some people here claim that is also
> true for my german *g* ). such infos i like to atach on a doc that an
> revisor don't have to search for flaws i know there are at certain word=
s
> or word group.
> so only mark a block or whole sentences as fuzzy would'nt do it IMO.

Yea, but it seems easier for translators to reject complete blocks or
paragraphs, but _with comments and reasoning_. As sometimes it's not just
a fuzzy word, but it's context, the sentence around it, and other things
which might be reconsidered to make it more fitting.

> in much i agree with robert

Always a good thing! *scnr* ;)

gr.,
Robert

--=20
# Robert 'phaylon' Sedlacek
# Perl 5/Catalyst Developer in Hamburg, Germany
{ EMail =3D> ' rs...@47... ', Web =3D> ' http://474.at ' }

Re: [perldoc2-developers] General Questions

[Joergen W. L. <joe...@gm...>]

[This (not Roberts preceding) post should be mostly obsolete since most 
of it should be answered in the Specification. Anyway - for 
completeness' sake... here we go:]

Robert 'phaylon' Sedlacek schrieb:

>>> * Service or Application?

>> The initial idea was to have a platform dedicated mainly (but not
>> exclusively) to the perl community. So to prepare the project for future
>> growth and extensibility it is probably the wiser choice to go more for
>> the "application" way of things.

> Well, I actually had only the perl community in mind at first, as most of
> them will have documentation in POD format.

It should be clear by now, that other document formats should be not a 
big problem, thanks to po4a (Nicolas' posting) and CPAN (Herbert's posting).

> It all depends on what we "want to do." Personally, I'd ++ a database
> approach with a, for example, shipped DBIC model that's ready to use. This
> would allow 3rd parties to develop tools which can flow back to the
> project.
> 
> What approach or schema to take depends on the data structure. What atoms
> are there for checkout/editing/comparing/merging/etc? What workflows have
> to be there, which states have to be kept?

see Spec and the following discussion.

>> - extensibility
>>    (add natural and programming languages, subprojects...)
> 
> What do you mean by "subprojects"? Most Perl Frameworks will provide
> support for Unicode and I18N/L10N. And if we focus on po4a as input
> format, we have a common middle ground that can be targetted by other
> documentation projects/formats.

The translation of the "core documentation" is a "subproject" of the 
translation of the Perl documentation, for example. See Spec for details.

>> - maintainability
>>    (database, forums, resources)
> 
> Catalyst itself is database-agnostic. Personally I'd favor DBIC, as it is
> pretty expressive, powerful, and has a very active community. I'm not so
> sure what you mean with forums and resources. Does CPAN count for the
> latter?

I was referring to forums that run on the platform or as part of is. The 
data accumulated by these forums will probably be stored in one or the 
other DB. This DB should be easily maintainable.

With "resources" I meant things like glossaries that might be available 
to transalators or other people. Maybe people could have their own 
glossary or dictionary.

CPAN is a resource but none that is maintained by this project so it 
probably does not count in this context.

>> - security
>>    (the more people use it, the bigger the chance that someone
>>    breaks it accidentally)
> 
> Well, if we don't eval, check all incoming user data, use database access
> based somehow on DBI and it's binding mechanisms, we should be on a save
> side. Fortunately, we have no register_globals :)

-T comes to mind. The things you mention above could probably be 
incorporated in some sort of "coding guideline" for the project. For the 
moment I do not think, we need this, since the people involved had 
enough time to learn from their own mistakes already, right? ;o))

>> - stableness
>>    (same as above)
> 
> I can't really remember any stability issues with the current popular Perl
> web frameworks, anyway.

Do they stay up and running even if one or more required modules fail to 
work (maybe due to an update, API change or whatever)? Especially with 
these huge lists of dependencies this could be an issue. But maybe I'm 
just paranoid.

>> - simpleness
>>    (both in structure as in useability)
> 
> Good point. I'd like to add deployability, where Catalyst itself has pro's
> and con's. The con part is it's huge list of dependencies, but that can
> (in a ready application) be shipped with, either in a distribution or in a
> PAR file, which should be able to capture the whole perl deployment
> environment.

This might be important if we start developing the platform on SF and 
then have to move it to whatever the final destination might be.

> Another pro is the possibility of deployment on many engines. mod_perl,
> FastCGI, SpeedyCGI, pperl.

Agreed.

Joergen

Re: [perldoc2-developers] [RFC] Platform Specification Vs. 0.1

[herbert b. <dei...@we...>]

allright, here my cents

#####################
- interface(s)
#####################

so we do it as webapp not desktop, that would be fine since im also involved in several other projects and a tranlation helper is something totally different than the pod viewer i want to build anyway.

#####################
- people
#####################

so we have admins that create and maintain the platform
and 

translators that can be assigned to a whole language a document or as reviewer
more seems to complex for me

sidenote: please don't compare our reviews with wikipedias peer review because wp is
a hack of a mess. sometimes it works well but that depends on subject, weather, 
astrological circumstances and other darker forces, because there is nearly everything 
open. i like to have here a more restricted culture, even if it should be for *ANYONE*
should be as easy as possible to make comments on any translated passage, that can be
considered later by the assigned translators.


#####################
Multiple formats
#####################

we are perl hacker with CPAn on our side so converter tools should be least problem.

#####################
Meta information
#####################

thats no enough, take me for instace, es i wrote my czech is sophisticated but containes
some terrible orthographical flaws (some people here claim that is also true for my german *g* ). such infos i like to atach on a doc that an revisor don't have to search for flaws i know there are at certain words or word group. 
so only mark a block or whole sentences as fuzzy would'nt do it IMO.

in much i agree with robert

so far

herbert

Re: [perldoc2-developers] [RFC] Platform Specification Vs. 0.1

[Robert 'p. S. <rs...@47...>]

Hi Joergen and everyone else listening;

Joergen W. Lang said:
> The first version of the specification for the platform is ready for
> your perusal.
>
> Please comment, add, edit, ask ... after all these are just a few
> thoughts out of my own twisted brain.

Thanks for the effort and the (convenient, for us) explicit specification=
.
Here are my first thoughts. It might get a bit hard to keep all the ideas
and decisions in memory. So I thought, maybe we should set up a wiki or
something along that for this process?

Anyway, here's my braindump:

---

As I have a rather lenghty answer of comments, I'll skip the line
numbers and refer to the sections instead. I will also keep it rather
short, as squirremail dropped my previous mail. I hereby officially
curse PHP once more.

** Section "Goals":

> The final goal is to provide complete translations of
>
> - the core documentation(1)
> - the documentation of the core modules(2)

As I understand it, we actually want to be "P6-proof," and able to
easily make this facility available to other projects or even
programming languages. I first thought this might be premature
optimization. But this more affects the categorization and meta
data of the projects themselves, rather than the actual translation
process. So I think it might be worth trying to make the application
aware of metadata in an abstract sense, and not "Perl version numbers"
themselves for example.

** Section "Multilingual"

> Since this is a translation platform, the contents and interfaces of th=
e
> website should be available in as many natural languages as possible.

We might even start a translation project for it! (just a joke)

Seriously though, I18N shouldn't be a problem, independent of the used
web framework.

** Section "Framework"

> We should not reinvent the wheel. There already is a good choice of web
> application frameworks out there. Choosing one written in Perl might
> help us - and Perl at the same time. ;o)

Full Ack. I'd still be happy to hear from other members what their
favorite web development platforms are and why.

** Section "Adoption"

> The 'adoption' method could be an essential part of the project. By
> assigning a complete document to one physical person, this person is
> encouraged to make the translation a personal effort instead of feeling
> like an anonymous gear within the big translation machine.

I'd also like to propose the role of a "language adopter," who can overse=
e
an entire language. The document adopters are document and language speci=
fic,
as I understand them.

** Section "COMPONENTS - repository"

> For the moment we use an SVN repository on sourceforge to collect and
> store the documents to be translated and the already existing
> translations. This might change during the developement of the project
> as it might be more practical to store the documents within the databas=
e.

++ for the database on my side. It makes enhancements, keeping track and
metadata much easier than trying to set that up above another layer.

** Section "COMPONENTS - interface(s)"

> The platform might have several different interfaces. One for
> translators, one for end users and for administrators.

I'd think two (web) interfaces might be enough. One for project members a=
nd
one for project users. As the administrator privileges could be integrate=
d
in the general translation interface.

> - submit errata
> - give general feedback

I'd propose the terms "comment" and "errata" for submissions. These could
also be accepted from non-registered users (but with Captcha for spam
prevention, of course). Furthermore, I think it might be a good idea to
design these in form of a small trouble-ticket system. Where these states
would be possible:

comments:
- unread
- acknowledged (with response)

errata:
- new
- rejected (with reason)
- acknowledged (or open)
- closed (with comment)

A public viewable list of comments/errata per document and per language
would also help to prevent to duplicate issues.

** Section "COMPONENTS - people"

> Sometimes decisions have to be made wether a certain word should be
> translated one way or the other or not a all. This might need one or
> more 'referees' of some kind.

I'd much rather prefer language-specific mailing-lists. This would also
provide a public viewable archive of reasonings behind certain things,
and a place for "outsiders" to address larger issues, which wouldn't fit
into "comments" or "errata" submissions.

** Section "Additional Features"

> - RSS feeds for
> -- statistics
> -- news
> -- ?

-- documents with newly translated parts
-- documents with newly approved parts
-- documents with newly abandoned parts
-- comments/errata

The first three could be shown in a changeset style of view.

> - IRC-Channel?

Of course! It has more than one advantage: It eases development of the
platform, it provides a direct source for help and to drop comments, it
is a nice meeting point and it generally keeps the involved parties
close together.

- Mailing lists

As stated above, I'd recommend per language lists additional to the
regular ones.

** Section "Workflow"

I would like to address a general issue here: There won't be core
project attendees for every language. This means that specific issues
in other languages can only be handled if there are "trusted" members
of the translation move. I therefore would propose a slightly more
complex hierarchy of roles and privileges:

- Administrators (should be clear)

- Language Adopters (Can "administrate" one language. These are the
  primary contacts for language global issues. Can influence all
  documents of one language)
- Document Adopters (Should be per language. Can influence one document
  in a specific language)

- Core Translators (Can check-out, check-in, etc. These are the "trusted"
  translators in the project. Can approve translations.)
- Wingman/Reviewer (A Core Translator assigned to another one for the
  purpose of QA.)
- Translators (Cannot approve. Can only checkout a limited number of
  document "parts". Can be promoted to Core Translators if found
  trustworthy enough. Maybe it should take one core translator to
  check-in changes, and a second one to approve to ensure quality.)

The Administrators would be the only language-independent roles. An
adopter role can only be carried by a core translator.

We might also want to allow the end-users to create accounts. So they
can keep public/private notes, store bookmarks etc.)

** Section "DETAILS - Database"

> What else?

I would suggest to wait with details about the database schema until we
agreed on what has to go inside and what structure we need.

** Section "DETAILS - Status of document"

> A document, stored in an SVN repository, a database or whereever, has a
> certain status attached to it.

I'd rather attach states to the parts of a document, rather than the whol=
e
document itself. By this we can dynamically accumulate states of document=
s
and languages.

Though we'd need different states or state indicators for documents and
document parts then. How about something along these:

Document states:
- vacant
- adopted

Document part states:
- not translated
- in translation
- translated but not approved
- translated and approved (read: finished)

I'd say it should be possible for a translator to check out specific part=
s
of a document (say, parts 15 to 23). These would then be in the "in
translation" state. The limit of parts to check out should be influenced
by the role (core translator or just translator) of the user. As you
stated, after a specified time, depending on the number of checked out
parts, this state should be revoked. The claimed parts would be "not
translated" again. The revocation counter should be reset on any activity
in the checked out parts, so we would need to regard a checkout as an
entity by itself.

Of course, if a translator has problems with a specific part, it should b=
e
possible for him to "drop" the part back to "not translated" but keep the
others checked out.

** Section "DETAILS - Meta information"

> - (Perl) version the document is based upon.

Wouldn't it be more open-ended if we'd make the projects hierarchical?
So there wouldn't be an explicit need for perl version number metadata.

E.g.

- Perl 5
  - Version 5.6
    - Core Documentation
    - Core Module Documentation
  - Version 5.8
    - Core Documentation
    - Core Module Documentation
- Perl 6
  ...

** Section "DETAILS - User registration"

> For reasons of security and consistency it is probably neccessary for
> users to register with the project as a translator/reviewer/... (aha -
> we already have different roles!)

Of course!

** Section "DETAILS - Checkout"

> A registered user will be able to assign one (or more?) documents to
> himself. This person will be the "adopter" for this document for a
> certain amount of time (the "time to live", "TTL", see "Abandoned
> documents").

I wouldn't let the adopters expire, but rather make the adoption of
something an administrative/overseeing role. I'd actually propose a
primary and a secondary adopter per document and language. The secondary
one could be chosen by the primary adopter himself, in case he's not
available. For reasons of vacation, or too much work, for example.

** Section "DETAILS - Review"

> A concept of peer review similar to that of wikipedia could be used.
> Other users are encouraged to review and to correct. Maybe this could
> follow the "buddy principle" as practiced with divers.

I agree with the "buddy" idea, except that I find the term "wingman" way
cooler. This might be a personal preference though ;)

> To review a document the 'buddy' needs to checkout the document and
> actually read it.  By re-submitting it the document will be marked as
> 'finished'.

If we introduce per-document-part states, the reviewing process might
even go along with the translation of certain parts of the document.
When the translator stores a part of his checkout as "finished," his
wingman would get it on his todo list for review. He can then either
approve the translation, or reject it (with a reason). The latter drops
it onto the translators todo list for his checkout again.

** Section "DETAILS - Check-in"

> The check-in or 'submit' of translated documents could be acchieved in
> one of the following ways:
>
> - Upload via HTML-Form
> - email (to a special address handling the integration of the document
>   into the database).

Well, I'd see some possibilities to check-out/check-in the document parts=
.
A first separation would be "online" or "offline." So I'd propose to keep
the checkout state canonically online, and allow status updates by checki=
ng
in offline edited documents.

Online translation would probably be a web interface. A saving of a
document part there would also be a request for review.

Offline editing would need some specified formats for export, which shoul=
d
be able to carry metadata. These would come to mind:

* XML

The metadata would be no problem. They could be edited directly, or with
an editor. Maybe Herbert can write us something fancy for this in Wx ;) A
client application could also check-out the todo-list of claimed items
via a webservice.

* POD

Of course I don't mean the original POD, but something specified. For
example:

  =3Dhead1 Translation Todo List

  $some_generic_information

  =3Dhead2 ORIGINAL[$metadata]

  $original_text

  =3Dhead2 TRANSLATION[$metadata]

  =3Dbegin TRANSLATION PLACEHOLDER (please erase when translation finishe=
d)

  $original_text

  =3Dend

  =3Dhead2 ORIGINAL[$metadata]

  ...

* po4a

I don't really know po4a's metadata capabilities, so I can't comment on
this.

The metadata in the formats allows for an easy synchronization. The check=
ed
out document would contain the parts the translator has on it's translati=
on
todo-list. He can start translating them and occasionally check the
document back in. Through placeholders like "TRANSLATION PLACEHOLDER"
above, the system can just extract the finished parts and send it to the
wingman for review. It can also insert those parts the wingman has alread=
y
rejected, with his reasonings in "=3Dbegin REJECTION REASON" blocks.

This would allow for offline editing and occasional synchronisation with
the online application to stay up to date.

---

So, please let me know what you think of these points.

gr.,
Robert

--=20
# Robert 'phaylon' Sedlacek
# Perl 5/Catalyst Developer in Hamburg, Germany
{ EMail =3D> ' rs...@47... ', Web =3D> ' http://474.at ' }

[perldoc2-developers] [RFC] Platform Specification Vs. 0.1

[Joergen W. L. <joe...@gm...>]

Hi everybody,

yes - it took a little longer than expected - but here it is:

*ta-da!*

The first version of the specification for the platform is ready for 
your perusal.

Please comment, add, edit, ask ... after all these are just a few 
thoughts out of my own twisted brain.

Imagine what six twisted brains could make it!

Hope you like it.

Joergen

P.S.: I will also upload it to the blog tonight.

below is line number one :o)
########################################################################
perldoc 2.0 Platform specification
########################################################################

Version:    0.1
Date:       November 14-16, 2006
Author:     Jørgen W. Lang
Email:      jw...@wo...

########################################################################
NOTE
########################################################################

Since this is the first version of the specification there probably are 
a lot of things that should be added, changed, improved, clarified, etc.

When referring to a particular part of this document, please try to also 
quote the line number. This way everybody should be able to easily 
identify the part you are talking about.

Thanks!

########################################################################
ABSTRACT
########################################################################

This document describes the components of the perldoc 2.0 translation 
platform and repository and the workflow between its parts.

########################################################################
GENERAL CONCEPTS
########################################################################

########################################################################
- Goals
########################################################################

The final goal is to provide complete translations of

- the core documentation(1)
- the documentation of the core modules(2)

Once finished the translations could be made available via 
language-specific subomains of perldoc.perl.org, like 
'fr.perldoc.perl.org' and as part of the actual perl distribution e.g. 
in the ./pod/ directory.

In the meantime translated documents could and should be available via 
the platform website. This way they can be used and reviewed as soon as 
single documents are finished.

The main focus of the platform is aimed at the translation of the 
documentation for the programming language Perl into other natural 
languages. Since Perl6 is already in the making, the platform should be 
ready for this.

Although it is neither the primary goal nor a prerequisite, the platform 
might support the translation of documentation for other 
projects/programming languages in the future.

(1) and (2) are explained under "Terms"

########################################################################
- Audience
########################################################################

- translators (translating the docs)
- end-users   (looking up documentation in their languages)
- developers  (who can help improving the platform)

The term 'end-users' is utilized to differentiate between developers, 
(P|p)erl hackers, etc. reading the documentation and those actively 
involved in the creation, mainteneance and improvement of the platform 
itself (althought these sometimes will be the same people).

########################################################################
- Multilingual
########################################################################

Since this is a translation platform, the contents and interfaces of the 
website should be available in as many natural languages as possible.

########################################################################
- Framework
########################################################################

We should not reinvent the wheel. There already is a good choice of web 
application frameworks out there. Choosing one written in Perl might 
help us - and Perl at the same time. ;o)

########################################################################
- Adoption
########################################################################

The 'adoption' method could be an essential part of the project. By 
assigning a complete document to one physical person, this person is 
encouraged to make the translation a personal effort instead of feeling 
like an anonymous gear within the big translation machine.

This method does not exclude the possibility for splitting up one 
document between multiple individuals. Maybe the platform should have 
support for this. Using po4a might help a lot.

########################################################################
- Quality
########################################################################

To ensure the best possible quality of translations a certain set of 
guidelines should be followed. A common glossary of terms should be used 
for each language.

########################################################################
COMPONENTS
########################################################################

The following key components are needed:

########################################################################
- repository
########################################################################

The repository is the storage area for documents to be translated. This 
could be a SVN repository, a database, a directory structure or whatever.

For the moment we use an SVN repository on sourceforge to collect and 
store the documents to be translated and the already existing 
translations. This might change during the developement of the project 
as it might be more practical to store the documents within the database.

########################################################################
- database
########################################################################

The database is used to store information about the documents to be 
translated like the perl version they are based on, their translation 
status, timestamps, and other meta information.

The database will also keep track of 'available' languages. This could 
mean a general table of languages that are spoken on the planet today.

(It could also be used to store the documents themselves.)

########################################################################
- interface(s)
########################################################################

The platform might have several different interfaces. One for 
translators, one for end users and for administrators.

The primary interface is web-based. Access to documents and information 
about them will be done via a website.

The interface(s) provides the following key features:

- create and manage user accounts
- login/logout
- overview of documents available for translation
- translation status of these documents
   (see 'document specific status' for details)
- check-out of 'vacant' documents
- check-in of translated documents
   (marks document as 'pending')
- show various forms of statistics about translation status,
   available documents

- check-out for review of translated documents
- checking in after review to mark documents as 'finished'

- submit errata
- give general feedback

- maintain database/repository

The platform could also provide secondary interfaces in the form of web 
services, maybe for the communication with an editor program installed 
on the local machine of a translator.

########################################################################
- people
########################################################################

Although msot of the processing is probably done more or less 
automatically there are certain parts of the workflow that involves 
review and steering be 'real people'.

The obvious is the actual translation itself. Additionally some 
editorial staff might be needed to review and correct the translation.

Sometimes decisions have to be made wether a certain word should be 
translated one way or the other or not a all. This might need one or 
more 'referees' of some kind.

It also takes real people to review feedback and submitted errata.

To support the interaction between people forums and other means of 
communication should be available. After all, the whole platform is 
powered by mutual help.

########################################################################
Design
########################################################################

Usage of the platform should be

- simple
- fun
- cool

########################################################################
Additional features
########################################################################

Tools/Helpers/Guidelines

- lists of available translation tools
   - like editors with .po mode
   - download links
   - scripts and programs to ease translator's lives

RSS

- RSS feeds for
-- statistics
-- news
-- ?

Resources

- glossaries
- dictionaries

Mutual help

- Forums
- IRC-Channel?
- Mailing lists

Multilevel adoptions

- one key person is the adopter for one document
- the document could then be shared among multiple
   translators who take care of various parts of the
   doc.

Multiple formats

- RSS
- PDF
- XHTML
- POD
- ...

Download the whole documentation for one language as one 'book'.

Sponsorships

- A possibility for individuals or companies to sponsor the translation
   of one or more particular document. These documents could have a
   special marker to them that identifies the sponsor to the reader.

########################################################################
Workflow
########################################################################

 From the translators point of view:

- (register/create account)
- check for available ('vacant') documents/languages
- login
- pick a document to adopt
- check-out the document (marks the document as 'adopted')
- translate the document
- check-in the document (marks the document as 'updated')
- get the document reviewed

 From a reviewer's point of view:

- (register/create account)
- check for 'updated' documents
- login
- pick a document to review
- check-out the document
- review the document (remove 'fuzzy' markers)
- check-in the document (no fuzzy markers mark it as 'finished')

 From a user's point of view:

- check for documents/languages
- read the document in maybe one of several available formats
- leave feedback/errata

########################################################################
DETAILS
########################################################################

########################################################################
- Database
########################################################################

The database stores the following information:

- translation projects and their status
   (as we expect at least one more project in the future)

- registered translators
   (and some details about them)

For a project:

- list of 'supported' documents
   (plus the neccessary details)

- maybe the documents themselves
- which languages the document was or is being translated to

For a document:

- status
- meta information

What else?

Furthermore, this or another database will very likely contain 
everything that's needed to run the web application itself.

########################################################################
- Status of project
########################################################################

Meta information like maintainer, contained subprojects, statistical 
information, etc.

For the translation or the Perl5 documentation two subprojects are the 
translation of the core documents and the translation of the core modules.

The translation of the core documents could be further split by 
'importance' of translation.

########################################################################
- Status of document
########################################################################

A document, stored in an SVN repository, a database or whereever, has a 
certain status attached to it. Depending on its state of translation 
this could be one of the following:

vacant|adopted|pending|finished|abandoned

vacant:       the document has not yet been assigned to a translator
adopted:      the document has been assigned to a translator
updated:      a partially translated document
pending:      the initial translation of the document has been finished
               but the document has not yet been reviewed.
finished:     the docuement has been translated and reviewd
abandoned:    documents that have been adopted but haven't been worked
               upon for a given time will be marked as 'abandoned' before
               they will be put back into 'vacant' mode. This mode is
               to give the translator time to change the document's
               status to 'updated'.

               The translator will have to be informed by this. If she
               does not update the document within a given time the
               status will change back to 'vacant' automatically.

########################################################################
- Meta information
########################################################################

For a document certain meta information will be stored:

- project this document is part of
- (Perl) version the document is based upon.
- time of adoption
- time of update
- name of adopter
- document is already translated partially
   (implied by 'updated' flag)

########################################################################
- User registration
########################################################################

For reasons of security and consistency it is probably neccessary for 
users to register with the project as a translator/reviewer/... (aha - 
we already have different roles!)

########################################################################
- Check-out
########################################################################

A registered user will be able to assign one (or more?) documents to 
himself. This person will be the "adopter" for this document for a 
certain amount of time (the "time to live", "TTL", see "Abandoned 
documents").

########################################################################
- Review
########################################################################

Probably the only way to good  quality and correctness of the 
translations (orthography, speling, language and content) is mutual 
help, unless Mark Shuttleworth wants to sponsor this project.

A concept of peer review similar to that of wikipedia could be used. 
Other users are encouraged to review and to correct. Maybe this could 
follow the "buddy principle" as practiced with divers.

To mark a document as 'finished' it has to be reviewed by at least one 
person not being the translator itself. Maybe the review should involve 
marking the several parts of the translation as 'reviewed' (maybe using 
the 'fuzzy' flag?)

To review a document the 'buddy' needs to checkout the document and 
actually read it.  By re-submitting it the document will be marked as 
'finished'.

Using the 'fuzzy' marker avoids having to review the whole document 
which can be a great help, especially with lengthy and complex 
documents. This implies that the fuzzy marker is set by default.

########################################################################
- Abandoned documents
########################################################################

Sometimes people adopt a document but do not have the 
time/motivation/resources to update it. To ensure that these documents 
do not become "zombies" they will have a certain 'time to live' based on 
their length and (maybe) complexity (perlopentut is more complex than 
perl588delta, etc.)

If an adopted document exceeds its time to live (TTL) the following 
could happen:

- the adopter will be informed that the document has not been updated
   within the given TTL. She will then be given a certain time to react.

- In this first stage it should not be neccessary to submit actual
   changes to the document but to merely 'touch' the document. This is to
   confirm that the translator is still willing to work on the document.
   This will re-initialize the time to live. Maybe with a flag that
   indicates that this document has one 'reminder' to it.

- The second stage might require an actual update of the document. TTL
   keeps running, does not get reset.

- If the TTL has been exceeded with no reaction on the translator's
   side the document will be marked as 'vacant' again.

- If a partially translated document was abandoned this needs to be
   marked in meta information


########################################################################
- Check-in
########################################################################

The check-in or 'submit' of translated documents could be acchieved in 
one of the following ways:

- Upload via HTML-Form
- email (to a special address handling the integration of the document
   into the database).

Using the database approach would enable us to allow check-ins of 
partially translated documents.

########################################################################
- Terms
########################################################################

This document uses the following terms as follows:

- adoption

The process of assigning a document to a particular person.

- project

The translation of the perl documentation (perldoc 2.0) is a project. 
The translation of the documentation for Catalyst is another.

- subproject

The translation of the core documentation is a subproject of perldoc 
2.0. The translation of the documentation for the core modules is another.

- core documentation (of perl)

A typical installation of perl from source creates the directory 
'perl-[version_number]'. Contained in this is a directory named 'pod'. 
All documents contained in this directory and ending in '.pod' are part 
of the core documentation.

- core modules

Modules that are installed with a typical perl installation from source 
by default.

########################################################################

Re: [perldoc2-developers] General Questions

[Robert 'p. S. <rs...@47...>]

Hello Joergen, 'evening .*

Joergen W. Lang said:
> Robert 'phaylon' Sedlacek schrieb:
>
>> * Service or Application?
>
> The initial idea was to have a platform dedicated mainly (but not
> exclusively) to the perl community. So to prepare the project for futur=
e
> growth and extensibility it is probably the wiser choice to go more for
> the "application" way of things.
>
> I think, generally it is a good idea to be as open to other projects as
> possible. On the other hand, there is Rosetta
> (https://launchpad.net/rosetta) which aims at more or less the same
> goals (and also uses gettext/.po). It already has a huge user/translato=
r
> base plus *very* solid funding. Rosetta is part of the Ubuntu project.
>
> The major difference between Rosetta and our project is our focus on
> documentation rather than dialogues, program messages, etc.
>
> Having said this, I guess that Rosetta can still be a good source of
> inspiration. Analyzing their approach is another piece of work I will
> have to do...

Well, I actually had only the perl community in mind at first, as most of
them will have documentation in POD format.

> Interestingly enough we actually have a working platform already: the
> SVN repository on sourceforge. It is just not really useable by 'end
> users', aka translators.
>
> Frank Seitz of Hamburg.pm suggested a while ago a database driven
> approach. That might be more maintainable/extensible than the SVN-based
> approach.
>
> Any SQL experts around?

It all depends on what we "want to do." Personally, I'd ++ a database
approach with a, for example, shipped DBIC model that's ready to use. Thi=
s
would allow 3rd parties to develop tools which can flow back to the
project.

What approach or schema to take depends on the data structure. What atoms
are there for checkout/editing/comparing/merging/etc? What workflows have
to be there, which states have to be kept?

> As the platform (or - at least the 'interface') will be mostly web-base=
d
> this is going to be a key decision. I think the choice should be based
> on the following:

As I'm really only familiar with Catalyst, I'll focus my answers in this
part on it.

> - extensibility
>    (add natural and programming languages, subprojects...)

What do you mean by "subprojects"? Most Perl Frameworks will provide
support for Unicode and I18N/L10N. And if we focus on po4a as input
format, we have a common middle ground that can be targetted by other
documentation projects/formats.

> - maintainability
>    (database, forums, resources)

Catalyst itself is database-agnostic. Personally I'd favor DBIC, as it is
pretty expressive, powerful, and has a very active community. I'm not so
sure what you mean with forums and resources. Does CPAN count for the
latter?

> - security
>    (the more people use it, the bigger the chance that someone
>    breaks it accidentally)

Well, if we don't eval, check all incoming user data, use database access
based somehow on DBI and it's binding mechanisms, we should be on a save
side. Fortunately, we have no register_globals :)

> - stableness
>    (same as above)

I can't really remember any stability issues with the current popular Per=
l
web frameworks, anyway.

> - simpleness
>    (both in structure as in useability)

Good point. I'd like to add deployability, where Catalyst itself has pro'=
s
and con's. The con part is it's huge list of dependencies, but that can
(in a ready application) be shipped with, either in a distribution or in =
a
PAR file, which should be able to capture the whole perl deployment
environment.

Another pro is the possibility of deployment on many engines. mod_perl,
FastCGI, SpeedyCGI, pperl.


Thanks for the answers!
gr.,
Robert

--=20
# Robert 'phaylon' Sedlacek
# Perl 5/Catalyst Developer in Hamburg, Germany
{ EMail =3D> ' rs...@47... ', Web =3D> ' http://474.at ' }