It's not clear how to use this plugin

Hi,

it is not clear how to use this plugin. Documentation is scarce, incomplete and involves many hand wavings, there are no automated tests, and there isn't a complete example. Please remedy it.

Furthermore, why is this program licensed under the AGPLv3? What are the implications of this licence for writing content that is later uploaded to the site as it is? What about the code? Just for the record, the licence of jekyll is MIT/X11L (a permissive licence) so it looks like you are not playing fair.

Regards,

— Shlomi Fish

Documentation is scarce, incomplete and involves many hand wavings, there are no automated tests, and there isn't a complete example. Please remedy it.

where exactly do you see "hand waving"? besides, you're free to provide patches.

What are the implications of this licence for writing content that is later uploaded to the site as it is? What about the code?

i'm sure you'll find your questions answered here.

Just for the record, the licence of jekyll is MIT/X11L (a permissive licence) so it looks like you are not playing fair.

sorry you feel that way. but i hope you can understand that i won't change the license just because you don't like it.

finally, a word of advice: your comment comes off as pretty hostile. this plugin has been extracted from an in-house application in the hopes that it might be useful to others (which it is). but we certainly don't owe anyone anything. we used the license that fit our purposes and provided some basic documentation to help others get started. if either of that doesn't suit you and you're not willing to help improve it, then just don't use this plugin. it's as simple as that.

cheers jens

Hello @blackwinter,

I apologise for the tone of my original bug report. Let me respond to your questions.

Documentation is scarce, incomplete and involves many hand wavings, there are no automated tests, and there isn't a complete example. Please remedy it.
where exactly do you see "hand waving"? besides, you're free to provide patches.

What I meant to say was that while I could get up to speed with Jekyll pretty quickly, I was unable to understand how to use this plugin. I am not a big expert in Ruby and the halo technologies and tend to be a bottom-up learner who is often too lazy or impatient to wade through large amounts of documentation prose. If you can provide a complete example for a site that uses this plugin (possibly as a test), this would be great.

Regarding “you're free to provide patches.”, I really hate the “Patches or STFU!” attitude because a good developer recognises that a bug report often (usually?) indicates a lack of the program as it stands. As Joel on Software notes in “Seven steps to remarkable customer service” one should both help the original requester for help and permanently fix the underlying problem to prevent such future requests which only waste time.

So for example, I have recently looked into ways to incorporate a web-based version of my Freecell Solver project, which is written in C (gnu99), into its site, because some people sent me some deals and asked me to run them on my solver, and I'd like to prevent me wasting time on handling such requests. In the process, I found emscripten which is an LLVM→JS compiler, and ran into a bug with it and reported it. However, its maintainer had some problems using the test case based on my instructions and so I added some extra logic into the build system to prevent such problems in the future. Eventually, the bug in emscripten was fixed and the JavaScript version of Freecell Solver now appears to run fine, but Freecell Solver benefited in other ways from this.

Back to the jekyll-localization issue, I wouldn't mind contributing an example site (possibly as a test suite), but I think I lack the necessary skills to do it - I don't understand how to implement the changes that the documentation says in the relevant site, or else I would not have filed this bug. I also don't fully understand the code. (By the way that site, which I prototyped in jekyll in order to play with it and see how I like it, is fully under CC-by for media and MIT/X11L for code, so you're not just helping me - you're helping the community in large.)

You said that you just extracted this code for an in-house project in hope it will be of use to some people. Well, making a project public and open source also involves a lot of work in the future of maintaining it, enhancing it, documenting it properly, adding tests and self-contained examples, etc. Otherwise, you are free to keep it in-house, where it will require much less discipline to maintain and document, and FOSS licences (including the GPL) allow you to use programs under which they are licensed, and even modify them, for in-house use, without the need to release your code. I refer you to another excellent article by Joel on Software - Five Worlds where he compares and contrasts in-house software to the so-called “shrinkwrap software” (which includes both proprietary and commercial software, open source software, and everything in between, including freeware and shareware), and to three other "worlds" of software.

My work on various open source software I originated and/or contributed to (most of it probably not very popular, but on some projects I received a lot of feedback from users) made me realise and appreciate the amount of discipline required by this “shrinkwrap software” and how just keeping a piece of code lying on my hard disk (or in an obscure version control repository that no one knows about) is much more effortless than maintaining it as marketplace software. So welcome to the real world.

Regarding the GPL FAQ, the AGPL, etc., I suppose I can try using jekyll-localization and hope you don't interpret it as in as a Draconic manner as either nmap whose interpretation of the GPLv2, I find as standing against the FSF's Free Software Definition, or as MySQL, who claim the GPL applies to any independent and clean-room implementation of the protocol, because the protocol itself is copyrighted under the GPL. I am not a lawyer, so I can only hope you won't sue me for maintaining a multi-lingual site under CC-by for media and MIT/X11 for code, while possibly using other jekyll plugins (and related Ruby gems) under different licences, and that I will not have to make my code or markup AGPL or GPLv3 too. I have given explained how I interpret the licences on my site here and suggest you follow suit, because the GPLv3/AGPLv3 can be pretty vague (as many legal documents go) and there are many grey areas.

I'm again sorry for the harsh tone of my original request - I may have been in a bad mood and I hope you can now see the value in my suggestions (which I admit were not phrased too constructively). I should note that no one in #jekyll on Freenode could help me with jekyll-localization either.

If you can provide a complete example for a site that uses this plugin (possibly as a test), this would be great.

you can see the plugin used here. it's a pretty big site, though, so a simpler example would probably be more suitable. i'll see if we can get around to providing one.

Regarding “you're free to provide patches.”, I really hate the “Patches or STFU!” attitude because a good developer recognises that a bug report often (usually?) indicates a lack of the program as it stands.

i'm familiar with joel's writings and enjoy them very much. however, this doesn't mean i have to follow his advice by the letter. when releasing code, i certainly do take on responsibility for it. which means i respond to issues brought up and usually even try to improve upon the situation one way or another. but in no way am i obliged to do so. and neither do i expect others to. it's give-and-take all the way down. and everyone's entitled to making their own decisions about it.

I don't understand how to implement the changes that the documentation says in the relevant site, or else I would not have filed this bug.

well, why don't we talk about what you're actually trying to accomplish then? can you point me at your code? maybe we can find out where the documentation is lacking in the process.

I have given explained how I interpret the licences on my site here and suggest you follow suit, because the GPLv3/AGPLv3 can be pretty vague (as many legal documents go) and there are many grey areas.

let me be clear on this: the license is not going to change. i'm a strong proponent of copyleft so you have to put up with that if you want to use my code. but there's really no need to worry about getting sued for using this plugin to generate your website.

Hi @blackwinter ,

you can see the plugin used here. it's a pretty big site, though, so a simpler example would probably be more suitable. i'll see if we can get around to providing one.

I didn't see a link to the site anywhere on the README. Now that I saw it, I cannot immediately tell how to localize while keeping the translations in sync - there seems to be two versions for each page and they are often out of sync with one another. There should really be a simpler example.

i'm familiar with joel's writings and enjoy them very much. however, this doesn't mean i have to follow his advice by the letter. when releasing code, i certainly do take on responsibility for it. which means i respond to issues brought up and usually even try to improve upon the situation one way or another. but in no way am i obliged to do so. and neither do i expect others to. it's give-and-take all the way down. and everyone's entitled to making their own decisions about it.

I didn't say you are obliged to fix a bug or deal with a customer service request permanently, but it is the best strategy in the long run, because this way you won't have to deal with other people asking this question or a similar one, and bothering you even more, wasting more of your time, and leaving a bad taste in the mouth among disgruntled users who may speak against your project or against you on many occasions. If you want to work harder and alienate your users, then feel free to close all bugs as “RESOLVED / WONT_FIX / YOU_SUCK”, but I think it's the wrong thing to do, which is why I consistently try to follow Joel's advice.

well, why don't we talk about what you're actually trying to accomplish then? can you point me at your code? maybe we can find out where the documentation is lacking in the process.

Thanks!

You can find the code on bitbucket.org (in a Mercurial repository). Someone told me he would like to create a Russian version of the site, and I may wish to create a Hebrew version, and there may other localised versions in the future. I didn't start the actual coding yet.

There's a "Fork me on BitBucket" strip at the right corner of the screen on the site which links to it and should appear even if JS is disabled.

let me be clear on this: the license is not going to change. i'm a strong proponent of copyleft so you have to put up with that if you want to use my code. but there's really no need to worry about getting sued for using this plugin to generate your website.

Well, it would be useful if you spelled your expectations from the fact that this plugin is under the AGPL licence explicitly in the README, because many people (and especially some companies) may be worried.

Regards,

— Shlomi Fish

Finally, can this bug be reopened (since it appears to be real) or should I file a new bug?

prometheus-ev / jekyll-localization

It's not clear how to use this plugin #3