summary refs log tree commit diff stats
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README162
1 files changed, 47 insertions, 115 deletions
diff --git a/README b/README
index 96b7e53e..6e386635 100644
--- a/README
+++ b/README
@@ -1,154 +1,86 @@
 Ranger v.1.0.4
 ==============
 
-Ranger
+Ranger is a console file manager with fast and straightforward navigation.
+By efficiently using the screen space, it gives you a broad overview of
+your file system.  Ranger's hotkeys are similar to those of other common
+unix programs such as VIM, Emacs and Midnight Commander, though it's
+controllable with Arrow Keys just fine.
 
-   A keeper, guardian, or soldier who ranges over a region
-   to protect the area or enforce the law.
-
-This is the filemanager Chuck Norris the Texas Ranger would use
-if he had a computer with a unix-like operating system.  (He doesn't
-trust computers though and prefers to do the calculations himself.)
-
-After all, as a professional ranger, he needs a broad overview of his
-territory, and the multi-column display of ranger provides just that,
-rather than restricting you to the current directory only.
-You can preview the content of the selected file or directory, copy or move
-files around with the VIM-like commands dd and yy, execute predefined
-applications when opening a file, etc...
-
-Everything is fully customizable and written in Python (2.6 and 3.1
-compatible) using curses for the text-based user interface.
+The program is written in Python (2.6 or 3.1) and uses curses for the
+text-based user interface.
 
 
 About
 -----
 
-* Author:          Roman Zimbelmann
-* Email:           romanz@lavabit.com
+* Author:          Roman Zimbelmann  <romanz@lavabit.com>
 * Website:         http://savannah.nongnu.org/projects/ranger
-* Git repo:        http://git.savannah.gnu.org/cgit/ranger.git
+* Dependencies:    Unix-like OS, Python 2.6 or 3.1
+* License:         GNU General Public License Version 3
 * Version:         1.0.4
 
+* Download URL of the newest stable version:
+http://git.savannah.gnu.org/cgit/ranger.git/snapshot/ranger-stable.tar.gz
+
+* Git Clone URL:
+git clone http://git.sv.gnu.org/r/ranger.git
+
 
 Features
 --------
 
-* Multi-column display
+* Multi-column display (Miller Columns)
 * Preview of the selected file/directory
 * Common file operations (create/chmod/copy/delete/...)
-* Quickly find files or text inside files
 * VIM-like console and hotkeys
-* Open files in external programs
-* Mouse support
+* Automatically determine file types and run them with correct programs
 * Change the directory of your shell after exiting ranger
-* Bookmarks
-
-
-Dependencies
-------------
-
-* A Unix-like Operating System
-* Python 2.6 or 3.1
-* Python curses module  (often but not always included with Python)
-
-
-Bugs and Feature Requests
--------------------------
-
-Report bugs and feature requests on savannah:
-    https://savannah.nongnu.org/bugs/?func=additem&group=ranger
-
-Alternatively you can send an email to romanz@lavabit.com.
-
-Please include as much relevant information as possible.
-Using ranger with the --debug option will abort the program and
-print tracebacks rather than a red message in the statusbar.
-If this applies to you, please include such a traceback in your report.
+* Tabs, Bookmarks, Mouse support
 
 
 Getting Started
 ---------------
 
-If you just want to check out ranger without installing it, type
-
-    ./ranger.py --clean
-
-in the top directory of ranger.  By using the --clean switch, it will
-leave no trace on your system whatsoever.
-
-To properly install it, follow the instructions in the INSTALL file,
-then type:
+Ranger can be started without installing.  Just run the executable (in
+a terminal.)  The switch "--clean" will prevent it from creating or
+accessing configuration files.
 
-    ranger
+Follow the instructions in the INSTALL file for installing ranger.
 
-You should see 4 columns.  The third is the directory where you are at
-the moment.  To the left, there are the directories above the current
-working directory, and the column on the right is a preview of the selected
-file/directory.
+After starting ranger, you should see 4 columns. The third one is the main
+column, the directory where you're currently at.  To the left you see the
+parent directories and to the right there's a preview of the object you're
+pointing at.  Now use the Arrow Keys to navigate, Enter to open a file
+or type Q to quit.
 
-Now use the arrow keys to navigate, press enter to open a file.
+To customize ranger, copy the files from ranger/defaults/ to ~/.ranger/
+and modify them according to your wishes.
 
-A list of commands with short descriptions can be viewed by
-pressing "?" inside the program and following the instructions.
-The file ranger/defaults/keys.py contains all key combinations, so that's
-another place you may want to check out.
-
-
-Opening Files with Ranger
--------------------------
-
-If you use the same applications like me, you'll be able to open
-files by pressing the right arrow key.  If not, you will have to
-specify them in ranger/defaults/apps.py.  It's explained
-in the docstrings how exactly to do that.
-
-Once you've set up your applications, you can also use ranger to
-open files from the shell:
-    ranger blabla.pdf
-
-
-Customizing Ranger
-------------------
 
-The file ranger/defaults/options.py contains most of the options.
-apps.py defines how files are run, keys.py defines keybindings.
+Troubleshooting, Getting Help
+-----------------------------
 
-The files in ranger/defaults/ can be copied into ~/.ranger/ for per-user
-modifications.  Colorschemes can be placed in ~/.ranger/colorschemes.
+If you encounter an error, try running ranger with --debug.  This will
+sometimes display more detailed information about the error.  Also, try
+deactivating optimization:
 
-The configuration files should be self-explanatory.  If you need more
-information, check out the source code.
+PYTHONOPTIMIZE="" ranger --debug
 
-Also, see the file HACKING for more detailed instructions on
-modifying the program.
+Report bugs on savannah:  (please include as much information as possible)
+http://savannah.nongnu.org/bugs/?func=additem&group=ranger
 
+Ask questions on the mailing list:
+http://lists.nongnu.org/mailman/listinfo/ranger-users
 
-Roadmap
--------
 
-Short term:
-
-* Performance improvements everywhere
-* Simplification of the code
-
-Long term:
-
-* A plugin system
-* Separate ranger into multiple programs:
-  1. One daemon running in the background for slow IO operations
-  2. A file launcher (ideally an already existing one)
-  3. The actual program containing unseparable parts
-
-
-Tips
-----
+Further Reading
+---------------
 
-Change the directory of your parent shell when you exit ranger:
+Check the man page for information on common features and hotkeys.
 
-ranger() {
-    command ranger --fail-if-run $@ &&
-    cd "$(grep \^\' ~/.ranger/bookmarks | cut -b3-)"
-}
+The most detailed manual is accessible by pressing "?" from inside ranger.
+It is also available at ranger/help/, contained in the *.py files.
 
-This can be put into your ~/.bashrc or something similar.
+The file ranger/defaults/keys.py contains all key combinations, so that's
+another place you may want to check out.
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2024-09-02 20:14:04 +0000
ef='#n60'>60 61 62 63 64 65 66 67 68 
69

70
71
72
73
74
75

76

77
78
79
80

81

82
83
84
85

86

87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

151

152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

         






                                                







                                        
                                    





                                        
                                    
       
                                                                                            


                                               

                                                                

                                               
                                                  

































                                                                                        
                                





                           
                                  



                                         
                              



                                  
                                 














                                                                                               





















                                                                                   


























                                                                              
                                      
















                                                                     
geom = {}

function geom.on_shape(x,y, drawing, shape)
  if shape.mode == 'freehand' then
    return geom.on_freehand(x,y, drawing, shape)
  elseif shape.mode == 'line' then
    return geom.on_line(x,y, drawing, shape)
  elseif shape.mode == 'manhattan' then
    local p1 = drawing.points[shape.p1]
    local p2 = drawing.points[shape.p2]
    if p1.x == p2.x then
      if x ~= p1.x then return false end
      local y1,y2 = p1.y, p2.y
      if y1 > y2 then
        y1,y2 = y2,y1
      end
      return y >= y1-2 and y <= y2+2
    elseif p1.y == p2.y then
      if y ~= p1.y then return false end
      local x1,x2 = p1.x, p2.x
      if x1 > x2 then
        x1,x2 = x2,x1
      end
      return x >= x1-2 and x <= x2+2
    end
  elseif shape.mode == 'polygon' or shape.mode == 'rectangle' or shape.mode == 'square' then
    return geom.on_polygon(x,y, drawing, shape)
  elseif shape.mode == 'circle' then
    local center = drawing.points[shape.center]
    local dist = geom.dist(center.x,center.y, x,y)
    return dist > shape.radius*0.95 and dist < shape.radius*1.05
  elseif shape.mode == 'arc' then
    local center = drawing.points[shape.center]
    local dist = geom.dist(center.x,center.y, x,y)
    if dist < shape.radius*0.95 or dist > shape.radius*1.05 then
      return false
    end
    return geom.angle_between(center.x,center.y, x,y, shape.start_angle,shape.end_angle)
  elseif shape.mode == 'deleted' then
  else
    print(shape.mode)
    assert(false)
  end
end

function geom.on_freehand(x,y, drawing, shape)
  local prev
  for _,p in ipairs(shape.points) do
    if prev then
      if geom.on_line(x,y, drawing, {p1=prev, p2=p}) then
        return true
      end
    end
    prev = p
  end
  return false
end

function geom.on_line(x,y, drawing, shape)
  local p1,p2
  if type(shape.p1) == 'number' then
    p1 = drawing.points[shape.p1]
    p2 = drawing.points[shape.p2]
  else
    p1 = shape.p1
    p2 = shape.p2
  end
  if p1.x == p2.x then
    if math.abs(p1.x-x) > 2 then
      return false
    end
    local y1,y2 = p1.y,p2.y
    if y1 > y2 then
      y1,y2 = y2,y1
    end
    return y >= y1-2 and y <= y2+2
  end
  -- has the right slope and intercept
  local m = (p2.y - p1.y) / (p2.x - p1.x)
  local yp = p1.y + m*(x-p1.x)
  if yp < y-2 or yp > y+2 then
    return false
  end
  -- between endpoints
  local k = (x-p1.x) / (p2.x-p1.x)
  return k > -0.005 and k < 1.005
end

function geom.on_polygon(x,y, drawing, shape)
  local prev
  for _,p in ipairs(shape.vertices) do
    if prev then
      if geom.on_line(x,y, drawing, {p1=prev, p2=p}) then
        return true
      end
    end
    prev = p
  end
  return geom.on_line(x,y, drawing, {p1=shape.vertices[1], p2=shape.vertices[#shape.vertices]})
end

-- are (x3,y3) and (x4,y4) on the same side of the line between (x1,y1) and (x2,y2)
function geom.same_side(x1,y1, x2,y2, x3,y3, x4,y4)
  if x1 == x2 then
    return math.sign(x3-x1) == math.sign(x4-x1)
  end
  if y1 == y2 then
    return math.sign(y3-y1) == math.sign(y4-y1)
  end
  local m = (y2-y1)/(x2-x1)
  return math.sign(m*(x3-x1) + y1-y3) == math.sign(m*(x4-x1) + y1-y4)
end

function math.sign(x)
  if x > 0 then
    return 1
  elseif x == 0 then
    return 0
  elseif x < 0 then
    return -1
  end
end

function geom.angle_with_hint(x1, y1, x2, y2, hint)
  local result = geom.angle(x1,y1, x2,y2)
  if hint then
    -- Smooth the discontinuity where angle goes from positive to negative.
    -- The hint is a memory of which way we drew it last time.
    while result > hint+math.pi/10 do
      result = result-math.pi*2
    end
    while result < hint-math.pi/10 do
      result = result+math.pi*2
    end
  end
  return result
end

-- result is from -π/2 to 3π/2, approximately adding math.atan2 from Lua 5.3
-- (LÖVE is Lua 5.1)
function geom.angle(x1,y1, x2,y2)
  local result = math.atan((y2-y1)/(x2-x1))
  if x2 < x1 then
    result = result+math.pi
  end
  return result
end

-- is the line between x,y and cx,cy at an angle between s and e?
function geom.angle_between(ox,oy, x,y, s,e)
  local angle = geom.angle(ox,oy, x,y)
  if s > e then
    s,e = e,s
  end
  -- I'm not sure this is right or ideal..
  angle = angle-math.pi*2
  if s <= angle and angle <= e then
    return true
  end
  angle = angle+math.pi*2
  if s <= angle and angle <= e then
    return true
  end
  angle = angle+math.pi*2
  return s <= angle and angle <= e
end

function geom.dist(x1,y1, x2,y2) return ((x2-x1)^2+(y2-y1)^2)^0.5 end
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2024-09-02 20:14:05 +0000