diff --git a/docs/doctrees/index.doctree b/docs/doctrees/index.doctree index 09d02fc9a..94f186261 100644 Binary files a/docs/doctrees/index.doctree and b/docs/doctrees/index.doctree differ diff --git a/docs/html/.buildinfo b/docs/html/.buildinfo index 9683692ae..fd783ea0c 100644 --- a/docs/html/.buildinfo +++ b/docs/html/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 9cade5fa70d219453c215cec2a2631df +config: 738ca7b60aed811ee1668ad08d26eabb tags: fbb0d17656682115ca4d033fb2f83ba1 diff --git a/docs/html/_sources/index.txt b/docs/html/_sources/index.txt index 36f73ed83..06388f70a 100644 --- a/docs/html/_sources/index.txt +++ b/docs/html/_sources/index.txt @@ -349,6 +349,39 @@ The connection is already created inside Converse.js, so the If someone submits a sane patch that does the above, I'll be happy to merge it. Until then, people will have to do this themselves. +======== +Features +======== + +Off-the-record encryption +========================= + +Converse.js supports `Off-the-record (OTR) `_ +encrypted messaging. + +The OTR protocol not only **encrypts your messages**, it provides ways to +**verify the identity** of the person you are talking to, +**plausible deniability** and **perfect forward secrecy** by generating +new encryption keys for each conversation. + +In its current state, Javascript cryptography is fraught with dangers and +challenges that make it impossible to reach the same standard of security that +is available with native "desktop" software. + +This is due to its runtime malleability, the way it is "installed" (e.g. +served) and the browser's lack of cryptographic primitives needed to implement +secure crypto. + +For harsh but fairly valid criticism of Javascript cryptography, read: +`Javascript Cryptography Considered Harmful `_. + +To get an idea on how this applies to OTR support in Converse.js, please read +`my thoughts on it `_. + +For now, suffice to say that although its useful to have OTR support in +Converse.js in order to avoid most eavesdroppers, if you need serious +communications privacy, then you're much better off using native software. + =========== Development =========== @@ -478,6 +511,137 @@ You can run both the tests and jshint in one go by calling: grunt check +Minification +============ + +Minifying Javascript and CSS +---------------------------- + +Please make sure to read the section `Development`_ and that you have installed +all development dependencies (long story short, you can run ``npm install`` +and then ``grunt fetch``). + +We use `require.js`_ to keep track of *Converse.js* and its dependencies and to +to bundle them together in a single minified file fit for deployment to a +production site. + +To minify the Javascript and CSS, run the following command: + +:: + + grunt minify + +Javascript will be bundled and minified with `require.js`_'s optimization tool, +using `almond `_. + +You can `read more about require.js's optimizer here`_. + +CSS is minified via `cssmin `_. + +Translations +============ + +.. Note :: + Translations take up a lot of space and will bloat your minified file. + At the time of writing, all the translations add about 50KB of extra data to + the minified javascript file. Therefore, make sure to only + include those languages that you intend to support and remove from + ./locale/locales.js those which you don't need. Remember to rebuild the + minified file afterwards. + +The gettext POT file located in ./locale/converse.pot is the template +containing all translations and from which for each language an individual PO +file is generated. + +The POT file contains all translateable strings extracted from converse.js. + +To make a user facing string translateable, wrap it in the double underscore helper +function like so: + +:: + + __('This string will be translated at runtime'); + +After adding the string, you'll need to regenerate the POT file, like so: + +:: + + make pot + +You can then create or update the PO file for a specific language by doing the following: + +:: + + msgmerge ./locale/de/LC_MESSAGES/converse.po ./locale/converse.pot -U + +To do this for ALL languages, run: + +:: + + make merge + +The resulting PO file is then what gets translated. + +If you've created a new PO file, please make sure to add the following +attributes at the top of the file (under *Content-Transfer-Encoding*). They are +required as configuration settings for Jed, the Javascript translations library +that we're using. + +:: + + "domain: converse\n" + "lang: de\n" + "plural_forms: nplurals=2; plural=(n != 1);\n" + + +Unfortunately `Jed `_ cannot use the PO files directly. We have to generate from it +a file in JSON format and then put that in a .js file for the specific +language. + +To generate JSON from a PO file, you'll need po2json for node.js. Run the +following command to install it (npm being the node.js package manager): + +:: + + npm install po2json + +You can then convert the translations into JSON format: + +:: + + po2json locale/de/LC_MESSAGES/converse.po locale/de/LC_MESSAGES/converse.json + +Now from converse.json paste the data as a value for the "locale_data" key in the +object in the language's .js file. + +So, if you are for example translating into German (language code 'de'), you'll +create or update the file ./locale/LC_MESSAGES/de.js with the following code: + +:: + + (function (root, factory) { + define("de", ['jed'], function () { + return factory(new Jed({ + "domain": "converse", + "locale_data": { + // Paste the JSON data from converse.json here + } + }) + } + }(this, function (i18n) { + return i18n; + })); + +making sure to also paste the JSON data as value to the "locale_data" key. + +.. Note :: + If you are adding translations for a new language that is not already supported, + you'll have to make one more edit in ./locale/locales.js to make sure the + language is loaded by require.js. + +Congratulations, you've now succesfully added your translations. Sorry for all +those hoops you had to jump through. + =============== Troubleshooting @@ -972,140 +1136,6 @@ Used only in conjunction with ``xhr_user_search``. This is the URL to which an AJAX GET request will be made to fetch user data from your remote server. The query string will be included in the request with ``q`` as its key. -============ -Minification -============ - -Minifying Javascript and CSS -============================ - -Please make sure to read the section `Development`_ and that you have installed -all development dependencies (long story short, you can run ``npm install`` -and then ``grunt fetch``). - -We use `require.js`_ to keep track of *Converse.js* and its dependencies and to -to bundle them together in a single minified file fit for deployment to a -production site. - -To minify the Javascript and CSS, run the following command: - -:: - - grunt minify - -Javascript will be bundled and minified with `require.js`_'s optimization tool, -using `almond `_. - -You can `read more about require.js's optimizer here`_. - -CSS is minified via `cssmin `_. - - -============ -Translations -============ - -.. Note :: - Translations take up a lot of space and will bloat your minified file. - At the time of writing, all the translations add about 50KB of extra data to - the minified javascript file. Therefore, make sure to only - include those languages that you intend to support and remove from - ./locale/locales.js those which you don't need. Remember to rebuild the - minified file afterwards. - -The gettext POT file located in ./locale/converse.pot is the template -containing all translations and from which for each language an individual PO -file is generated. - -The POT file contains all translateable strings extracted from converse.js. - -To make a user facing string translateable, wrap it in the double underscore helper -function like so: - -:: - - __('This string will be translated at runtime'); - -After adding the string, you'll need to regenerate the POT file, like so: - -:: - - make pot - -You can then create or update the PO file for a specific language by doing the following: - -:: - - msgmerge ./locale/de/LC_MESSAGES/converse.po ./locale/converse.pot -U - -To do this for ALL languages, run: - -:: - - make merge - -The resulting PO file is then what gets translated. - -If you've created a new PO file, please make sure to add the following -attributes at the top of the file (under *Content-Transfer-Encoding*). They are -required as configuration settings for Jed, the Javascript translations library -that we're using. - -:: - - "domain: converse\n" - "lang: de\n" - "plural_forms: nplurals=2; plural=(n != 1);\n" - - -Unfortunately `Jed `_ cannot use the PO files directly. We have to generate from it -a file in JSON format and then put that in a .js file for the specific -language. - -To generate JSON from a PO file, you'll need po2json for node.js. Run the -following command to install it (npm being the node.js package manager): - -:: - - npm install po2json - -You can then convert the translations into JSON format: - -:: - - po2json locale/de/LC_MESSAGES/converse.po locale/de/LC_MESSAGES/converse.json - -Now from converse.json paste the data as a value for the "locale_data" key in the -object in the language's .js file. - -So, if you are for example translating into German (language code 'de'), you'll -create or update the file ./locale/LC_MESSAGES/de.js with the following code: - -:: - - (function (root, factory) { - define("de", ['jed'], function () { - return factory(new Jed({ - "domain": "converse", - "locale_data": { - // Paste the JSON data from converse.json here - } - }) - } - }(this, function (i18n) { - return i18n; - })); - -making sure to also paste the JSON data as value to the "locale_data" key. - -.. Note :: - If you are adding translations for a new language that is not already supported, - you'll have to make one more edit in ./locale/locales.js to make sure the - language is loaded by require.js. - -Congratulations, you've now succesfully added your translations. Sorry for all -those hoops you had to jump through. - .. _`read more about require.js's optimizer here`: http://requirejs.org/docs/optimization.html .. _`HTTP`: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol .. _`XMPP`: https://en.wikipedia.org/wiki/Xmpp diff --git a/docs/html/genindex.html b/docs/html/genindex.html index 5ec715998..8705ca552 100644 --- a/docs/html/genindex.html +++ b/docs/html/genindex.html @@ -9,7 +9,7 @@ - Index — Converse.js 0.7.2 documentation + Index — Converse.js 0.7.3 documentation @@ -17,7 +17,7 @@ - +
@@ -80,7 +80,7 @@
  • index
    • -
  • Converse.js 0.7.2 documentation »
    • +
  • Converse.js 0.7.3 documentation »
    • diff --git a/docs/html/index.html b/docs/html/index.html index fc316b813..998246759 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -7,7 +7,7 @@ - Quickstart (to get a demo up and running) — Converse.js 0.7.2 documentation + Quickstart (to get a demo up and running) — Converse.js 0.7.3 documentation @@ -15,7 +15,7 @@ - +
    @@ -82,66 +82,70 @@
  • Facebook integration
    • -
  • Development diff --git a/docs/html/searchindex.js b/docs/html/searchindex.js index c31ce1a59..b2a9ae780 100644 --- a/docs/html/searchindex.js +++ b/docs/html/searchindex.js @@ -1 +1 @@ -Search.setIndex({objects:{},terms:{all:0,code:0,partial:0,queri:0,global:0,webchat:0,follow:0,row:0,privat:0,middl:0,depend:0,sensit:0,punjab:0,cach:0,buddi:0,under:0,sens:0,spec:0,sent:0,everi:0,string:0,fals:0,account:0,ident:0,facebook:0,jack:0,veri:0,retriev:0,tri:0,chatpanel:[],button:0,messagetext:0,list:0,correct:0,"try":0,item:0,sane:0,div:0,refer:0,pleas:0,prevent:0,xhr_user_search_url:0,almond:0,focu:0,jump:0,second:0,pass:0,download:0,further:0,fullnam:0,port:0,folk:0,even:0,index:0,what:0,hide:0,appear:0,section:0,abl:0,access:0,delet:0,use_otr_by_default:0,"new":0,net:0,method:0,jqueri:0,widget:0,themselv:0,messagexml:0,gener:0,here:0,bodi:0,typeerror:0,let:0,path:0,strong:[],modifi:0,valu:0,box:0,great:0,convers:0,mysit:0,ajax:0,onbuddystatuschang:0,fetch:0,implement:0,sorri:0,chanc:0,via:0,repositori:0,extra:0,solut:0,prefer:0,put:0,href:0,fake:0,auto_list_room:0,instal:0,should:0,establish:0,getsess:0,from:0,zip:0,commun:0,doubl:0,two:0,websit:0,few:0,stylesheet:0,busi:0,call:0,recommend:0,msg:0,type:0,until:0,toggl:0,more:0,peopl:0,notic:0,site:0,conjunct:0,particular:0,vcard:0,must:0,none:[],word:0,room:0,past:0,work:0,uniqu:0,xhr:0,legwork:0,can:0,lc_messag:0,purpos:0,root:0,blogpost:0,control:0,quickstart:0,give:0,share:0,templat:0,tag:0,proprietari:0,explor:0,onlin:0,unfortun:0,occup:0,end:0,goal:0,thing:0,anoth:0,write:0,how:0,bosh_serv:0,sid:0,instead:0,css:0,updat:0,npm:0,regener:0,product:0,resourc:0,after:0,usabl:0,befor:0,allow_contact_request:0,multipl:0,underscor:0,data:0,demonstr:0,man:0,repo:0,"short":0,practic:0,third:0,bind:0,secur:0,show_controlbox_by_default:0,correspond:0,element:0,caus:0,callback:0,show_only_online_us:0,allow:0,parti:0,mechan:0,order:0,feedback:0,chatbox:0,xmpp:0,over:0,move:0,becaus:0,through:0,reconnect:0,paramet:0,streamlin:0,snippet:0,style:[],"8147a27e4a7f9b55ffc85c2683f9529a":0,render:0,fit:0,fix:0,window:0,pend:0,persist:0,hidden:0,main:0,might:0,them:0,anim:0,"return":0,thei:0,python:0,initi:0,onmessag:0,automat:0,expose_rid_and_sid:0,front:0,now:0,introduct:0,name:0,edit:0,troubleshoot:0,revers:0,authent:0,separ:0,token:0,ejabberd:0,each:0,debug:0,side:0,mean:0,domain:0,michael:0,individu:0,realli:0,"static":0,connect:0,our:0,happen:0,extract:0,event:0,special:0,out:0,variabl:0,shown:0,"3rd":0,space:0,miss:0,proxy_pass:0,content:0,rel:0,internet:0,got:0,plural:0,factori:0,po2json:0,model:0,proxi:0,insid:0,written:0,standard:0,standalon:0,reason:0,ask:0,org:0,afterward:0,xhr_custom_status_url:0,rewriteengin:0,could:0,keep:0,turn:0,perhap:0,outsid:[],first:0,origin:0,softwar:0,directli:0,malici:0,onc:0,hoop:0,lastnam:0,number:0,yourself:0,restrict:0,instruct:0,alreadi:0,done:0,submit:0,onchatboxclos:0,owner:0,custom:0,jabber:0,differ:0,php:0,script:0,top:0,contact:0,attack:0,messag:0,attach:0,stori:0,master:0,jed:0,jcbrand:0,"final":0,listen:0,luckili:0,consol:0,option:0,tool:0,specifi:0,part:0,pars:0,grunt:0,than:0,serv:0,wide:0,kind:0,bloat:0,provid:0,remov:0,project:0,bridg:0,someothersit:0,browser:0,pre:0,"function":0,credenti:0,saa:0,modern:0,ani:0,packag:0,have:0,tabl:0,need:0,moffitt:0,django:0,bosh_service_url:0,prebind:0,inform:0,latter:0,thorough:0,click:0,note:0,also:0,exampl:0,take:0,which:0,singl:0,wherebi:0,sure:0,roster:0,unsur:0,previou:0,most:0,deploi:0,homepag:0,"class":0,don:0,use_vcard:0,url:0,request:0,doe:0,runtim:0,determin:0,bower:0,usual:0,xdomainrequest:0,devdepend:0,show:0,german:0,text:0,succesfulli:0,server_nam:0,session:0,identifi:0,fine:0,find:0,help:0,xml:0,current:0,onli:0,exactli:0,locat:0,just:0,configur:0,apach:0,stanza:0,haven:0,"public":0,version:0,folder:0,local:0,meant:0,count:[],get:0,stop:0,soon:0,opkod:0,nativ:0,cannot:0,chat:0,deploy:0,requir:0,show_call_button:0,enabl:0,emb:0,mainspec:0,whenev:0,patch:0,reload:0,bad:0,integr:0,contain:0,where:0,view:0,wiki:0,set:0,habit:0,stroph:0,see:0,bare:0,result:0,close:0,eventnam:0,best:0,concern:0,awar:[],statu:0,said:0,extend:0,inconveni:0,someth:0,state:0,muc:0,between:0,awai:0,experi:0,jasmin:0,across:0,attribut:0,appreci:0,kei:0,screen:0,javascript:0,jid:0,job:0,entir:0,bosh:0,otherwis:0,"5e64a30272af065bd72258c565a03f2f":0,cache_otr_kei:0,both:0,cor:0,instant:0,shortliv:0,conversej:0,myself:0,etc:0,grain:0,mani:0,login:0,com:0,load:0,node_modul:0,simpli:0,pot:0,solv:0,assum:0,backend:0,quit:0,sucessfulli:0,addition:0,rebuild:0,empti:0,github:0,compon:0,json:0,much:0,toolbar:0,subscrib:0,blob:0,session_kei:0,fire:0,imag:0,xxx:0,rubi:0,convert:0,minifi:0,togeth:0,input:0,i18n:0,otr:0,present:0,"case":0,multi:0,therefor:0,look:0,servic:0,plugin:0,defin:0,"while":0,abov:0,error:0,howev:0,hightlight:0,increment:0,helper:0,demo:0,auto_subscrib:0,non:0,oncallbuttonclick:0,itself:0,incom:0,rid:0,conn:[],develop:0,open:0,receiv:0,media:0,make:0,minif:0,cross:0,same:0,read:0,onconnectfacebook:0,html:0,unexpectedli:0,chatroom:0,document:0,medit:0,conflict:0,complet:0,signon:0,http:0,webserv:0,optim:0,upon:0,someon:0,hand:0,remot:0,"50kb":0,user:0,uncaught:0,rewriterul:0,xhr_user_search:0,cssmin:0,recent:0,weibel:0,stateless:0,off:0,bewar:0,choos:0,firstli:0,markup:0,min:0,well:0,object:0,person:0,without:0,command:0,achiev:0,thi:0,onmessagesend:0,everyth:0,latest:0,plural_form:0,protocol:0,execut:0,when:0,onstatuschang:0,jshint:0,languag:0,web:0,xmlhttprequest:0,expos:0,field:0,had:0,onchatboxopen:0,add:0,other:0,non_amd:0,versa:0,appli:0,els:0,match:0,build:0,bin:0,applic:0,format:0,webpag:0,amd:0,nginx:0,traffic:0,know:0,background:0,press:0,like:0,xss:0,backbon:0,specif:0,manual:0,server:0,collect:[],benefit:0,api:0,either:0,output:0,page:0,candi:0,facebookconnect:0,right:0,deal:0,nplural:0,some:0,back:0,drop:0,librari:0,bottom:0,though:0,xhr_custom_statu:0,track:0,allow_otr:0,inject:0,overcom:0,oniniti:0,localhost:0,avatar:0,plu:0,who:0,run:0,host:0,although:0,post:0,panel:0,src:0,about:0,firstnam:0,controlbox:0,manag:0,issu:0,act:0,client:0,own:0,curiou:0,inlin:0,within:0,encod:0,onbuddystatusmessagechang:0,been:0,onreadi:0,wrap:0,chang:0,storag:0,your:0,merg:0,log:0,wai:0,aren:0,transfer:0,support:0,"long":0,happi:0,avail:0,trigger:0,includ:0,lot:0,suit:0,analysi:0,head:0,properli:0,form:0,bundl:0,somehow:0,link:0,translat:0,synonym:0,line:0,stand:0,"true":0,bug:0,congratul:0,longer:0,info:0,pull:0,made:0,dirti:0,tab:0,possibl:0,whether:0,bugfix:0,displai:0,asynchron:0,record:0,below:0,those:0,tightli:0,auto_reconnect:0,problem:0,emit:0,expect:0,onrosterviewupd:0,featur:0,constant:0,creat:0,movim:0,decrypt:0,doesn:0,msgmerg:0,exist:0,file:0,face:0,check:0,probabl:0,encrypt:0,want:0,onrost:0,tip:0,detail:0,gettext:0,"default":0,valid:0,onchatboxfocus:0,rememb:0,varieti:0,test:0,you:0,servernam:0,nice:0,node:0,intend:0,duck:0,onstatusmessagechang:0,releas:0,hide_muc_serv:0,stai:0,lang:0,requirej:0,vice:0,directori:0,virtualhost:0,getjson:0,rule:0,allow_muc:0,ignor:0,locale_data:0,potenti:0,time:0},objtypes:{},titles:["Quickstart (to get a demo up and running)"],objnames:{},filenames:["index"]}) \ No newline at end of file +Search.setIndex({objects:{},terms:{all:0,code:0,partial:0,queri:0,lack:0,webchat:0,follow:0,row:0,privat:0,middl:0,depend:0,onmessagesend:0,sensit:0,punjab:0,cach:0,buddi:0,under:0,sens:0,spec:0,sent:0,global:0,everi:0,string:0,fals:0,account:0,requirej:0,jid:0,facebook:0,jack:0,veri:0,retriev:0,tri:0,chatpanel:[],button:0,messagetext:0,list:0,virtualhost:0,factori:0,"try":0,item:0,sane:0,div:0,pleas:0,prevent:0,version:0,xhr_user_search_url:0,almond:0,focu:0,jump:0,second:0,pass:0,download:0,further:0,fullnam:0,port:0,folk:0,even:0,index:0,what:0,hide:0,appear:0,section:0,abl:0,access:0,delet:0,use_otr_by_default:0,awar:[],"new":0,net:0,method:0,widget:0,themselv:0,messagexml:0,gener:0,here:0,bodi:0,typeerror:0,let:0,path:0,strong:[],modifi:0,valu:0,box:0,great:0,convers:0,mysit:0,reason:0,fetch:0,implement:0,sorri:0,chanc:0,via:0,although:0,extra:0,apach:0,prefer:0,ask:0,href:0,fake:0,auto_list_room:0,instal:0,establish:0,getsess:0,from:0,zip:0,commun:0,doubl:0,two:0,websit:0,few:0,stylesheet:0,call:0,recommend:0,msg:0,type:0,until:0,toggl:0,more:0,peopl:0,line:0,notic:0,remot:0,particular:0,vcard:0,must:0,none:[],word:0,room:0,past:0,work:0,uniqu:0,xhr:0,can:0,lc_messag:0,purpos:0,root:0,blogpost:0,control:0,quickstart:0,give:0,challeng:0,share:0,templat:0,critic:0,tag:0,proprietari:0,explor:0,onlin:0,occup:0,end:0,goal:0,thing:0,anoth:0,deniabl:0,snippet:0,how:0,bosh_serv:0,sid:0,expose_rid_and_sid:0,css:0,updat:0,npm:0,regener:0,product:0,resourc:0,haven:0,after:0,usabl:0,befor:0,allow_contact_request:0,multipl:0,underscor:0,data:0,demonstr:0,man:0,opkod:0,"short":0,practic:0,third:0,seriou:0,secur:0,show_controlbox_by_default:0,correspond:0,element:0,caus:0,inform:0,show_only_online_us:0,allow:0,media:0,mechan:0,order:0,talk:0,feedback:0,chatbox:0,xmpp:0,over:0,move:0,becaus:0,through:0,reconnect:0,paramet:0,streamlin:0,write:0,style:[],"8147a27e4a7f9b55ffc85c2683f9529a":0,render:0,fit:0,fix:0,better:0,window:0,pend:0,persist:0,hidden:0,main:0,might:0,them:0,anim:0,"return":0,thei:0,python:0,initi:0,onmessag:0,onbuddystatusmessagechang:0,instead:0,front:0,now:0,introduct:0,name:0,edit:0,troubleshoot:0,revers:0,crypto:0,authent:0,separ:0,token:0,ejabberd:0,each:0,debug:0,side:0,mean:0,everyth:0,domain:0,michael:0,individu:0,idea:0,realli:0,"static":0,connect:0,our:0,happen:0,patch:0,extract:0,event:0,special:0,out:0,variabl:0,shown:0,"3rd":0,space:0,jabber:0,proxy_pass:0,auto_reconnect:0,content:0,rel:0,internet:0,got:0,plural:0,correct:0,po2json:0,proxi:0,insid:0,state:0,standard:0,standalon:0,ajax:0,put:0,org:0,afterward:0,xhr_custom_status_url:0,could:0,keep:0,turn:0,perhap:0,xhr_custom_statu:0,outsid:[],imposs:0,first:0,origin:0,softwar:0,directli:0,malici:0,onc:0,hoop:0,lastnam:0,number:0,yourself:0,restrict:0,instruct:0,alreadi:0,done:0,"long":0,onchatboxclos:0,owner:0,happi:0,miss:0,suffic:0,differ:0,script:0,top:0,contact:0,attack:0,messag:0,attach:0,stori:0,master:0,jed:0,privaci:0,"final":0,listen:0,luckili:0,consol:0,option:0,tool:0,jcbrand:0,specifi:0,part:0,pars:0,grunt:0,than:0,serv:0,wide:0,kind:0,bloat:0,provid:0,remov:0,project:0,bridg:0,bind:0,someothersit:0,browser:0,pre:0,analysi:0,sai:0,credenti:0,saa:0,modern:0,ani:0,packag:0,have:0,tabl:0,need:0,moffitt:0,django:0,bosh_service_url:0,prebind:0,callback:0,latter:0,thorough:0,click:0,note:0,also:0,exampl:0,take:0,which:0,singl:0,therefor:0,sure:0,roster:0,unsur:0,previou:0,reach:0,most:0,deploi:0,rewriterul:0,homepag:0,"class":0,don:0,use_vcard:0,url:0,request:0,doe:0,runtim:0,determin:0,bower:0,latest:0,xdomainrequest:0,devdepend:0,show:0,german:0,text:0,succesfulli:0,page:0,server_nam:0,session:0,protocol:0,fine:0,find:0,help:0,xml:0,current:0,onli:0,exactli:0,locat:0,execut:0,configur:0,solut:0,stanza:0,should:0,busi:0,folder:0,local:0,meant:0,info:0,get:0,stop:0,soon:0,repo:0,nativ:0,cannot:0,cryptographi:0,requir:0,show_call_button:0,enabl:0,emb:0,mainspec:0,whenev:0,multi:0,achiev:0,"public":0,reload:0,bad:0,integr:0,though:0,contain:0,where:0,view:0,wiki:0,set:0,habit:0,stroph:0,see:0,bare:0,result:0,close:0,eventnam:0,best:0,concern:0,jqueri:0,statu:0,said:0,kei:0,inconveni:0,someth:0,written:0,muc:0,between:0,awai:0,experi:0,jasmin:0,across:0,attribut:0,verifi:0,appreci:0,extend:0,screen:0,javascript:0,conjunct:0,job:0,entir:0,bosh:0,otherwis:0,"5e64a30272af065bd72258c565a03f2f":0,cache_otr_kei:0,both:0,cor:0,instant:0,shortliv:0,conversej:0,avatar:0,etc:0,grain:0,mani:0,login:0,com:0,load:0,node_modul:0,simpli:0,within:0,pot:0,solv:0,non:0,assum:0,malleabl:0,backend:0,quit:0,sucessfulli:0,addition:0,rebuild:0,due:0,empti:0,github:0,compon:0,json:0,much:0,toolbar:0,subscrib:0,non_amd:0,session_kei:0,fire:0,imag:0,xxx:0,rubi:0,convert:0,minifi:0,togeth:0,els:0,i18n:0,otr:0,plausibl:0,present:0,"case":0,myself:0,ident:0,look:0,servic:0,plugin:0,defin:0,"while":0,abov:0,error:0,howev:0,hightlight:0,increment:0,helper:0,demo:0,auto_subscrib:0,site:0,oncallbuttonclick:0,itself:0,incom:0,rid:0,conn:[],develop:0,harsh:0,open:0,receiv:0,parti:0,make:0,format:0,minif:0,cross:0,same:0,webpag:0,onconnectfacebook:0,html:0,unexpectedli:0,chatroom:0,document:0,medit:0,conflict:0,complet:0,signon:0,http:0,webserv:0,optim:0,upon:0,someon:0,hand:0,fairli:0,"50kb":0,user:0,uncaught:0,php:0,xhr_user_search:0,cssmin:0,recent:0,weibel:0,stateless:0,off:0,bewar:0,firstli:0,markup:0,min:0,well:0,thought:0,person:0,without:0,command:0,wherebi:0,thi:0,choos:0,model:0,usual:0,plural_form:0,identifi:0,just:0,tip:0,onstatuschang:0,jshint:0,file:0,languag:0,web:0,xmlhttprequest:0,expos:0,field:0,danger:0,had:0,onchatboxopen:0,desktop:0,add:0,valid:0,blob:0,versa:0,primit:0,input:0,match:0,build:0,bin:0,applic:0,secreci:0,read:0,amd:0,nginx:0,traffic:0,know:0,background:0,press:0,backbon:0,xss:0,like:0,specif:0,manual:0,server:0,collect:[],benefit:0,api:0,either:0,output:0,perfect:0,manag:0,candi:0,facebookconnect:0,right:0,who:0,deal:0,nplural:0,some:0,back:0,drop:0,librari:0,bottom:0,avoid:0,deploy:0,rewriteengin:0,track:0,allow_otr:0,inject:0,overcom:0,oniniti:0,localhost:0,refer:0,plu:0,object:0,run:0,host:0,repositori:0,post:0,appli:0,panel:0,src:0,about:0,firstnam:0,controlbox:0,unfortun:0,issu:0,act:0,client:0,own:0,curiou:0,inlin:0,eavesdropp:0,encod:0,harm:0,automat:0,been:0,onreadi:0,wrap:0,chang:0,storag:0,your:0,merg:0,log:0,wai:0,aren:0,transfer:0,support:0,submit:0,custom:0,avail:0,trigger:0,includ:0,lot:0,suit:0,forward:0,"function":0,head:0,properli:0,form:0,bundl:0,somehow:0,link:0,translat:0,synonym:0,cryptograph:0,stand:0,"true":0,bug:0,congratul:0,longer:0,count:[],pull:0,made:0,dirti:0,tab:0,possibl:0,whether:0,bugfix:0,displai:0,asynchron:0,record:0,below:0,those:0,tightli:0,legwork:0,problem:0,emit:0,expect:0,onrosterviewupd:0,featur:0,constant:0,creat:0,movim:0,decrypt:0,doesn:0,msgmerg:0,exist:0,chat:0,face:0,check:0,probabl:0,encrypt:0,want:0,onrost:0,when:0,detail:0,gettext:0,"default":0,other:0,onchatboxfocus:0,rememb:0,varieti:0,test:0,you:0,servernam:0,nice:0,node:0,intend:0,duck:0,onstatusmessagechang:0,releas:0,consid:0,hide_muc_serv:0,stai:0,lang:0,fraught:0,vice:0,directori:0,onbuddystatuschang:0,getjson:0,rule:0,allow_muc:0,ignor:0,locale_data:0,potenti:0,time:0},objtypes:{},titles:["Quickstart (to get a demo up and running)"],objnames:{},filenames:["index"]}) \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 36f73ed83..06388f70a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -349,6 +349,39 @@ The connection is already created inside Converse.js, so the If someone submits a sane patch that does the above, I'll be happy to merge it. Until then, people will have to do this themselves. +======== +Features +======== + +Off-the-record encryption +========================= + +Converse.js supports `Off-the-record (OTR) `_ +encrypted messaging. + +The OTR protocol not only **encrypts your messages**, it provides ways to +**verify the identity** of the person you are talking to, +**plausible deniability** and **perfect forward secrecy** by generating +new encryption keys for each conversation. + +In its current state, Javascript cryptography is fraught with dangers and +challenges that make it impossible to reach the same standard of security that +is available with native "desktop" software. + +This is due to its runtime malleability, the way it is "installed" (e.g. +served) and the browser's lack of cryptographic primitives needed to implement +secure crypto. + +For harsh but fairly valid criticism of Javascript cryptography, read: +`Javascript Cryptography Considered Harmful `_. + +To get an idea on how this applies to OTR support in Converse.js, please read +`my thoughts on it `_. + +For now, suffice to say that although its useful to have OTR support in +Converse.js in order to avoid most eavesdroppers, if you need serious +communications privacy, then you're much better off using native software. + =========== Development =========== @@ -478,6 +511,137 @@ You can run both the tests and jshint in one go by calling: grunt check +Minification +============ + +Minifying Javascript and CSS +---------------------------- + +Please make sure to read the section `Development`_ and that you have installed +all development dependencies (long story short, you can run ``npm install`` +and then ``grunt fetch``). + +We use `require.js`_ to keep track of *Converse.js* and its dependencies and to +to bundle them together in a single minified file fit for deployment to a +production site. + +To minify the Javascript and CSS, run the following command: + +:: + + grunt minify + +Javascript will be bundled and minified with `require.js`_'s optimization tool, +using `almond `_. + +You can `read more about require.js's optimizer here`_. + +CSS is minified via `cssmin `_. + +Translations +============ + +.. Note :: + Translations take up a lot of space and will bloat your minified file. + At the time of writing, all the translations add about 50KB of extra data to + the minified javascript file. Therefore, make sure to only + include those languages that you intend to support and remove from + ./locale/locales.js those which you don't need. Remember to rebuild the + minified file afterwards. + +The gettext POT file located in ./locale/converse.pot is the template +containing all translations and from which for each language an individual PO +file is generated. + +The POT file contains all translateable strings extracted from converse.js. + +To make a user facing string translateable, wrap it in the double underscore helper +function like so: + +:: + + __('This string will be translated at runtime'); + +After adding the string, you'll need to regenerate the POT file, like so: + +:: + + make pot + +You can then create or update the PO file for a specific language by doing the following: + +:: + + msgmerge ./locale/de/LC_MESSAGES/converse.po ./locale/converse.pot -U + +To do this for ALL languages, run: + +:: + + make merge + +The resulting PO file is then what gets translated. + +If you've created a new PO file, please make sure to add the following +attributes at the top of the file (under *Content-Transfer-Encoding*). They are +required as configuration settings for Jed, the Javascript translations library +that we're using. + +:: + + "domain: converse\n" + "lang: de\n" + "plural_forms: nplurals=2; plural=(n != 1);\n" + + +Unfortunately `Jed `_ cannot use the PO files directly. We have to generate from it +a file in JSON format and then put that in a .js file for the specific +language. + +To generate JSON from a PO file, you'll need po2json for node.js. Run the +following command to install it (npm being the node.js package manager): + +:: + + npm install po2json + +You can then convert the translations into JSON format: + +:: + + po2json locale/de/LC_MESSAGES/converse.po locale/de/LC_MESSAGES/converse.json + +Now from converse.json paste the data as a value for the "locale_data" key in the +object in the language's .js file. + +So, if you are for example translating into German (language code 'de'), you'll +create or update the file ./locale/LC_MESSAGES/de.js with the following code: + +:: + + (function (root, factory) { + define("de", ['jed'], function () { + return factory(new Jed({ + "domain": "converse", + "locale_data": { + // Paste the JSON data from converse.json here + } + }) + } + }(this, function (i18n) { + return i18n; + })); + +making sure to also paste the JSON data as value to the "locale_data" key. + +.. Note :: + If you are adding translations for a new language that is not already supported, + you'll have to make one more edit in ./locale/locales.js to make sure the + language is loaded by require.js. + +Congratulations, you've now succesfully added your translations. Sorry for all +those hoops you had to jump through. + =============== Troubleshooting @@ -972,140 +1136,6 @@ Used only in conjunction with ``xhr_user_search``. This is the URL to which an AJAX GET request will be made to fetch user data from your remote server. The query string will be included in the request with ``q`` as its key. -============ -Minification -============ - -Minifying Javascript and CSS -============================ - -Please make sure to read the section `Development`_ and that you have installed -all development dependencies (long story short, you can run ``npm install`` -and then ``grunt fetch``). - -We use `require.js`_ to keep track of *Converse.js* and its dependencies and to -to bundle them together in a single minified file fit for deployment to a -production site. - -To minify the Javascript and CSS, run the following command: - -:: - - grunt minify - -Javascript will be bundled and minified with `require.js`_'s optimization tool, -using `almond `_. - -You can `read more about require.js's optimizer here`_. - -CSS is minified via `cssmin `_. - - -============ -Translations -============ - -.. Note :: - Translations take up a lot of space and will bloat your minified file. - At the time of writing, all the translations add about 50KB of extra data to - the minified javascript file. Therefore, make sure to only - include those languages that you intend to support and remove from - ./locale/locales.js those which you don't need. Remember to rebuild the - minified file afterwards. - -The gettext POT file located in ./locale/converse.pot is the template -containing all translations and from which for each language an individual PO -file is generated. - -The POT file contains all translateable strings extracted from converse.js. - -To make a user facing string translateable, wrap it in the double underscore helper -function like so: - -:: - - __('This string will be translated at runtime'); - -After adding the string, you'll need to regenerate the POT file, like so: - -:: - - make pot - -You can then create or update the PO file for a specific language by doing the following: - -:: - - msgmerge ./locale/de/LC_MESSAGES/converse.po ./locale/converse.pot -U - -To do this for ALL languages, run: - -:: - - make merge - -The resulting PO file is then what gets translated. - -If you've created a new PO file, please make sure to add the following -attributes at the top of the file (under *Content-Transfer-Encoding*). They are -required as configuration settings for Jed, the Javascript translations library -that we're using. - -:: - - "domain: converse\n" - "lang: de\n" - "plural_forms: nplurals=2; plural=(n != 1);\n" - - -Unfortunately `Jed `_ cannot use the PO files directly. We have to generate from it -a file in JSON format and then put that in a .js file for the specific -language. - -To generate JSON from a PO file, you'll need po2json for node.js. Run the -following command to install it (npm being the node.js package manager): - -:: - - npm install po2json - -You can then convert the translations into JSON format: - -:: - - po2json locale/de/LC_MESSAGES/converse.po locale/de/LC_MESSAGES/converse.json - -Now from converse.json paste the data as a value for the "locale_data" key in the -object in the language's .js file. - -So, if you are for example translating into German (language code 'de'), you'll -create or update the file ./locale/LC_MESSAGES/de.js with the following code: - -:: - - (function (root, factory) { - define("de", ['jed'], function () { - return factory(new Jed({ - "domain": "converse", - "locale_data": { - // Paste the JSON data from converse.json here - } - }) - } - }(this, function (i18n) { - return i18n; - })); - -making sure to also paste the JSON data as value to the "locale_data" key. - -.. Note :: - If you are adding translations for a new language that is not already supported, - you'll have to make one more edit in ./locale/locales.js to make sure the - language is loaded by require.js. - -Congratulations, you've now succesfully added your translations. Sorry for all -those hoops you had to jump through. - .. _`read more about require.js's optimizer here`: http://requirejs.org/docs/optimization.html .. _`HTTP`: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol .. _`XMPP`: https://en.wikipedia.org/wiki/Xmpp