Browse code

Updates the README regarding minifying sources

hiromipaw authored on03/07/2017 09:56:57
Showing2 changed files
... ...
@@ -1,7 +1,5 @@
1 1
 RewriteEngine On
2 2
 
3
-#ErrorDocument 404 /404
4
-
5 3
 # moved to /docs/
6 4
 RewriteRule ^faq(.*) /docs/faq$1 [R=301,L]
7 5
 RewriteRule ^bridges(.*) /docs/bridges$1 [R=301,L]
... ...
@@ -1,6 +1,6 @@
1 1
 # How to contribute
2 2
 
3
-Thanks for being interested to work on the website, I tried to make a simple 
3
+Thanks for being interested to work on the website, I tried to make a simple
4 4
 how-to for you to quickly get you setup:
5 5
 
6 6
 __Step 1:__ Clone the git repo.
... ...
@@ -8,7 +8,7 @@ __Step 1:__ Clone the git repo.
8 8
     git clone https://git.torproject.org/project/web/webwml.git
9 9
     cd webwml
10 10
 
11
-__Step 1b:__ Create a bare public repository (i.e on Github), where you'd push 
11
+__Step 1b:__ Create a bare public repository (i.e on Github), where you'd push
12 12
 your commits to. Make sure you're in `webwml` directory, and run:
13 13
 
14 14
     git remote add pick-a-name your-git-url
... ...
@@ -18,19 +18,19 @@ _Example:_
18 18
 
19 19
 __Step 2:__ Create and switch to a new branch.
20 20
 
21
-_In the following example, I've named my branch "docs" as I'm planning to work 
21
+_In the following example, I've named my branch "docs" as I'm planning to work
22 22
 on the documentations._
23 23
 
24 24
     git checkout -b docs
25 25
 
26
-__Step 3:__ Now you can start working on website and make changes. Once you're 
26
+__Step 3:__ Now you can start working on website and make changes. Once you're
27 27
 done, commit and push it to your public repo.
28 28
 
29 29
 _Example:_
30 30
 
31 31
     git push tpo-gh docs
32 32
 
33
-__Step 4:__ Open a new ticket on [trac](https://trac.torproject.org) with a 
33
+__Step 4:__ Open a new ticket on [trac](https://trac.torproject.org) with a
34 34
 link to your shiny new repo/branch.
35 35
 
36 36
 # Building website
... ...
@@ -41,14 +41,14 @@ To quickly get set up and build website locally, simply follow these steps:
41 41
 
42 42
     sudo apt-get install wml asciidoc
43 43
 
44
-  __Step 2:__ Configure where to find your tor git repository. It needs this 
44
+  __Step 2:__ Configure where to find your tor git repository. It needs this
45 45
 to make the
46 46
      manual page.
47 47
 
48 48
     git clone https://git.torproject.org/project/web/webwml.git
49 49
     cd webwml
50 50
     cp Makefile.local.sample Makefile.local
51
-    
51
+
52 52
 Note: Change the `TORGIT` in Makefile.local to point to your tor git repo.
53 53
 
54 54
   __Step 3:__ Make the website.
... ...
@@ -69,16 +69,21 @@ The build fails with "Invalid object name".
69 69
     ---- Contents of STDERR channel: ---------
70 70
     fatal: Invalid object name 'tor-0.2.6.1-alpha'.
71 71
     asciidoc: FAILED: manpage document title is mandatory
72
-    No manpage because of asciidoc error or file not available from git at 
72
+    No manpage because of asciidoc error or file not available from git at
73 73
     /tmp/wml.zwcq0q/wml.30867.tmp1.wml line 415.
74 74
 
75
-  This means your tor repository is out of date. Update your tor git 
75
+  This means your tor repository is out of date. Update your tor git
76 76
 repository.
77 77
 
78
+### Some information regarding working with minified CSS and JS sources
79
+
80
+If you want to edit any of the CSS or JS sources, please bear in mind that the HTML uses the minified versions. We keep in the repository both versions side-to-side. Once you edit the original source make sure you generate the minified version again. Most editors have plugins to minify CSS and JS files.
81
+
82
+If you are wondering why is it "cool" to minify sources even though compression is used on the server, please consider that Minification can be well be used in combination with gzipping sources. Minification does a lot of additional things that compression doesn't do. During minification comments are removed, long variables are renamed to shorter variable names, etc. Transferred data can be significantly smaller after minification, than by simply compressing the original. Although this depends a lot on the original source, minifying helps with mobile browsers and slower connections.
78 83
 
79 84
 ### More detailed instructions from Roger
80 85
 
81
-_Note: This section was written when website repo was still on svn, and it 
86
+_Note: This section was written when website repo was still on svn, and it
82 87
 wasn't built automatically._
83 88
 
84 89
 Here are the instructions I sent David Fifield when he asked about